@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/chores/probes.ts

@@ -12,26 +12,11 @@ import {
 } from "./stack.js";
 import { WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG, WORKSPACE_ROOT_RG_EXCLUDE_ARG } from "./workspace-scope.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. */
+// Probe specs (command + parser) shared by the daemon and the panel so both agree on what each measurement means.
+// Parsers return `undefined` rather than throw on an unrecognized shape, since a tool's JSON output can drift between
+// versions; the runner records that as a failed probe, not a clean repo.
+// Tier sets refresh cadence by cost (tier 1 daily, tier 2 weekly); a non-zero `available` means unmeasured, never a
+// false-clean result.
 
 const HOUR_MS = 3_600_000;
 const DAY_MS = 24 * HOUR_MS;
@@ -39,29 +24,23 @@ 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.
+    // Shown to the reader in the panel, next to the probe's 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.
+    // How long a result stays fresh; the background runner refreshes past it, manual refresh 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.
+    // Exit 0 means this repo can be measured; runs in the repo's own directory, like `command`.
     readonly available: string;
-    /* What is MISSING when `available` says no, named here rather than derived from the title. The obvious
-     * derivation, "this repository has no security advisories to measure", states the one thing an unmeasured
-     * probe must never claim, that there are none, and it is the same conflation the block above exists to
-     * prevent. Phrased as a bare clause ("no lockfile"), because the panel groups these under its own lead-in. */
+    // What's missing, as a bare clause; must never imply the repo has zero findings (unmeasured is not clean).
     readonly unavailable: 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.
+    // Runs via `sh -c` in the repo dir; non-zero exit isn't failure, the runner judges by whether parse succeeded.
     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.
+// Parses the first `{...}` found as JSON, or returns undefined; tolerates leading warnings or empty stdout without
+// throwing.
 const asObject = (text: string): Record<string, unknown> | undefined => {
     const start = text.indexOf(`{`);
     if (start === -1) {
@@ -78,8 +57,8 @@ const asObject = (text: string): Record<string, unknown> | 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.
+// Leading-integer parts of a version, compared positionally rather than via full semver; prerelease/build metadata
+// can't change which position differs first.
 const versionParts = (version: string): number[] =>
     version
         .replace(/^[^\d]*/, ``)
@@ -95,11 +74,9 @@ const semverKind = (current: string, latest: string): OutdatedPackage["kind"] =>
     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. */
+// `pnpm outdated --json` prints a name→{current,latest,dependencyType} map; the recursive workspace form merges into
+// the same shape.
+// Entries missing `current` or `latest` are skipped: pnpm could not resolve them against the registry.
 const parseOutdated = (stdout: string): ProbeFacts | undefined => {
     const root = asObject(stdout);
     if (root === undefined) {
@@ -123,20 +100,17 @@ const parseOutdated = (stdout: string): ProbeFacts | undefined => {
 
 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. */
+// `pnpm audit --json` prints {advisories, metadata}; metadata's tally is ignored since the chore needs which package
+// and whether a patch exists.
+// `dev` is read from the findings' own flag: a build-time-only advisory is a different risk than one in a running
+// service.
 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.
+    // No `advisories` key is pnpm's clean report (empty list), not an unrecognized shape.
     if (raw === undefined) {
         return { id: `audit`, advisories: [] };
     }
@@ -160,8 +134,7 @@ const parseAudit = (stdout: string): ProbeFacts | undefined => {
             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.
+            // `<0.0.0` is npm's spelling of "no patch exists"; treated as absent rather than a fixable range.
             ...(patched === undefined || patched === `<0.0.0` ? {} : { patched }),
             dev: findings.length > 0 && findings.every((finding) => finding[`dev`] === true),
         });
@@ -169,17 +142,12 @@ const parseAudit = (stdout: string): ProbeFacts | undefined => {
     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. */
+// Sample of paths only; the agent re-runs knip live, so a full list would already be stale.
 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.
+    // `issues` is the whole report; its absence means this isn't knip's output at all.
     if (!Array.isArray(raw)) {
         return undefined;
     }
@@ -196,10 +164,7 @@ const parseKnip = (stdout: string): ProbeFacts | undefined => {
     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. */
+// jscpd writes JSON to a file, not stdout; percentage of scanned lines is stable, unlike a raw clone count.
 const DUPLICATION_SAMPLE = 5;
 
 const parseJscpd = (stdout: string): ProbeFacts | undefined => {
@@ -228,28 +193,15 @@ const parseJscpd = (stdout: string): ProbeFacts | undefined => {
     return { id: `jscpd`, duplication };
 };
 
-/* WHAT THE SUITE WOULD NOTICE IF THE CODE BROKE, from Stryker's report.
- *
- * The report is the cross-tool "mutation testing report schema": `files` maps a path to `{ mutants: [{ mutatorName,
- * replacement, location.start.line, status }] }`. Statuses are Killed, Survived, NoCoverage, Timeout, CompileError,
- * RuntimeError, Ignored, Pending.
- *
- * THE ARITHMETIC IS STRYKER'S, NOT OURS, and that is a deliberate constraint rather than laziness. A timeout counts
- * as DETECTED (a mutant that hangs the suite is one the suite noticed) and NoCoverage counts as UNDETECTED (nothing
- * ran, so nothing could have caught it). Both are counter-intuitive enough to be worth restating here, and both are
- * what the tool's own score means — a row that recomputed them differently would be quietly arguing with the
- * evidence printed underneath it.
- *
- * `Pending` is treated as inconclusive rather than dropped: an interrupted incremental run leaves them, and
- * counting them either way would move the score for a reason that has nothing to do with the tests. */
+// Timeout counts as DETECTED, NoCoverage as UNDETECTED; Pending is inconclusive, not dropped either way.
 const SURVIVOR_SAMPLE = 8;
 const DETECTED = new Set([`Killed`, `Timeout`]);
 const UNDETECTED = new Set([`Survived`, `NoCoverage`]);
 
 type Survivor = MutationScore["survivors"][number];
 
-// One file's mutant list, or nothing. Every shape this cannot recognise reads as "no mutants here" rather than
-// throwing: a report with one malformed entry is still worth the rest of its numbers.
+// One file's mutant list, or empty for any shape that doesn't match; a malformed entry doesn't invalidate the rest of
+// the report.
 const mutantsOf = (raw: unknown): readonly Record<string, unknown>[] => {
     if (typeof raw !== `object` || raw === null) {
         return [];
@@ -269,8 +221,7 @@ const survivorOf = (file: string, mutant: Record<string, unknown>): Survivor =>
     file,
     line: lineOf(mutant),
     mutator: asString(mutant[`mutatorName`]) ?? `?`,
-    // An empty replacement is meaningful — the mutator deleted the expression — so it is rendered as the removal
-    // it is rather than left blank for a reader to puzzle over.
+    // Empty replacement means the mutator deleted the expression; rendered as `(removed)` rather than blank.
     replacement: asString(mutant[`replacement`]) ?? `(removed)`,
 });
 
@@ -290,9 +241,8 @@ const tallyMutants = (files: Record<string, unknown>): Tally => {
                 tally.killed++;
                 continue;
             }
-            // Anything that is neither detected nor undetected never got a verdict — it would not compile, or the
-            // configuration ignored it. Counting it either way would move the score for a reason that has nothing
-            // to do with the tests.
+            // Neither detected nor undetected got a verdict; it didn't compile or was ignored, and doesn't move the
+            // score.
             if (!UNDETECTED.has(status)) {
                 tally.inconclusive++;
                 continue;
@@ -306,16 +256,14 @@ const tallyMutants = (files: Record<string, unknown>): Tally => {
 
 const parseMutation = (stdout: string): ProbeFacts | undefined => {
     const files = asObject(stdout)?.[`files`];
-    // No `files` key at all means this is not a mutation report. An EMPTY one is a real answer (nothing was
-    // mutated) and a missing one is a parse failure, and the runner has to be able to tell them apart.
+    // Missing `files` means this isn't a mutation report; an empty one is honest (nothing was mutated).
     if (typeof files !== `object` || files === null || Array.isArray(files)) {
         return undefined;
     }
     const tally = tallyMutants(files as Record<string, unknown>);
     const valid = tally.killed + tally.survived;
     const mutation: MutationScore = {
-        // Nothing to mutate scores 100 rather than NaN: there is no undetected fault in it, which is the honest
-        // reading and the one that keeps the chore quiet instead of dividing by zero.
+        // Nothing to mutate scores 100, not NaN: no undetected fault exists, and it avoids dividing by zero.
         score: valid === 0 ? 100 : Math.round((tally.killed / valid) * 100),
         killed: tally.killed,
         survived: tally.survived,
@@ -325,35 +273,20 @@ const parseMutation = (stdout: string): ProbeFacts | undefined => {
     return { id: `mutation`, mutation };
 };
 
-/* THE UI SWEEP. The only probe here whose command is COMPOSED rather than written out, because its subject is a
- * table (stack.ts) that will grow and a hand-written command would be a second copy of it going stale.
- *
- * Everything it emits is a labelled, tab-separated line, and the first line is always the bare marker `UI`. That
- * marker is the whole reason this parser can tell "the sweep ran and this repository is clean" from "the sweep
- * never ran": every other line is optional, so without it an empty stdout and a spotless codebase are the same
- * string, and reporting the second when it was the first is the one thing probes.ts exists to prevent. */
+// First output line is always literal marker `UI`: distinguishes a clean sweep from one that never ran.
 const UI_MARKER = `UI`;
-// Caps, applied after `sort` so truncation is alphabetical and therefore identical between runs, an unsorted
-// truncation would mint a new digest on every sweep and badge forever. What is dropped is genuinely dropped: a
-// component past the cap cannot join a family, and the chore says so rather than implying it saw everything.
+// Caps apply after `sort`: truncation is alphabetical and stable between runs; anything past the cap is dropped.
 const COMPONENT_LIMIT = 2000;
 const RULE_FILE_LIMIT = 500;
 
-/* THE `.` IS LOAD-BEARING, and leaving it off cost this probe every finding it will ever have. Given no path,
- * ripgrep searches the tree only when stdin is a TTY, otherwise it reads STDIN, which is exactly how the runner
- * spawns a probe. The sweep therefore ran, exited 0, printed its marker and matched nothing, in every repository,
- * forever: the precise failure the marker line was introduced to make impossible, arriving through the one door it
- * does not cover. It reproduces from Node and not from an interactive shell, which is why it survived being read.
- *
- * The prefix that comes back with it (`./src/Button.vue`) is normalised away at the parse, so one spelling of a
- * path reaches the chores no matter which tool produced it. */
+// Required: without a path, ripgrep reads stdin instead of the tree when run non-interactively, as here.
 const SCAN_ROOT = `.`;
 
 const globArgs = (globs: readonly string[]): string =>
     [...[...globs, ...SCAN_IGNORES].map((glob) => `-g '${glob}'`), WORKSPACE_ROOT_RG_EXCLUDE_ARG].join(` `);
 
-// `path:count` from `rg --count-matches`, normalised. Split at the LAST colon: a path may contain one, a count is
-// always the digits at the end.
+// `path:count` from `rg --count-matches`; splits at the last colon since a path may contain one but the count is always
+// trailing digits.
 const splitCount = (text: string): { path: string; count: number } | undefined => {
     const at = text.lastIndexOf(`:`);
     if (at <= 0) {
@@ -363,10 +296,8 @@ const splitCount = (text: string): { path: string; count: number } | undefined =
     return Number.isNaN(count) || count <= 0 ? undefined : { path: normalizePath(text.slice(0, at)), count };
 };
 
-/* An idiom's line is a PATH AND NOTHING ELSE, which is what lets one line shape carry both kinds of rule. A
- * present rule asks ripgrep which files match (`-l`); an absent one asks which files do not (`--files-without-
- * match`), and neither has a count to report. Nothing downstream ever wanted one: a file is on the old idiom or
- * it is not, and how many times it says so within itself is not a fact anyone would act on differently. */
+// Emits a bare path per match: `-l` for a present rule, `--files-without-match` for an absent one; no count is ever
+// needed downstream.
 const idiomCommand = (rule: IdiomRule): string =>
     `rg --no-messages ${rule.absent === undefined ? `-l` : `--files-without-match`} -e '${rule.pattern}' ${globArgs(rule.globs)} ${SCAN_ROOT} 2>/dev/null ` +
     `| sort | head -n ${RULE_FILE_LIMIT} | awk '{print "IDIOM\\t${rule.id}\\t" $0}'`;
@@ -378,8 +309,7 @@ const scanCommand = (): string =>
         `rg --no-messages --count-matches -e '${BYPASS_PATTERN}' ${globArgs(MARKUP_GLOBS)} ${SCAN_ROOT} 2>/dev/null ` +
             `| sort | head -n ${RULE_FILE_LIMIT} | awk '{print "BYPASS\\t" $0}'`,
         ...IDIOM_RULES.map(idiomCommand),
-        // Every rg above exits 1 when it matches nothing, which is the healthy case and must not read as a broken
-        // command. The runner judges by the parse, but leaving the script's own status at 1 would be a lie.
+        // Resets exit status to 0: an rg above exiting 1 (no matches) is the healthy case, not a broken command.
         `true`,
     ].join(`; `);
 
@@ -411,13 +341,10 @@ const parseUi = (stdout: string): ProbeFacts | undefined => {
     return { id: `ui`, scan };
 };
 
-/* THE BUILD OUTPUT, measured where it already is. See BundleSchema for why this never runs the build; the
- * consequence here is that `available` is a question about the filesystem rather than about the toolchain, and a
- * repository whose only builds happen in CI reports `unavailable` rather than a wrong number. */
+// Checks disk, not the toolchain: a CI-only build reports unavailable, not a wrong number.
 const BUILD_DIRS = [`dist`, `build`, `out`, `public/build`];
 const BUNDLE_MARKER = `DIR`;
-// Enough of the ranking to see the shape of a build. Past this the assets are the long tail of lazy chunks, and
-// carrying four hundred of them on a route the rail badge polls would cost more than the finding is worth.
+// Ranking cutoff; past this are long-tail lazy chunks not worth the badge route's cost to carry.
 const ASSET_LIMIT = 40;
 
 const bundleCommand = (): string =>
@@ -426,9 +353,8 @@ const bundleCommand = (): string =>
         `for d in ${BUILD_DIRS.join(` `)}; do if [ -d "$d" ]; then dir="$d"; break; fi; done`,
         `[ -n "$dir" ] || exit 0`,
         `printf '${BUNDLE_MARKER}\\t%s\\n' "$dir"`,
-        // `-exec ... {} +` rather than a `for` over command substitution: a hashed asset name will not contain a
-        // space, but a build that copies user content into the output can, and a probe is not the place to find
-        // out. Sorted by raw bytes so the head is the ranking rather than whatever order the walk returned.
+        // `-exec ... {} +`, not a `for` loop: an asset path can contain a space; sorted by bytes so head is the
+        // ranking.
         `find "$dir" -type f \\( -name '*.js' -o -name '*.mjs' -o -name '*.cjs' -o -name '*.css' \\) ` +
             `-exec sh -c 'for f; do printf "ASSET\\t%s\\t%s\\t%s\\n" "$(wc -c <"$f")" "$(gzip -c "$f" | wc -c)" "$f"; done' _ {} + ` +
             `2>/dev/null | sort -k2 -rn | head -n ${ASSET_LIMIT}`,
@@ -455,9 +381,7 @@ const parseBundle = (stdout: string): ProbeFacts | undefined => {
     }
     const bundle: Bundle = {
         dir: dirLine.slice(BUNDLE_MARKER.length + 1),
-        // Of the assets CARRIED, which is the top of the ranking rather than the whole build. The chore says so
-        // when it quotes the number: a total that silently excluded the tail would be the more misleading of the
-        // two, and re-walking the tree to sum it would double the probe's cost for a figure nobody splits on.
+        // Sum of the assets carried (the ranking), not the whole build; avoids a second walk to total the rest.
         totalBytes: assets.reduce((sum, asset) => sum + asset.bytes, 0),
         totalGzip: assets.reduce((sum, asset) => sum + asset.gzip, 0),
         assets,
@@ -465,12 +389,9 @@ const parseBundle = (stdout: string): ProbeFacts | undefined => {
     return { id: `bundle`, bundle };
 };
 
-// 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.
+// jscpd report dir under /tmp, read immediately then discarded; same path chores.ts uses.
 const JSCPD_DIR = `/tmp/intentic-chore-jscpd`;
-// Where Stryker's json reporter writes, which is its own default and not configurable per run on the CLI. Read
-// from the repo directory the probe runs in, like jscpd's report above.
+// Stryker's own default json-report path, not configurable per run; read from the repo dir the probe runs in.
 const MUTATION_REPORT = `reports/mutation/mutation.json`;
 
 export const PROBES: readonly ProbeSpec[] = [
@@ -483,8 +404,8 @@ export const PROBES: readonly ProbeSpec[] = [
         timeoutMs: 5 * 60_000,
         available: `test -f package.json`,
         unavailable: `no 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.
+        // `-r` reports every workspace package, not just root; `|| true` since pnpm exits non-zero when it has
+        // findings.
         command: `pnpm outdated -r --json 2>/dev/null || true`,
         parse: parseOutdated,
     },
@@ -495,8 +416,7 @@ export const PROBES: readonly ProbeSpec[] = [
         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.
+        // A lockfile, not package.json: audit resolves the installed tree, and without one pnpm has nothing to check.
         available: `test -f pnpm-lock.yaml || test -f package-lock.json`,
         unavailable: `no lockfile`,
         command: `pnpm audit --json 2>/dev/null || true`,
@@ -509,8 +429,7 @@ export const PROBES: readonly ProbeSpec[] = [
         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.
+        // The repo's own knip, never a floating one: a mismatched version can call its own live API dead code.
         available: `pnpm exec knip --version >/dev/null 2>&1`,
         unavailable: `knip is not a devDependency`,
         command: `pnpm exec knip --reporter json --no-exit-code 2>/dev/null || true`,
@@ -525,8 +444,7 @@ export const PROBES: readonly ProbeSpec[] = [
         timeoutMs: 20 * 60_000,
         available: `test -f package.json`,
         unavailable: `no 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.
+        // `--threshold 100` stops jscpd failing on its own opinion; the chore judges duplication from the percentage.
         command:
             `pnpm dlx jscpd ${WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG} --reporters json --output ${JSCPD_DIR} --min-lines 12 --threshold 100 . >/dev/null 2>&1; ` +
             `cat ${JSCPD_DIR}/jscpd-report.json 2>/dev/null`,
@@ -536,31 +454,14 @@ export const PROBES: readonly ProbeSpec[] = [
         id: `mutation`,
         title: `Test strength`,
         measures: `how much of the code could break with every test still green`,
-        /* THE MOST EXPENSIVE PROBE HERE, and the tier does not really capture it: this runs the suite once per
-         * injected fault. `--incremental` is what makes it liveable — Stryker keeps a result file and re-runs only
-         * the mutants whose code or tests changed, so the first run costs what a full run costs and every one
-         * after it costs the diff. The monthly TTL is set against the FIRST run, not the incremental ones.
-         *
-         * Opt-in per repository, by the presence of a `stryker.conf.json`, and that is the load-bearing part of
-         * the design rather than a convenience. This monorepo has 65 packages with their own vitest configs and no
-         * root suite; mutating all of them unasked would be hours of CPU nobody agreed to spend. A repo says which
-         * code is worth the measurement by writing that file, which is also where `mutate` narrows the scope. */
+        // `--incremental` reruns only changed mutants; the 30-day TTL targets that costly first full run.
         tier: 2,
         ttlMs: 30 * DAY_MS,
         timeoutMs: 90 * 60_000,
-        /* Two conditions, and the config is the one that matters: Stryker being installed says the tool COULD run,
-         * the config says somebody decided it should. Without the second this would report "unavailable" on every
-         * repo that merely shares this monorepo's lockfile.
-         *
-         * The repo's OWN Stryker, never a floating one, for a reason measured rather than assumed: under
-         * `pnpm dlx` the plugin loader resolves from the working directory and finds nothing — "Cannot find
-         * TestRunner plugin \"vitest\". In fact, no TestRunner plugins were loaded" — and the runner has to agree
-         * with the vitest the repo actually runs. Same argument as knip above. */
+        // Config presence means the repo opted in, not just having Stryker; must use the repo's own stryker, not `dlx`.
         available: `{ test -f stryker.conf.mjs || test -f stryker.conf.json; } && pnpm exec stryker --version >/dev/null 2>&1`,
         unavailable: `no stryker config in this repo`,
-        // `|| true` for the same reason the others carry it: Stryker exits non-zero when the score is under its
-        // own threshold, which is an opinion about the number, not a failure to produce one. The judgement is the
-        // chore's, made from the score, and the runner decides by whether the parser recognised the report.
+        // `|| true`: Stryker exits non-zero under its own score threshold; the parser decides if the run was valid.
         command: `pnpm exec stryker run --reporters json --incremental >/dev/null 2>&1 || true; cat ${MUTATION_REPORT} 2>/dev/null`,
         parse: parseMutation,
     },
@@ -568,15 +469,12 @@ export const PROBES: readonly ProbeSpec[] = [
         id: `ui`,
         title: `Front-end source`,
         measures: `components, hard-coded styles and idioms the framework has replaced`,
-        /* Tier 1 despite reading the whole tree, and the placement is a judgement rather than an oversight. The
-         * tier is about COST: this is a dozen ripgrep walks, seconds on a large monorepo, against knip
-         * type-checking the tree and jscpd tokenizing every file for minutes. A weekly TTL would also make it the
-         * wrong shape, its findings move whenever someone writes a component, which is daily. */
+        // Tier 1 despite scanning the tree: ripgrep walks cost seconds, and findings move daily as components change.
         tier: 1,
         ttlMs: DAY_MS,
         timeoutMs: 5 * 60_000,
-        // Any manifest in the repo declaring a UI framework or Tailwind, not just the root's, a monorepo keeps
-        // React in the app package and the root manifest is a handful of build tools.
+        // Any manifest declaring a framework or Tailwind, not just root's; monorepos often keep React in an app
+        // package.
         available:
             `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ${WORKSPACE_ROOT_RG_EXCLUDE_ARG} ` +
             `-e '[\\x22](${[...UI_FRAMEWORKS.flatMap((framework) => framework.packages), ...TAILWIND_PACKAGES].join(`|`)})[\\x22]\\s*:' . >/dev/null`,
@@ -591,12 +489,9 @@ export const PROBES: readonly ProbeSpec[] = [
         tier: 1,
         ttlMs: DAY_MS,
         timeoutMs: 5 * 60_000,
-        // A build directory that actually contains something a browser would download. `-d` alone would pass on
-        // the empty `dist/` a cleaned checkout leaves behind, and the measurement would report a zero-byte bundle
-        // as a fact about the application.
+        // Must contain an actual asset file: `-d` alone would pass an empty `dist/` left by a cleaned checkout.
         available: `find ${BUILD_DIRS.join(` `)} -maxdepth 4 -type f \\( -name '*.js' -o -name '*.mjs' -o -name '*.css' \\) 2>/dev/null | head -n 1 | grep -q .`,
-        // Says what is missing AND that this never builds, because the obvious reading of "no build output" is
-        // that we tried and it failed. The owner running their own build once is the whole fix.
+        // States it never builds, only reads the last one: "no output" would otherwise read as "the build failed".
         unavailable: `no build output on disk, this reads the last build, it never runs one`,
         command: bundleCommand(),
         parse: parseBundle,

package/src/chores/prompt.ts

@@ -1,19 +1,9 @@
-/* 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. */
+// Every generated prompt has four parts, in this order:
+// subject — what is being worked on.
+// why — the measurement's numbers, quoted exactly, then what they mean.
+// goal — a direction to move in, not a prescribed design.
+// done — falsifiable; checkable via `iq` in the agent's own worktree.
+// Invariants sit between goal and done: constraints on how, restated in full each time.
 
 export interface Ask {
     readonly subject: string;
@@ -27,38 +17,24 @@ export interface Ask {
 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. */
+// Findings are claims to verify, not tasks to execute; acting on all of them is worse than acting on none.
 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. */
+// Constraints for a change-making turn: every change must be explainable on its own line of the summary.
 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.
+// Constraints for a look-only turn, stated explicitly so a report chore never quietly starts editing.
 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 scope of changes is the thing at stake: named as a scope rather than "only this file",
- * since half those archetypes ask for new files and must not read as forbidding them. */
+// Constraints for a one-file refactor turn; scope covers whatever it splits into, not just this one file.
 export const REFACTOR_INVARIANTS =
     `Read it first. Behaviour stays identical. Changes affect only this file, whatever it splits into, and the ` +
     `importers that must follow. Leave no re-export shims behind.`;