@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/prompts.js

@@ -292,13 +292,16 @@ GOAL
   <one paragraph>
 
 CONSTRAINTS
-  - <bullet>
+  - <bullet> [from: Q<n>]   ← when the constraint comes from the Q&A answer numbered <n>
+  - <bullet> [from: spec]   ← when it comes from the refined task itself
   - …
 
 ACCEPTANCE
   - <human-readable success criterion>
   - …
 
+Every CONSTRAINTS bullet ends with a \`[from: …]\` tag naming where it came from: \`[from: Q3]\` if the Q&A's answer 3 is what states it, or \`[from: spec]\` if the refined task states it. Tag a bullet ONLY when you can point at that source — a constraint you inferred yourself carries no tag, and that is the correct answer, not a gap. The tag decides how much weight the verification gates give the constraint, so a tag that names a source which does not state it turns your inference into an unwaivable rule.
+
 VERIFY:
 \`\`\`sh
 <runnable shell command 1>
@@ -373,6 +376,7 @@ SCOPE RULES (equally critical — do not break these):
 - Do NOT introduce new requirements, deliverables, files, scripts, hooks, configs, or acceptance criteria that are not explicitly implied by the refined task or the Q&A.
 - Do NOT broaden scope. If the refined task says "run X and report", do not turn it into "build a toolchain around X with hooks, docs, and reports".
 - CONSTRAINTS from the refined task MUST be preserved in spirit. Do not silently drop or weaken them.
+- Keep each CONSTRAINTS bullet's trailing \`[from: …]\` tag exactly as it stands, and do not add one to a bullet that has none. The tag is the constraint's provenance, and the verification gates weigh it; inventing or dropping one rewrites how binding the constraint is.
 - If the spec below is malformed, empty, or wrapped in a heredoc, reconstruct it from the refined task and Q&A — not from your own invention.
 - Your job is to tighten language, sharpen acceptance criteria, and ensure VERIFY is runnable. Not to redesign the task.
 - WIRING vs pinned facts: if the spec states interface wiring (a mount/route table, a module→path mapping, an exported signature, a file layout), reconcile EACH wiring specific against the design's pinned interface facts (the CROSS-SLICE CONTRACTS below, if present, are those facts quoted verbatim). Keep every wiring specific that reproduces the pinned facts exactly; CORRECT any that do not; and do NOT invent wiring the design leaves unspecified. Watch specifically for a "uniform" pattern (one module → one mount prefix, one naming scheme) applied to an interface whose pinned facts are NOT uniform — that is a seam bug, fix only the entry that breaks, and leave the conforming entries unchanged.
@@ -412,13 +416,20 @@ YOU MAY ONLY READ. Do NOT execute any of the listed commands, not even with --he
 Output exactly two sections:
 
 VERIFIED
-  <command>  <one-line evidence: where it was found>
+  <command>  <class>  <one-line evidence: where it was found>
   ...
 
 REJECTED
   <command>  <one-line reason it can't be confirmed>
   ...
 
+<class> is exactly one of:
+  check  — analyses and EXITS on its own (lint, typecheck, test, format --check)
+  build  — produces artifacts and EXITS on its own (build, compile, bundle)
+  serve  — starts a process that KEEPS RUNNING until killed (dev server, watch mode, repl)
+Any command that does not terminate by itself MUST be classed serve.
+Separate every column with TWO OR MORE spaces.
+
 Do not add other sections, preamble, or commentary.
 
 TOOLING (one command per line):

package/dist/task/qa-transcript.d.ts

@@ -38,6 +38,23 @@ export type QaKind =
  * gap — a human's own words are the baseline everything else is marked against.
  */
 export declare const QA_PROVENANCE: Record<QaKind, string>;
+/**
+ * Recover each answer's KIND from a rendered record, so a spec's `[from: Q3]`
+ * tag resolves to a provenance long after the dialog's own object is gone — at
+ * verify time the transcript exists only as the `## grill Q&A` text in the task
+ * file.
+ *
+ * Index IS the question number minus one, the same statement `_render` makes.
+ * An answer with no suffix is `typed`: that is what the empty-string row above
+ * declares, and it is also the honest reading of a record whose policy stamped
+ * nothing — the host cannot tell a human's words from an unstamped kind, and
+ * `typed` is the reading that does not invent a provenance.
+ *
+ * YOLO's two kinds share one stamp, so a YOLO answer resolves to `yolo`. They
+ * carry the same weight in `constraint-policy.ts`, which is the only question
+ * this resolution is asked.
+ */
+export declare function qaKindsFromRecord(record: string): Array<QaKind | undefined>;
 export interface QaPolicy {
     /** Kinds whose provenance appears in the RECORD — persisted, and handed on. */
     record: ReadonlySet<QaKind>;

package/dist/task/qa-transcript.js

@@ -31,6 +31,34 @@ export const QA_PROVENANCE = {
     accepted: '(accepted recommendation)',
     typed: ''
 };
+/**
+ * Recover each answer's KIND from a rendered record, so a spec's `[from: Q3]`
+ * tag resolves to a provenance long after the dialog's own object is gone — at
+ * verify time the transcript exists only as the `## grill Q&A` text in the task
+ * file.
+ *
+ * Index IS the question number minus one, the same statement `_render` makes.
+ * An answer with no suffix is `typed`: that is what the empty-string row above
+ * declares, and it is also the honest reading of a record whose policy stamped
+ * nothing — the host cannot tell a human's words from an unstamped kind, and
+ * `typed` is the reading that does not invent a provenance.
+ *
+ * YOLO's two kinds share one stamp, so a YOLO answer resolves to `yolo`. They
+ * carry the same weight in `constraint-policy.ts`, which is the only question
+ * this resolution is asked.
+ */
+export function qaKindsFromRecord(record) {
+    const kinds = [];
+    for (const line of record.split('\n')) {
+        const answer = /^A(\d+):\s*(.*)$/.exec(line);
+        if (!answer)
+            continue;
+        const text = answer[2].trimEnd();
+        const hit = Object.entries(QA_PROVENANCE).find(([, suffix]) => suffix.length > 0 && text.endsWith(suffix));
+        kinds[Number(answer[1]) - 1] = hit?.[0] ?? 'typed';
+    }
+    return kinds;
+}
 /**
  * GRILL: stamps `auto` and both YOLO kinds in the record, and shows the generator
  * nothing.

package/dist/task/question-source.d.ts

@@ -52,6 +52,17 @@ export interface QuestionRule {
     /** Applied only when the defect survived its one re-prompt. */
     repair?: (q: ClarifyQuestion) => ClarifyQuestion;
 }
+/**
+ * A decision the caller may SETTLE outside the dialog. The generator is
+ * stateless, so being told "already answered" in the transcript does not stop it
+ * re-drawing the same fork reworded; `match` is how the source recognises the
+ * re-draw and drops it.
+ */
+export interface QuestionTopic {
+    id: string;
+    /** Matched against the plain-text question. */
+    match: (plain: string) => boolean;
+}
 export interface QuestionSourceDeps {
     /**
      * Ask the model for the next question. `hint` is the corrective re-prompt to
@@ -64,6 +75,8 @@ export interface QuestionSourceDeps {
     /** Ordered quality rules. At most ONE fires per question: they share a single
      *  corrective re-prompt, spent by the first rule that detects a defect. */
     rules?: ReadonlyArray<QuestionRule>;
+    /** Topics `settle` can close. A topic the caller never settles costs nothing. */
+    topics?: ReadonlyArray<QuestionTopic>;
     cap?: number;
     log?: (msg: string) => void;
 }
@@ -81,11 +94,12 @@ export type NextQuestion = {
  *
  * The interface is one method. Behind it: the cap, the duplicate backstop and its
  * strike budget, the NONE-vs-unparseable distinction, `pickQuestion`, the one-shot
- * budget shared by every quality rule, and the hint precedence between a format
- * re-prompt and a duplicate re-prompt.
+ * budget shared by every quality rule, the hint precedence between a format
+ * re-prompt and a duplicate re-prompt, and the settled-topic filter.
  */
 export declare function makeQuestionSource(deps: QuestionSourceDeps): {
     next: () => Promise<NextQuestion>;
     asked: () => ReadonlyArray<string>;
     reopen: () => void;
+    settle: (topic: string) => void;
 };

package/dist/task/question-source.js

@@ -47,12 +47,14 @@ export function pickQuestion(parsed) {
  *
  * The interface is one method. Behind it: the cap, the duplicate backstop and its
  * strike budget, the NONE-vs-unparseable distinction, `pickQuestion`, the one-shot
- * budget shared by every quality rule, and the hint precedence between a format
- * re-prompt and a duplicate re-prompt.
+ * budget shared by every quality rule, the hint precedence between a format
+ * re-prompt and a duplicate re-prompt, and the settled-topic filter.
  */
 export function makeQuestionSource(deps) {
     const cap = deps.cap ?? MAX_DIALOG_QUESTIONS;
     const rules = deps.rules ?? [];
+    const topics = deps.topics ?? [];
+    const settled = new Set();
     const asked = [];
     let dupStrikes = 0;
     let dupHint = null;
@@ -92,12 +94,18 @@ export function makeQuestionSource(deps) {
             }
             let picked = pickQuestion(parsed);
             const plain = stripInlineMarkdown(picked.question);
-            // The duplicate backstop runs BEFORE any quality re-prompt: a question
-            // about to be discarded as a re-ask must not first buy itself an extra
-            // child call to be polished.
-            if (isDuplicateQuestion(asked, plain)) {
+            // A SETTLED topic is filtered here, ahead of both the dedupe backstop
+            // and any quality re-prompt: the caller has already recorded an answer,
+            // so this draw must not be shown, polished, or charged to the cap. It
+            // does spend a duplicate strike, because it IS one — a re-ask of a
+            // decision already in the transcript — and that budget is what stops a
+            // generator that can only redraw this fork from looping forever.
+            const settledTopic = topics.find(t => settled.has(t.id) && t.match(plain));
+            if (settledTopic || isDuplicateQuestion(asked, plain)) {
                 dupStrikes++;
-                deps.log?.(`duplicate question, strike ${dupStrikes}/${MAX_DUP_STRIKES}`);
+                deps.log?.(settledTopic ?
+                    `settled topic "${settledTopic.id}" re-asked, strike ${dupStrikes}/${MAX_DUP_STRIKES}`
+                    : `duplicate question, strike ${dupStrikes}/${MAX_DUP_STRIKES}`);
                 hint = null;
                 if (dupStrikes >= MAX_DUP_STRIKES)
                     return { kind: 'exhausted', why: 'dups' };
@@ -141,5 +149,10 @@ export function makeQuestionSource(deps) {
         dupStrikes = 0;
         dupHint = null;
     }
-    return { next, asked: () => asked, reopen };
+    /** Close a topic the caller answered itself. Idempotent; an unknown id is a
+     *  no-op, so a caller may settle a topic it declared nothing for. */
+    function settle(topic) {
+        settled.add(topic);
+    }
+    return { next, asked: () => asked, reopen, settle };
 }

package/dist/task/repo-health-check.d.ts

@@ -1,4 +1,21 @@
 import { type CommandRunner } from './command-run.js';
+/**
+ * What ONE discovered command did. `outcome` is `classifyCommandRun`'s verdict, so
+ * a tool that could not run at all is `skip` rather than a zero-exit pass.
+ *
+ * This exists for the DIFFERENTIAL (health-baseline.ts): "was the repo already
+ * failing?" is per command, not per overall verdict. Two runs can both be `ok:
+ * false` while a different command failed in each — a task that broke typecheck in
+ * a repo whose lint was already red — and the overall boolean calls that
+ * pre-existing.
+ */
+export interface HealthCommandResult {
+    /** The command line as run, e.g. `bun run lint`. The differential's join key. */
+    cmd: string;
+    outcome: 'pass' | 'fail' | 'skip';
+    /** Real exit status on a `fail`; null when nothing conclusive ran. */
+    exitCode: number | null;
+}
 export interface HealthOutcome {
     /** true → every discovered static check passed, or there was nothing to run.
      *  false → a discovered command actually ran and exited non-zero. */
@@ -7,6 +24,9 @@ export interface HealthOutcome {
     reason: string;
     /** Which manifest drove discovery, or null when none was found. */
     ecosystem: string | null;
+    /** Every command that was REACHED, in run order. The run short-circuits on the
+     *  first failure, so commands after it are absent rather than passing. */
+    commands: HealthCommandResult[];
     /**
      * First lines of the failing command's combined stderr+stdout — captured so a
      * FAIL is explainable from artifacts alone. The exit code alone does not say
@@ -20,6 +40,13 @@ export interface HealthOutcome {
 export declare function captureHealthOutput(stdout: string, stderr: string): string;
 /** One discovered command: the binary and its args, run from the repo root. */
 export type HealthCommand = [bin: string, args: string[]];
+/**
+ * Every file `discoverHealthCommands` consults. Exported because a verified
+ * command is only as good as the manifest that vouched for it: `manifestHash`
+ * (run-context.ts) hashes exactly this set, so a project that gains a `lint`
+ * script invalidates the run's tooling verdicts and nothing else does.
+ */
+export declare const HEALTH_MANIFEST_FILES: readonly ["package.json", "Makefile", "Cargo.toml", "pyproject.toml", "deno.json", "deno.jsonc", "go.mod"];
 /**
  * Discover the project's OWN whole-repo static-analysis commands. First manifest
  * that exists wins; returns only the STATIC commands actually available for that

package/dist/task/repo-health-check.js

@@ -66,6 +66,21 @@ function makeHasTarget(cwd, target) {
         return false;
     }
 }
+/**
+ * Every file `discoverHealthCommands` consults. Exported because a verified
+ * command is only as good as the manifest that vouched for it: `manifestHash`
+ * (run-context.ts) hashes exactly this set, so a project that gains a `lint`
+ * script invalidates the run's tooling verdicts and nothing else does.
+ */
+export const HEALTH_MANIFEST_FILES = [
+    'package.json',
+    'Makefile',
+    'Cargo.toml',
+    'pyproject.toml',
+    'deno.json',
+    'deno.jsonc',
+    'go.mod'
+];
 /**
  * Discover the project's OWN whole-repo static-analysis commands. First manifest
  * that exists wins; returns only the STATIC commands actually available for that
@@ -105,7 +120,13 @@ export function discoverHealthCommands(cwd) {
 }
 /** The nothing-to-run outcome, shared by both runners. */
 function noCommandOutcome(ecosystem) {
-    return { ok: true, reason: 'no repo-wide static-analysis command found', ecosystem, output: '' };
+    return {
+        ok: true,
+        reason: 'no repo-wide static-analysis command found',
+        ecosystem,
+        commands: [],
+        output: ''
+    };
 }
 /**
  * Run the discovered static checks whole-repo and let the real exit codes decide.
@@ -133,8 +154,10 @@ export async function runRepoHealthCheck(cwd, opts = {}) {
     if (!ecosystem || cmds.length === 0)
         return noCommandOutcome(ecosystem);
     const run = opts.run ?? spawnCommand;
+    const commands = [];
     for (const [bin, args] of cmds) {
-        opts.onCommand?.(`${bin} ${args.join(' ')}`);
+        const cmd = `${bin} ${args.join(' ')}`;
+        opts.onCommand?.(cmd);
         // Runner resolution: a PATH-stripped environment must not
         // silently skip the statics when the runner sits at a known install
         // location; the resolved dir also rides on PATH for the script chain.
@@ -158,14 +181,25 @@ export async function runRepoHealthCheck(cwd, opts = {}) {
         // English, so a genuine report quoting "browsers are not installed" would
         // skip the static check and certify the repo healthy.
         const verdict = classifyCommandRun(r, [], { runtimeGap: false });
-        if (verdict.outcome !== 'fail')
+        if (verdict.outcome !== 'fail') {
+            const passed = verdict.outcome === 'pass';
+            commands.push({ cmd, outcome: passed ? 'pass' : 'skip', exitCode: passed ? 0 : null });
             continue;
+        }
+        commands.push({ cmd, outcome: 'fail', exitCode: verdict.status });
         return {
             ok: false,
-            reason: `\`${bin} ${args.join(' ')}\` exited ${verdict.status}`,
+            reason: `\`${cmd}\` exited ${verdict.status}`,
             ecosystem,
+            commands,
             output: captureHealthOutput(r.stdout, r.stderr)
         };
     }
-    return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem, output: '' };
+    return {
+        ok: true,
+        reason: `${ecosystem}: static checks passed`,
+        ecosystem,
+        commands,
+        output: ''
+    };
 }

package/dist/task/requirements.d.ts

@@ -1,17 +1,38 @@
+import { type BlockKind, type SpecDoc } from './spec-doc.js';
 export interface RequirementEntry {
     /** The verbatim quote from the source doc — the obligation. */
     quote: string;
-    /** Where it came from (heading/section, or 'prose'). */
+    /** Where it came from (heading/section, or 'prose'). Model-authored. */
     anchor: string;
+    /** 1-based source line of the block it grounded in — the HOST's anchor. */
+    line?: number;
+    /** Grounded above the first heading, where a doc says what the thing IS. */
+    preamble?: boolean;
 }
+/**
+ * Which blocks may carry a requirement.
+ *
+ * The model still proposes whatever it likes; this decides what GROUNDING will
+ * accept. A fenced block is code or a file tree, and a table row is a grid of
+ * columns whose cells only read as a sentence by accident — both produced
+ * "requirements" like a DDL column definition or a router-table guard cell,
+ * which no task can own and which then held the coverage verdict INCOMPLETE.
+ */
+export interface RequirementPolicy {
+    candidateKinds: ReadonlySet<BlockKind>;
+    excludePreamble: boolean;
+}
+export declare const REQUIREMENT_POLICY: RequirementPolicy;
 export declare function requirementsFile(cwd: string): string;
 /** Parse `REQUIREMENT: "<quote>" [anchor: …]` lines (mirrors parseContractLines). */
 export declare function parseRequirementLines(text: string): RequirementEntry[];
-/** THE ANTI-SYNTHESIS GUARD: keep only entries whose quote is a normalised
- *  substring of the source doc (same rule as keepGroundedContracts). Does NOT
- *  cap — capping is capRequirements' job, which protects obligation-marked
- *  passages from doc-order truncation. */
-export declare function keepGroundedRequirements(entries: RequirementEntry[], sourceDoc: string): RequirementEntry[];
+/** THE ANTI-SYNTHESIS GUARD: keep only entries whose quote grounds in a CANDIDATE
+ *  block of the source doc (same rule as keepGroundedContracts, narrowed by the
+ *  policy). A quote whose only match lies in an excluded block is dropped — the
+ *  model is free to propose it, the document decides. Does NOT cap — capping is
+ *  capRequirements' job, which protects obligation-marked passages from doc-order
+ *  truncation. */
+export declare function keepGroundedRequirements(entries: RequirementEntry[], sourceDoc: string | SpecDoc, policy?: RequirementPolicy): RequirementEntry[];
 /**
  * Bound the list WITHOUT doc-order truncation. An extractor that works top-down
  * yields more entries than the cap from the doc's early sections alone, so a
@@ -48,7 +69,7 @@ export declare function isLowValueQuote(quote: string): boolean;
  * uncoveredPassages() below turns "a marked passage produced no quote" into hard
  * evidence for one forced re-extraction.
  */
-export declare function enumerateObligationPassages(doc: string): string[];
+export declare function enumerateObligationPassages(doc: string | SpecDoc, policy?: RequirementPolicy): string[];
 /** Marked passages none of the kept quotes came from — the hard evidence that
  *  extraction recall failed there (a kept quote "covers" a passage when the
  *  passage contains it, normalised). */
@@ -67,6 +88,23 @@ export type ReqMapping = {
 } | {
     kind: 'none';
 };
+export type RequirementClass = 'prohibition' | 'global-policy' | 'descriptive' | 'ownable';
+/**
+ * `descriptive` is the class the coverage loop must not chase: a line that says
+ * what the product IS rather than what the work must do. It cost two whole
+ * rejected decompose rounds live — "Invite-only used-parts marketplace for a
+ * local Mazda MX-5 club." was extracted as a requirement, mapped NONE by every
+ * round because no task delivers a sentence, and held the verdict INCOMPLETE.
+ *
+ * Both marks are required, not either: preamble POSITION (above every heading,
+ * where a spec states its subject) and the absence of any modal. A preamble
+ * sentence that does carry a modal is a real obligation stated up front, and a
+ * modal-free sentence anywhere else is the ordinary shape of a feature statement
+ * — treating either alone as descriptive would empty the coverage gate.
+ */
+export declare function classifyRequirement(quote: string, fromPreamble?: boolean): RequirementClass;
+/** A requirement no single task can ever OWN, judged on the quote alone — the
+ *  shape `groundedCoverage` and the granularity floor get. */
 export declare function isCrossCuttingRequirement(quote: string): boolean;
 /** Requirement INDICES a task owns (a `TASK n` verdict), the monotonic-replacement
  *  signal (coverage-loop.ts). Index-aligned with the requirements list. */
@@ -125,9 +163,15 @@ export interface OwnedRequirement {
     /** The verbatim design quote (the obligation). */
     quote: string;
     anchor: string;
-    /** The plan title of the task the coverage map assigned it to — matched
-     *  against the executing task's title at phase time (ids don't exist yet at
-     *  plan time, and spliced repair tasks shift them). */
+    /**
+     * The plan key (`TaskEntry.key`) of the task the coverage map assigned it to —
+     * the join. Allocated at plan time and stable under every later rewrite of the
+     * title. Absent on a ledger written before keys existed, which still joins on
+     * the title.
+     */
+    key?: string;
+    /** The plan title of the owning task. Display and legacy join only — a title
+     *  is prose, and a task that rewords its own is still the same task. */
     title: string;
     /**
      * DETACHED: the files this obligation
@@ -149,10 +193,20 @@ export declare function readOwnedRequirements(cwd: string): Promise<OwnedRequire
 export declare function parseOwnedRequirements(text: string): OwnedRequirement[];
 /** The owned entries whose plan title matches THIS task's title (normalised
  *  equality — titles travel verbatim from the plan list into task creation;
- *  spliced repair tasks simply match nothing). A DETACHED entry (`pending`) is
- *  owned by nobody until a task claims it, so it is never returned here — its
- *  `title` is provenance, not ownership. */
+ *  spliced repair tasks simply match nothing). */
 export declare function ownedForTitle(owned: OwnedRequirement[], title: string): OwnedRequirement[];
+/** The owned entries assigned to THIS task's plan entry. */
+export declare function ownedForKey(owned: OwnedRequirement[], key: string): OwnedRequirement[];
+/**
+ * THIS task's owned entries. The key is the join; the title is the fallback for a
+ * ledger written before keys existed, and only then — once ANY entry carries a
+ * key the ledger is a keyed one, and a task the plan did not key (a spliced
+ * repair step) owns nothing, which is the same answer the title join gave it.
+ */
+export declare function ownedForTask(owned: OwnedRequirement[], join: {
+    key?: string;
+    title: string;
+}): OwnedRequirement[];
 /** The injection block for a task's OWN mapped obligations. Mirrors
  *  buildRequirementsBlock (the directive pattern that measurably works) but is
  *  singular in address: these are not "wherever they touch", they ARE this