@intentic/sandbox-contract 1.170.0 → 1.171.0

package/src/chores/digest.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "vitest";
+import { bucketOf, digestOf } from "./digest.js";
+
+describe(`digestOf`, () => {
+    test(`is stable for the same parts and different for different ones`, () => {
+        expect(digestOf(`a`, `b`)).toBe(digestOf(`a`, `b`));
+        expect(digestOf(`a`, `b`)).not.toBe(digestOf(`b`, `a`));
+        expect(digestOf(`a`)).not.toBe(digestOf(`aa`));
+    });
+
+    test(`is short enough to sit in a JSON ledger without anyone minding`, () => {
+        expect(digestOf(`x`.repeat(10_000)).length).toBeLessThanOrEqual(8);
+    });
+});
+
+/* The anti-drift mechanism. A chore that counts things must not mint a new digest — and therefore a new badge —
+ * every time an ordinary day's work moves the number by one. Buckets widen with the count, because the difference
+ * between one and two matters and the difference between four hundred and five hundred does not. */
+describe(`bucketOf`, () => {
+    test(`absorbs drift and keeps the moves that mean something`, () => {
+        expect(bucketOf(12)).toBe(bucketOf(13));
+        expect(bucketOf(12)).not.toBe(bucketOf(40));
+        expect(bucketOf(1)).not.toBe(bucketOf(2));
+        expect(bucketOf(400)).toBe(bucketOf(500));
+    });
+
+    test(`nothing is its own bucket, so a chore's first finding of a kind is always news`, () => {
+        expect(bucketOf(0)).not.toBe(bucketOf(1));
+    });
+});

package/src/chores/index.ts

@@ -0,0 +1,9 @@
+export { CHORES, choreAutomationPrompt, choreById, chorePrompt, repoLabel } from "./chores.js";
+export type { Chore, ChoreContext, ChoreFinding, ChoreStance } from "./chores.js";
+export { bucketOf, digestOf } from "./digest.js";
+export { CHORE_INVARIANTS, composeAsk, REFACTOR_INVARIANTS, REPORT_INVARIANTS, TRIAGE_NOTE } from "./prompt.js";
+export type { Ask } from "./prompt.js";
+export { PROBES, probeSpec } from "./probes.js";
+export type { ProbeSpec } from "./probes.js";
+export { assessChore, assessReport, ledgerKey, unseenVerdicts } from "./verdict.js";
+export type { ChoreState, ChoreVerdict } from "./verdict.js";

package/src/chores/probes.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "vitest";
+import { probeSpec } from "./probes.js";
+
+/* The parsers are the part of this library that faces someone else's output, so they are tested the way that
+ * output actually arrives: real shapes, then the shapes that have historically broken things — a tool that
+ * printed a warning line before its JSON, a version whose fields moved, an empty run. The bar for every one of
+ * them is the same: recognise it, or return undefined so the runner can record a failure. Never throw, and never
+ * report a clean result from output it did not understand. */
+
+const parse = (id: Parameters<typeof probeSpec>[0], stdout: string) => probeSpec(id).parse(stdout);
+
+describe(`outdated`, () => {
+    test(`reads pnpm's name → {current, latest} map and classifies the semver step`, () => {
+        const facts = parse(
+            `outdated`,
+            JSON.stringify({
+                vue: { current: `3.4.1`, latest: `4.0.0`, dependencyType: `dependencies` },
+                vitest: { current: `2.1.0`, latest: `2.3.4`, dependencyType: `devDependencies` },
+                zod: { current: `4.4.3`, latest: `4.4.9`, dependencyType: `dependencies` },
+            }),
+        );
+        expect(facts).toEqual({
+            id: `outdated`,
+            packages: [
+                { name: `vue`, current: `3.4.1`, latest: `4.0.0`, kind: `major`, section: `dependencies` },
+                { name: `vitest`, current: `2.1.0`, latest: `2.3.4`, kind: `minor`, section: `devDependencies` },
+                { name: `zod`, current: `4.4.3`, latest: `4.4.9`, kind: `patch`, section: `dependencies` },
+            ],
+        });
+    });
+
+    test(`skips entries pnpm could not resolve, rather than inventing a version for them`, () => {
+        const facts = parse(`outdated`, JSON.stringify({ ok: { current: `1.0.0`, latest: `2.0.0` }, broken: { current: `1.0.0` }, alsoBroken: null }));
+        expect(facts).toEqual({ id: `outdated`, packages: [{ name: `ok`, current: `1.0.0`, latest: `2.0.0`, kind: `major`, section: `dependencies` }] });
+    });
+
+    // pnpm prints deprecation and lockfile notices on the same stream in some versions; the JSON still has to be
+    // found. This is the single most common reason a parser like this silently reports "clean".
+    test(`finds the JSON after a leading warning line`, () => {
+        expect(parse(`outdated`, ` WARN  Ignoring broken lockfile\n{"vue":{"current":"1.0.0","latest":"2.0.0"}}`)).toEqual({
+            id: `outdated`,
+            packages: [{ name: `vue`, current: `1.0.0`, latest: `2.0.0`, kind: `major`, section: `dependencies` }],
+        });
+    });
+
+    test(`an empty report is no packages, not a failure`, () => {
+        expect(parse(`outdated`, `{}`)).toEqual({ id: `outdated`, packages: [] });
+    });
+
+    test(`output that is not JSON at all is a failure, never a clean result`, () => {
+        expect(parse(`outdated`, `ERR_PNPM_NO_LOCKFILE  Cannot proceed`)).toBeUndefined();
+    });
+});
+
+describe(`audit`, () => {
+    const advisory = (over: Record<string, unknown>) => ({
+        module_name: `left-pad`,
+        severity: `high`,
+        title: `Prototype pollution`,
+        patched_versions: `>=1.3.0`,
+        findings: [{ dev: false }],
+        ...over,
+    });
+
+    test(`carries which package, how bad, and whether a fix exists`, () => {
+        expect(parse(`audit`, JSON.stringify({ advisories: { "1": advisory({}) } }))).toEqual({
+            id: `audit`,
+            advisories: [{ name: `left-pad`, severity: `high`, title: `Prototype pollution`, patched: `>=1.3.0`, dev: false }],
+        });
+    });
+
+    // "<0.0.0" is npm's spelling of "no version fixes this". Treating it as a range would have the chore promise
+    // a bump that cannot be made, which is the one thing a security prompt must not do.
+    test(`treats "<0.0.0" as no patch published`, () => {
+        const facts = parse(`audit`, JSON.stringify({ advisories: { "1": advisory({ patched_versions: `<0.0.0` }) } }));
+        expect(facts).toEqual({ id: `audit`, advisories: [expect.not.objectContaining({ patched: expect.anything() })] });
+    });
+
+    test(`an advisory is dev-only only when every finding is`, () => {
+        const mixed = parse(`audit`, JSON.stringify({ advisories: { "1": advisory({ findings: [{ dev: true }, { dev: false }] }) } }));
+        const devOnly = parse(`audit`, JSON.stringify({ advisories: { "1": advisory({ findings: [{ dev: true }, { dev: true }] }) } }));
+        expect(mixed).toMatchObject({ advisories: [{ dev: false }] });
+        expect(devOnly).toMatchObject({ advisories: [{ dev: true }] });
+    });
+
+    test(`a report with no advisories key is clean, not unparseable`, () => {
+        expect(parse(`audit`, JSON.stringify({ metadata: { vulnerabilities: { high: 0 } } }))).toEqual({ id: `audit`, advisories: [] });
+    });
+});
+
+describe(`knip`, () => {
+    test(`sums the per-file issue arrays and samples the wholly unreferenced files`, () => {
+        const facts = parse(
+            `knip`,
+            JSON.stringify({
+                issues: [
+                    { file: `src/a.ts`, exports: [{ name: `x` }, { name: `y` }], types: [{ name: `T` }], dependencies: [{ name: `lodash` }], devDependencies: [], files: [] },
+                    { file: `src/b.ts`, exports: [{ name: `z` }], types: [], dependencies: [], devDependencies: [{ name: `jest` }], files: [] },
+                    { file: `src/old.ts`, exports: [], files: [{ name: `src/old.ts` }] },
+                    { file: `src/older.ts`, exports: [], files: [{ name: `src/older.ts` }] },
+                ],
+            }),
+        );
+        expect(facts).toEqual({
+            id: `knip`,
+            deadCode: { files: 2, exports: 3, types: 1, dependencies: 1, devDependencies: 1, sample: [`src/old.ts`, `src/older.ts`] },
+        });
+    });
+
+    test(`missing per-kind arrays count as zero rather than throwing`, () => {
+        expect(parse(`knip`, JSON.stringify({ issues: [{ file: `src/a.ts` }, null] }))).toMatchObject({
+            deadCode: { files: 0, exports: 0, types: 0, dependencies: 0, devDependencies: 0, sample: [] },
+        });
+    });
+
+    // A clean run still prints the envelope, and an empty one is the answer that keeps the chore quiet.
+    test(`an empty issue list is a clean repository, not an unrecognisable one`, () => {
+        expect(parse(`knip`, JSON.stringify({ issues: [] }))).toEqual({
+            id: `knip`,
+            deadCode: { files: 0, exports: 0, types: 0, dependencies: 0, devDependencies: 0, sample: [] },
+        });
+    });
+
+    // Without an `issues` array this is not knip's report, whatever else it contains — and reporting zero dead code
+    // from a shape we do not recognise is exactly the lie the state machine exists to prevent.
+    test(`a shape without an issues array is a failure`, () => {
+        expect(parse(`knip`, JSON.stringify({ files: [`src/old.ts`] }))).toBeUndefined();
+    });
+});
+
+describe(`jscpd`, () => {
+    test(`takes the percentage of scanned lines and the biggest clones, longest first`, () => {
+        const facts = parse(
+            `jscpd`,
+            JSON.stringify({
+                statistics: { total: { percentage: 7.4, lines: 1000 } },
+                duplicates: [
+                    { lines: 12, firstFile: { name: `a.ts` }, secondFile: { name: `b.ts` } },
+                    { lines: 40, firstFile: { name: `c.ts` }, secondFile: { name: `d.ts` } },
+                ],
+            }),
+        );
+        expect(facts).toEqual({
+            id: `jscpd`,
+            duplication: {
+                percentage: 7.4,
+                clones: 2,
+                top: [
+                    { lines: 40, first: `c.ts`, second: `d.ts` },
+                    { lines: 12, first: `a.ts`, second: `b.ts` },
+                ],
+            },
+        });
+    });
+
+    test(`a clean run reports zero percent with no clones`, () => {
+        expect(parse(`jscpd`, JSON.stringify({ statistics: { total: { percentage: 0 } }, duplicates: [] }))).toMatchObject({
+            duplication: { percentage: 0, clones: 0, top: [] },
+        });
+    });
+
+    // jscpd writes its report to a file; when the run dies the `cat` in the command prints nothing at all.
+    test(`no output at all is a failure`, () => {
+        expect(parse(`jscpd`, ``)).toBeUndefined();
+    });
+});

package/src/chores/probes.ts

@@ -0,0 +1,273 @@
+import type { Advisory, DeadCode, Duplication, OutdatedPackage, ProbeFacts, ProbeId } from "../schemas.js";
+
+/* THE PROBES — the measurements that cost a subprocess, declared once so the daemon that runs them and the panel
+ * that explains them cannot disagree about what "outdated" meant.
+ *
+ * A spec is a shell command and a parser, deliberately in that order of trust: the command is whatever the tool's
+ * own maintainers publish as its machine-readable output, and the parser is written to be DISAPPOINTED. Every one
+ * of these tools has changed its JSON shape at least once, they are run against whatever version the repo pinned,
+ * and a probe that throws on an unexpected field would take the whole maintenance surface down with it. So each
+ * parser walks the structure defensively and returns `undefined` when it cannot recognise what it got — which the
+ * runner records as a failed probe with the output attached, rather than as a clean repository.
+ *
+ * TIERS ARE ABOUT COST, and the cost is what sets the cadence. Tier 1 reads metadata that already exists (a
+ * lockfile, a registry's version list) and finishes in seconds, so the background runner refreshes it daily. Tier
+ * 2 reads the whole tree — knip type-checks it, jscpd tokenizes every file — and can run for minutes on a large
+ * repo, so it refreshes weekly and says how long it took, because a reader deciding whether to force a refresh
+ * deserves to know what they are asking for.
+ *
+ * THE `available` COMMAND IS NOT AN AFTERTHOUGHT. "knip is not a devDependency of this repo" and "knip found no
+ * dead code" are opposite facts that a bare exit code cannot tell apart, and collapsing them is how a maintenance
+ * panel ends up reporting a green repository it has never measured. Non-zero here means unmeasured, and an
+ * unmeasured chore renders greyed and can never light the rail. */
+
+const HOUR_MS = 3_600_000;
+const DAY_MS = 24 * HOUR_MS;
+
+export interface ProbeSpec {
+    readonly id: ProbeId;
+    readonly title: string;
+    // What the reader is told this measures, in the panel, next to its age.
+    readonly measures: string;
+    readonly tier: 1 | 2;
+    // How long a result stays fresh. The background runner refreshes anything older; the panel's per-probe
+    // refresh button ignores it.
+    readonly ttlMs: number;
+    readonly timeoutMs: number;
+    // Exit 0 ⇒ this repo can be measured. Runs in the repo's own directory, like the command.
+    readonly available: string;
+    // `sh -c`, in the repo's directory. Stdout is the parser's input; a non-zero exit is NOT a failure by itself
+    // (pnpm outdated and pnpm audit both exit non-zero precisely when they have something to report), so the
+    // runner judges by whether the parser recognised the output.
+    readonly command: string;
+    readonly parse: (stdout: string) => ProbeFacts | undefined;
+}
+
+// A parsed JSON object, or undefined for anything else. Every parser starts here, so "the tool printed a warning
+// before its JSON" and "the tool printed nothing" both land on the same honest answer instead of throwing.
+const asObject = (text: string): Record<string, unknown> | undefined => {
+    const start = text.indexOf(`{`);
+    if (start === -1) {
+        return undefined;
+    }
+    try {
+        const parsed: unknown = JSON.parse(text.slice(start));
+        return typeof parsed === `object` && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const asString = (value: unknown): string | undefined => (typeof value === `string` && value !== `` ? value : undefined);
+const countOf = (value: unknown): number => (Array.isArray(value) ? value.length : 0);
+
+// Which semver step separates two versions. Compared as leading integers rather than by a semver library: the
+// only question is which position first differs, and prerelease/build metadata cannot change that answer.
+const versionParts = (version: string): number[] => version.replace(/^[^\d]*/, ``).split(`.`).map((part) => Number.parseInt(part, 10) || 0);
+
+const semverKind = (current: string, latest: string): OutdatedPackage["kind"] => {
+    const [currentMajor = 0, currentMinor = 0] = versionParts(current);
+    const [latestMajor = 0, latestMinor = 0] = versionParts(latest);
+    if (latestMajor !== currentMajor) {
+        return `major`;
+    }
+    return latestMinor !== currentMinor ? `minor` : `patch`;
+};
+
+/* `pnpm outdated --json` prints a map of package name → { current, latest, dependencyType }. In a workspace the
+ * recursive form merges every package's entries into the same map and adds `dependentPackages`, which is why this
+ * reads the map rather than expecting a list: one shape covers both, and a field we don't use appearing is not a
+ * parse failure. Entries missing `current` or `latest` are skipped — that is how pnpm reports a package it could
+ * not resolve against the registry, and it is not evidence of anything. */
+const parseOutdated = (stdout: string): ProbeFacts | undefined => {
+    const root = asObject(stdout);
+    if (root === undefined) {
+        return undefined;
+    }
+    const packages: OutdatedPackage[] = [];
+    for (const [name, raw] of Object.entries(root)) {
+        if (typeof raw !== `object` || raw === null) {
+            continue;
+        }
+        const entry = raw as Record<string, unknown>;
+        const current = asString(entry[`current`]);
+        const latest = asString(entry[`latest`]);
+        if (current === undefined || latest === undefined || current === latest) {
+            continue;
+        }
+        packages.push({ name, current, latest, kind: semverKind(current, latest), section: asString(entry[`dependencyType`]) ?? `dependencies` });
+    }
+    return { id: `outdated`, packages };
+};
+
+const SEVERITIES = new Set([`critical`, `high`, `moderate`, `low`, `info`]);
+
+/* `pnpm audit --json` prints `{ advisories: { <id>: {...} }, metadata: {...} }`. The metadata's counts are
+ * deliberately ignored: they are a tally, and this surface needs the advisories themselves — which package, and
+ * whether a patched range exists — because "there is a fix that is a version bump" and "there is no patch yet"
+ * lead to completely different turns, and a count cannot tell them apart.
+ *
+ * `dev` comes off the findings' own flag rather than being inferred. A build-time-only advisory is real but it is
+ * not the same risk as one in a running service, and the chore's prompt says so instead of treating them alike. */
+const parseAudit = (stdout: string): ProbeFacts | undefined => {
+    const root = asObject(stdout);
+    if (root === undefined) {
+        return undefined;
+    }
+    const raw = root[`advisories`];
+    // No `advisories` key at all is pnpm's clean report — an empty list, not an unrecognisable one.
+    if (raw === undefined) {
+        return { id: `audit`, advisories: [] };
+    }
+    if (typeof raw !== `object` || raw === null) {
+        return undefined;
+    }
+    const advisories: Advisory[] = [];
+    for (const value of Object.values(raw as Record<string, unknown>)) {
+        if (typeof value !== `object` || value === null) {
+            continue;
+        }
+        const entry = value as Record<string, unknown>;
+        const name = asString(entry[`module_name`]);
+        const severity = asString(entry[`severity`]);
+        if (name === undefined || severity === undefined || !SEVERITIES.has(severity)) {
+            continue;
+        }
+        const patched = asString(entry[`patched_versions`]);
+        const findings = Array.isArray(entry[`findings`]) ? (entry[`findings`] as Record<string, unknown>[]) : [];
+        advisories.push({
+            name,
+            severity: severity as Advisory["severity"],
+            title: asString(entry[`title`]) ?? name,
+            // "<0.0.0" is npm's spelling of "no patch exists", and treating it as a fixing range would have the
+            // chore promise a bump that cannot be made.
+            ...(patched === undefined || patched === `<0.0.0` ? {} : { patched }),
+            dev: findings.length > 0 && findings.every((finding) => finding[`dev`] === true),
+        });
+    }
+    return { id: `audit`, advisories };
+};
+
+/* knip's JSON reporter prints `{ issues: [...] }` — one row per file that has findings, carrying a per-kind array
+ * of what it found there. A wholly unreferenced file is a row whose own `files` array names it, which is why that
+ * count is a sum like every other kind rather than a list of its own. Counts plus a sample of the file paths, not
+ * the full list: the agent re-runs knip itself against the live tree (a list from a probe hours old would send it
+ * at files that are already gone), so what travels here only has to be enough to decide whether the turn is worth
+ * starting. */
+const DEAD_CODE_SAMPLE = 8;
+
+const parseKnip = (stdout: string): ProbeFacts | undefined => {
+    const raw = asObject(stdout)?.[`issues`];
+    // `issues` is the whole report in this reporter, so its absence means we are not reading knip's output at all.
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const issues = raw.filter((issue): issue is Record<string, unknown> => typeof issue === `object` && issue !== null);
+    const sum = (key: string): number => issues.reduce((total, issue) => total + countOf(issue[key]), 0);
+    const deadCode: DeadCode = {
+        files: sum(`files`),
+        exports: sum(`exports`),
+        types: sum(`types`),
+        dependencies: sum(`dependencies`),
+        devDependencies: sum(`devDependencies`),
+        sample: issues.flatMap((issue) => (countOf(issue[`files`]) === 0 ? [] : (asString(issue[`file`]) ?? []))).slice(0, DEAD_CODE_SAMPLE),
+    };
+    return { id: `knip`, deadCode };
+};
+
+/* jscpd writes its JSON to a file rather than stdout, which is why the command below ends in a `cat`. The report
+ * carries `statistics[`total`].percentage` (of scanned lines) and a `duplicates` array; the percentage is what a
+ * threshold is worth setting against, because a clone COUNT grows with the repository and would mean something
+ * different every quarter. */
+const DUPLICATION_SAMPLE = 5;
+
+const parseJscpd = (stdout: string): ProbeFacts | undefined => {
+    const root = asObject(stdout);
+    const statistics = root?.[`statistics`];
+    if (typeof statistics !== `object` || statistics === null) {
+        return undefined;
+    }
+    const total = (statistics as Record<string, unknown>)[`total`];
+    const percentage = typeof total === `object` && total !== null ? (total as Record<string, unknown>)[`percentage`] : undefined;
+    const duplicates = Array.isArray(root?.[`duplicates`]) ? (root[`duplicates`] as Record<string, unknown>[]) : [];
+    const pathOf = (side: unknown): string => (typeof side === `object` && side !== null ? (asString((side as Record<string, unknown>)[`name`]) ?? `?`) : `?`);
+    const duplication: Duplication = {
+        percentage: typeof percentage === `number` ? percentage : 0,
+        clones: duplicates.length,
+        top: duplicates
+            .map((clone) => ({ lines: typeof clone[`lines`] === `number` ? clone[`lines`] : 0, first: pathOf(clone[`firstFile`]), second: pathOf(clone[`secondFile`]) }))
+            .toSorted((left, right) => right.lines - left.lines)
+            .slice(0, DUPLICATION_SAMPLE),
+    };
+    return { id: `jscpd`, duplication };
+};
+
+// Where the tier-2 tools leave their reports. Under /tmp because they are inputs to a parse that happens
+// immediately after, never something to keep — the cached ProbeResult is the artefact that survives. The same
+// path the scheduled form of this chore uses (chores.ts), so a workspace running both keeps one copy.
+const JSCPD_DIR = `/tmp/intentic-chore-jscpd`;
+
+export const PROBES: readonly ProbeSpec[] = [
+    {
+        id: `outdated`,
+        title: `Dependency versions`,
+        measures: `how far behind the registry each dependency is`,
+        tier: 1,
+        ttlMs: DAY_MS,
+        timeoutMs: 5 * 60_000,
+        available: `test -f package.json`,
+        // `-r` so a monorepo reports every workspace package, not just the root's own handful. `|| true` because
+        // pnpm exits non-zero exactly when it HAS findings, and the runner judges by whether the parse succeeded.
+        command: `pnpm outdated -r --json 2>/dev/null || true`,
+        parse: parseOutdated,
+    },
+    {
+        id: `audit`,
+        title: `Security advisories`,
+        measures: `published advisories against this dependency tree`,
+        tier: 1,
+        ttlMs: DAY_MS,
+        timeoutMs: 5 * 60_000,
+        // A lockfile, not a package.json: auditing resolves the actual installed tree, and without one pnpm
+        // reports against nothing.
+        available: `test -f pnpm-lock.yaml || test -f package-lock.json`,
+        command: `pnpm audit --json 2>/dev/null || true`,
+        parse: parseAudit,
+    },
+    {
+        id: `knip`,
+        title: `Unreachable code`,
+        measures: `files, exports and dependencies nothing references`,
+        tier: 2,
+        ttlMs: 7 * DAY_MS,
+        timeoutMs: 15 * 60_000,
+        // The repo's OWN knip, never a floating one: `pnpm dlx knip` would download a version that disagrees with
+        // the repo's knip.json about what counts as an entry point, and then report its whole public API as dead.
+        available: `pnpm exec knip --version >/dev/null 2>&1`,
+        command: `pnpm exec knip --reporter json --no-exit-code 2>/dev/null || true`,
+        parse: parseKnip,
+    },
+    {
+        id: `jscpd`,
+        title: `Copy-paste`,
+        measures: `how much of the tree is duplicated elsewhere in it`,
+        tier: 2,
+        ttlMs: 7 * DAY_MS,
+        timeoutMs: 20 * 60_000,
+        available: `test -f package.json`,
+        // `--threshold 100` so jscpd never fails the command on its own opinion of what is too much duplication —
+        // that judgement is the chore's, made from the percentage, not the tool's exit code.
+        command:
+            `pnpm dlx jscpd --reporters json --output ${JSCPD_DIR} --min-lines 12 --threshold 100 . >/dev/null 2>&1; ` +
+            `cat ${JSCPD_DIR}/jscpd-report.json 2>/dev/null`,
+        parse: parseJscpd,
+    },
+];
+
+export const probeSpec = (id: ProbeId): ProbeSpec => {
+    const spec = PROBES.find((probe) => probe.id === id);
+    if (spec === undefined) {
+        throw new Error(`chores: no probe named "${id}"`);
+    }
+    return spec;
+};

package/src/chores/prompt.ts

@@ -0,0 +1,64 @@
+/* HOW WE ASK. Every prompt this workspace generates from a measurement — a hotspot's refactor, a chore's sweep —
+ * has the same four parts, in the same order, for the same reasons:
+ *
+ *   subject    the one line that says what is being worked on. First, because a model that reads the rationale
+ *              before the target starts planning against a subject it has not been told yet.
+ *   why        the NUMBERS, quoted exactly as the panel shows them, then what they mean. Exact so the agent and
+ *              the person are arguing about one set of facts; the agent can and should recount them.
+ *   goal       what shape to move towards — never a design. Whoever generated this prompt has not read the code,
+ *              so a prescribed solution from out here is a guess wearing an instruction's clothes.
+ *   done       falsifiable, and checkable by the agent itself. The same resident engine that produced the
+ *              measurement answers `iq` in the agent's own worktree, so "run it again and see" is available and
+ *              "I have finished" is not something it has to be taken at its word on.
+ *
+ * The invariants sit between goal and done because they are the constraints on HOW, and they are stated in full
+ * every time rather than assumed. Each one is a specific way the turn fails without it — they are here because
+ * they were each learned from a diff nobody could review. */
+
+export interface Ask {
+    readonly subject: string;
+    readonly why: string;
+    readonly diagnosis: string;
+    readonly goal: string;
+    readonly invariants: string;
+    readonly done: string;
+}
+
+export const composeAsk = ({ subject, why, diagnosis, goal, invariants, done }: Ask): string =>
+    [subject, `Why: ${why} ${diagnosis}`, goal, `${invariants} ${done}`].join(`\n\n`);
+
+/* Said to every turn a TOOL woke, and the reason the maintenance surface can point agents at tool output at all.
+ * A tool reporting N findings is not reporting N problems: knip is confidently wrong about anything reachable
+ * from outside the repo, jscpd counts generated files, an advisory in a build-time dependency is not the same
+ * risk as one in a running service. A chore that mechanically actions the whole list is worse than no chore —
+ * it makes noisy, confident, wrong changes at three in the morning, and the next person has to review a diff
+ * whose author had no opinion about it. */
+export const TRIAGE_NOTE =
+    `The measurement woke you; it did not decide anything. Read the repository before you touch it, and treat every ` +
+    `finding as a claim to verify rather than a task to execute. If a finding is wrong, say why in one line and leave ` +
+    `it — a run that verifies ten and fixes two is a good run.`;
+
+/* The invariants for a turn that CHANGES things. Whatever it does lands as uncommitted work in the owner's
+ * workspace, so it is reviewed as one diff by someone who did not watch it happen — which is what every clause
+ * here is protecting.
+ *
+ * "Separately explainable" is doing the most work: a chore that fixes its findings AND tidies what it passed on
+ * the way produces a diff whose reviewer cannot tell which changes were the point. */
+export const CHORE_INVARIANTS =
+    `Keep it mechanical and separately explainable: nothing lands that you could not justify on its own line of the ` +
+    `summary. Do not reformat, rename or "while I was in here" anything the finding did not name. Run the repository's ` +
+    `own type-check and tests before you finish, and if you cannot make them pass, leave the change out and say so.`;
+
+// The invariants for a turn that only LOOKS. Separate from the above rather than a flag on it, because the failure
+// mode is the opposite one: a report-stance chore that quietly starts editing is the single most surprising thing
+// this surface could do, and it has to be forbidden in words rather than by omission.
+export const REPORT_INVARIANTS =
+    `Change nothing. This is a survey: the output is your findings, cited file:line, and a recommendation the owner ` +
+    `can act on or dismiss. Where you would propose an edit, describe it and where it would go instead of making it.`;
+
+/* The invariants for a turn refactoring ONE FILE, as the codebase-health panel's rows ask for. Distinct from the
+ * chore ones because the blast radius is the thing at stake: named as a radius rather than "only this file",
+ * since half those archetypes ask for new files and must not read as forbidding them. */
+export const REFACTOR_INVARIANTS =
+    `Read it first. Behaviour stays identical, and the blast radius is this file, whatever it splits into, and the ` +
+    `importers that must follow — no re-export shims left behind.`;