@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/chores/digest.test.ts

@@ -13,7 +13,7 @@ describe(`digestOf`, () => {
     });
 });
 
-/* The anti-drift mechanism. A chore that counts things must not mint a new digest — and therefore a new badge —
+/* 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`, () => {

package/src/chores/digest.ts

@@ -1,8 +1,8 @@
-/* THE EVIDENCE DIGEST — the one idea that turns a nagging panel into something you can live with.
+/* THE EVIDENCE DIGEST, the one idea that turns a nagging panel into something you can live with.
  *
  * A chore is due because of a measurement. Run the turn, and one of three things happens: the measurement moves
  * (the work landed), it stays put (the work is pending review, or the tool was wrong), or the tool reports
- * something else entirely next week. Only the first is "done", and none of them is answerable by a timestamp —
+ * something else entirely next week. Only the first is "done", and none of them is answerable by a timestamp,
  * "ran 3 days ago" cannot tell you whether it ran against THIS.
  *
  * So a run records a hash of the evidence that provoked it. The next verdict compares:
@@ -32,7 +32,7 @@ export const digestOf = (...parts: readonly (string | number)[]): string => {
 
 /* Buckets a count so that ordinary drift does not read as news. Twelve outdated packages becoming thirteen is not
  * a thing to interrupt someone about; twelve becoming forty is. Powers-of-two boundaries, so the bucket widens
- * with the number — the difference between 1 and 2 matters and the difference between 400 and 500 does not.
+ * with the number, the difference between 1 and 2 matters and the difference between 400 and 500 does not.
  *
  * This is the difference between a digest that changes on every poll (and therefore badges forever) and one that
  * changes when the situation does. Chores that count things digest the BUCKET; chores whose evidence is a set of

package/src/chores/extension-update.ts

@@ -1,16 +1,16 @@
 import { composeAsk } from "./prompt.js";
 
-/* AN EXTENSION UPDATE, READ AS A DIFF. The commit that is installed was approved once already — re-reading all
+/* AN EXTENSION UPDATE, READ AS A DIFF. The commit that is installed was approved once already, re-reading all
  * of it would bury the one question an update asks: what is different, and did any of it change the deal? So
  * the turn's subject is the diff between the two commits, and the manifest's delta leads, because a new entry
  * in `permissions.sandbox` is reach the owner never approved, arriving dressed as an update.
  *
  * Here in the contract's chores rather than in the web app, because two callers build it: the update card's
- * "read the diff" button, and the daemon's agent-prepared update policy — which runs this exact read
+ * "read the diff" button, and the daemon's agent-prepared update policy, which runs this exact read
  * unprompted when the registry lists a new sha, so the owner opens a finished account instead of starting one. */
 const UPDATE_INVARIANTS =
     `This turn reads and reports; it changes nothing and installs nothing. Clone into a scratch directory ` +
-    `outside the workspace and read the diff between the two commits — the installed code was approved once ` +
+    `outside the workspace and read the diff between the two commits: the installed code was approved once ` +
     `already, so what is between them is the whole subject. Lead with the manifest's delta: any route added to ` +
     `\`permissions.sandbox\` is reach the owner never approved and the headline whatever else changed. Then the ` +
     `code: what behaviour changed, in the owner's terms, citing file and line.`;
@@ -19,7 +19,7 @@ export interface UpdateBrief {
     // The listing's display name, or the repository when it is being installed straight from a URL.
     readonly label: string;
     readonly url: string;
-    // What is installed and what the update proposes — both full shas, both facts, neither a branch.
+    // What is installed and what the update proposes, both full shas, both facts, neither a branch.
     readonly fromRef: string;
     readonly toRef: string;
     // Subdirectory inside the repository, for a monorepo source. Empty for a repo of its own.
@@ -33,5 +33,5 @@ export const updateBrief = ({ label, url, fromRef, toRef, path }: UpdateBrief):
         diagnosis: `The manifest (intentic-extension.json at the extension root) is the contract on both sides of the diff, so its delta is readable exactly like the code's.`,
         goal: `Read the diff and say what the update actually is: the manifest delta first, then what the code now does that it did not, and what it stopped doing.`,
         invariants: UPDATE_INVARIANTS,
-        done: `Done when you end on a recommendation the owner can act on — update, update and watch something named, or stay on ${fromRef.slice(0, 7)} — with the change that decided it cited by file and line.`,
+        done: `Done when you end on a recommendation the owner can act on, update, update and watch something named, or stay on ${fromRef.slice(0, 7)}, with the change that decided it cited by file and line.`,
     });

package/src/chores/fix-deps.ts

@@ -1,14 +1,14 @@
-/* THE FIX CHORE — the template for opting into dependency-breakage repair.
+/* THE FIX CHORE, the template for opting into dependency-breakage repair.
  *
  * The automations catalogue offers it as a recipe; nothing creates it until the owner picks that template.
  *
- * It wakes on `deps.broken` — the dependency verifier's edge event: a landed change drifted the installed
+ * It wakes on `deps.broken`, the dependency verifier's edge event: a landed change drifted the installed
  * dependencies, the daemon reinstalled them, ran the tree's own checks, and they came back red. The payload
  * is that event: `deps.project` is the project whose checks failed, `deps.command` the exact command that
  * judged it, `deps.exitCode` and `deps.logTail` what it said, and `deps.attempt` which consecutive red this
  * is since the last green.
  *
- * THE GUARD IS THE LOOP CAP, and it lives in guard shell — one visible, owner-editable line — rather than in
+ * THE GUARD IS THE LOOP CAP, and it lives in guard shell, one visible, owner-editable line, rather than in
  * daemon code, because whoever tunes "how many tries before a human looks" must be able to see the number.
  * Attempt 1 is the breakage, attempt 2 is one landed fix that still failed; past that the loop stops and the
  * standing red is the owner's to read (the activity feed has been narrating every step).
@@ -28,7 +28,7 @@ export const FIX_DEPS_AUTOMATION = {
         "and they failed. The payload names the project (`deps.project`), the check command (`deps.command`), how it exited " +
         "(`deps.exitCode`) and the tail of its output (`deps.logTail`); the full log is in the project's `--verify` terminal.\n\n" +
         "Re-run the check yourself to see the failure first-hand, then fix the ROOT CAUSE. That usually means updating call " +
-        "sites, types or tests to match what actually changed — never loosening or deleting the checks, pinning or downgrading " +
+        "sites, types or tests to match what actually changed: never loosening or deleting the checks, pinning or downgrading " +
         "dependencies just to silence them, or editing generated files. If the breakage needs a decision only the owner can " +
         "make (an intentional breaking upgrade, a license change, a dependency that should be dropped), stop and say exactly " +
         "that instead of guessing.\n\n" +

package/src/chores/probes.test.ts

@@ -3,7 +3,7 @@ import { probeSpec } from "./probes.js";
 import { IDIOM_RULES } from "./stack.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
+ * 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. */
@@ -135,7 +135,7 @@ describe(`knip`, () => {
         });
     });
 
-    // Without an `issues` array this is not knip's report, whatever else it contains — and reporting zero dead code
+    // 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();
@@ -233,8 +233,8 @@ describe(`ui`, () => {
     });
 
     /* Every path the sweep prints wears a `./`, because every ripgrep in it is handed `.` to walk. Downstream this
-     * would have to be remembered at each comparison — jscpd's paths against the component list, a bypass against
-     * a component — so it is spent once, here, and one spelling of a path leaves the parser. */
+     * would have to be remembered at each comparison: jscpd's paths against the component list, a bypass against
+     * a component, so it is spent once, here, and one spelling of a path leaves the parser. */
     test(`strips the prefix ripgrep prints for a path it was told to walk`, () => {
         expect(parse(`ui`, sweep(`COMPONENT\t./src/Button.vue`, `BYPASS\t./src/Button.vue:3`, `IDIOM\tvue-options-api\t./src/Old.vue`))).toEqual({
             id: `ui`,
@@ -257,7 +257,7 @@ describe(`ui`, () => {
 describe(`the sweep's composed command`, () => {
     const stages = (): string[] => probeSpec(`ui`).command.split(`; `);
 
-    /* Given no path, ripgrep searches STDIN whenever stdin is not a TTY — which is exactly how a probe is spawned.
+    /* Given no path, ripgrep searches STDIN whenever stdin is not a TTY, which is exactly how a probe is spawned.
      * The sweep exited 0, printed its marker and matched nothing, in every repository, forever, which the marker
      * line cannot catch because the sweep really did run. It reproduces from a child process and never from an
      * interactive shell, so the command is the only place it is visible. */
@@ -300,7 +300,7 @@ describe(`bundle`, () => {
     });
 
     // The `find` prints nothing for a directory that exists but holds no assets. `available` is supposed to catch
-    // that, and this is the second line of defence — a zero-byte bundle would otherwise read as a fact.
+    // that, and this is the second line of defence: a zero-byte bundle would otherwise read as a fact.
     test(`a directory line with no assets is an empty build, not a failure`, () => {
         expect(parse(`bundle`, `DIR\tbuild`)).toMatchObject({ bundle: { dir: `build`, assets: [], totalBytes: 0, totalGzip: 0 } });
     });

package/src/chores/probes.ts

@@ -11,19 +11,19 @@ import {
     TAILWIND_PACKAGES,
 } from "./stack.js";
 
-/* THE PROBES — the measurements that cost a subprocess, declared once so the daemon that runs them and the panel
+/* 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
+ * 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
+ * 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.
  *
@@ -48,7 +48,7 @@ export interface ProbeSpec {
     // Exit 0 ⇒ this repo can be measured. Runs in the repo's own directory, like the 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
+     * 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. */
     readonly unavailable: string;
@@ -97,7 +97,7 @@ const semverKind = (current: string, latest: string): OutdatedPackage["kind"] =>
 /* `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
+ * 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);
@@ -123,8 +123,8 @@ 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"
+ * 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
@@ -135,7 +135,7 @@ const parseAudit = (stdout: string): ProbeFacts | 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 at all is pnpm's clean report, an empty list, not an unrecognisable one.
     if (raw === undefined) {
         return { id: `audit`, advisories: [] };
     }
@@ -168,7 +168,7 @@ 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
+/* 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
@@ -233,16 +233,16 @@ const parseJscpd = (stdout: string): ProbeFacts | undefined => {
  * 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. */
+ * string, and reporting the second when it was the first is the one thing probes.ts exists to prevent. */
 const UI_MARKER = `UI`;
-// Caps, applied after `sort` so truncation is alphabetical and therefore identical between runs — an unsorted
+// 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.
 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
+ * 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.
@@ -367,7 +367,7 @@ const parseBundle = (stdout: string): ProbeFacts | undefined => {
 };
 
 // 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
+// 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`;
 
@@ -423,7 +423,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 —
+        // `--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; ` +
@@ -437,11 +437,11 @@ export const PROBES: readonly ProbeSpec[] = [
         /* 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. */
+         * wrong shape, its findings move whenever someone writes a component, which is daily. */
         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
+        // 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.
         available:
             `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ` +
@@ -463,7 +463,7 @@ export const PROBES: readonly ProbeSpec[] = [
         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.
-        unavailable: `no build output on disk — this reads the last build, it never runs one`,
+        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,18 +1,18 @@
-/* HOW WE ASK. Every prompt this workspace generates from a measurement — a hotspot's refactor, a chore's sweep —
+/* 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,
+ *   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
+ * 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 {
@@ -30,16 +30,16 @@ export const composeAsk = ({ subject, why, diagnosis, goal, invariants, done }:
 /* 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 —
+ * 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.`;
+    `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
+ * 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
@@ -57,8 +57,8 @@ export const REPORT_INVARIANTS =
     `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",
+ * 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. */
 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.`;
+    `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.`;

package/src/chores/stack.test.ts

@@ -5,7 +5,7 @@ import { componentStem, frameworksOf, IDIOM_RULES, idiomRule, UI_FRAMEWORKS, use
  *
  * Most of what is below guards a failure that CANNOT be seen by reading the table: a pattern is interpolated into
  * a shell command that runs on someone else's machine at three in the morning, so a stray quote is not a typo
- * anyone reviews — it is a probe that dies in a workspace nobody is watching, with a shell error for a reason. */
+ * anyone reviews: it is a probe that dies in a workspace nobody is watching, with a shell error for a reason. */
 
 describe(`the patterns are safe to interpolate`, () => {
     // The scan wraps every pattern and glob in shell single quotes. One apostrophe inside ends the quoting and
@@ -29,7 +29,7 @@ describe(`the patterns are safe to interpolate`, () => {
 
     /* Rust's regex crate has no lookaround, and getting it means ripgrep's -P, which is a compile-time option on
      * the box the sweep happens to run on. A rule that seems to need one is asking a question about the FILE
-     * rather than about a line — which is what `absent` is. */
+     * rather than about a line, which is what `absent` is. */
     test(`no pattern uses a lookaround`, () => {
         for (const rule of IDIOM_RULES) {
             expect(rule.pattern, rule.id).not.toMatch(/\(\?<?[=!]/);
@@ -109,7 +109,7 @@ describe(`the name two components share`, () => {
     });
 
     /* The trap in stripping a trailing number. `H1` and `H2` are different components and reduce to the same
-     * single letter, so the stem is only accepted when what survives is still long enough to mean something —
+     * single letter, so the stem is only accepted when what survives is still long enough to mean something:
      * otherwise the untouched name is kept and the two stay apart. */
     test(`short names keep their digits rather than collapsing together`, () => {
         expect(componentStem(`src/type/H1.tsx`)).toBe(`h1`);

package/src/chores/stack.ts

@@ -1,4 +1,4 @@
-/* WHAT THIS REPOSITORY IS BUILT WITH, and the patterns that follow from it — the table the UI chores are written
+/* WHAT THIS REPOSITORY IS BUILT WITH, and the patterns that follow from it, the table the UI chores are written
  * against, kept apart from both the probe that runs it and the chores that read it.
  *
  * It sits in the middle on purpose. probes.ts composes ONE ripgrep sweep out of the rules below, and chores.ts
@@ -13,14 +13,14 @@
  * THE PATTERNS ARE RIPGREP'S DIALECT, and they carry two constraints that are not obvious from reading them:
  *
  *   No literal apostrophe, ever. The scan command wraps each pattern in shell single quotes, so a `'` inside one
- *   would end the quoting and hand the rest of the regex to the shell. Match quotes as `[\x22\x27]` instead —
+ *   would end the quoting and hand the rest of the regex to the shell. Match quotes as `[\x22\x27]` instead,
  *   Rust's regex crate reads those escapes, and the shell never sees a quote character at all. stack.test.ts
  *   enforces this, because the failure is a probe that dies at three in the morning in someone else's workspace
  *   rather than anything a reader would notice here.
  *
  *   No lookaround. Rust's regex crate has none, and reaching for ripgrep's PCRE2 mode to get it would make the
  *   sweep depend on how the box's ripgrep was compiled. A rule that seems to need it is usually asking a question
- *   about the FILE rather than about a line — see `absent` below, which is what that question actually is. */
+ *   about the FILE rather than about a line, see `absent` below, which is what that question actually is. */
 
 export interface UiFramework {
     readonly id: string;
@@ -38,7 +38,7 @@ export const UI_FRAMEWORKS: readonly UiFramework[] = [
     { id: `angular`, label: `Angular`, packages: [`@angular/core`] },
 ];
 
-// Tailwind is not in the table above because it is not a UI framework and does not own any idiom rules — it is a
+// Tailwind is not in the table above because it is not a UI framework and does not own any idiom rules, it is a
 // styling system that any of the three can be wearing, and it gates exactly one chore.
 export const TAILWIND_PACKAGES: readonly string[] = [`tailwindcss`];
 
@@ -64,20 +64,20 @@ export const SCAN_IGNORES: readonly string[] = [
     `!**/*.{test,spec,stories}.*`,
 ];
 
-// What counts as a component file, across all three frameworks at once. The sweep cannot vary by repository — a
-// probe's command is a fixed string — so it asks for all of them and a Vue-only repo simply has no `.tsx` files.
+// What counts as a component file, across all three frameworks at once. The sweep cannot vary by repository, a
+// probe's command is a fixed string, so it asks for all of them and a Vue-only repo simply has no `.tsx` files.
 export const COMPONENT_GLOBS: readonly string[] = [`*.vue`, `*.tsx`, `*.jsx`, `*.component.ts`];
 
 // Where a Tailwind class can appear. Wider than COMPONENT_GLOBS because a class list lives in markup as often as
-// in a component — an Angular template and a plain .html page both style with the same utilities.
+// in a component, an Angular template and a plain .html page both style with the same utilities.
 export const MARKUP_GLOBS: readonly string[] = [`*.vue`, `*.tsx`, `*.jsx`, `*.html`, `*.svelte`, `*.astro`];
 
-/* THE DESIGN SYSTEM BYPASS. Not "any arbitrary value" — `grid-cols-[1fr_auto]` and `w-[calc(100%-2rem)]` are
+/* THE DESIGN SYSTEM BYPASS. Not "any arbitrary value", `grid-cols-[1fr_auto]` and `w-[calc(100%-2rem)]` are
  * Tailwind working as designed, and a chore that counted them would be objecting to the feature rather than to
  * anything wrong. What this matches is the two arbitrary values that route around a decision the theme already
  * made: a colour that is not in the palette, and a pixel size that is not on the spacing or type scale.
  *
- * The leading `-` is load-bearing. It anchors the match to a utility prefix (`bg-`, `text-`, `w-`), so a bare
+ * The leading `-` is required. It anchors the match to a utility prefix (`bg-`, `text-`, `w-`), so a bare
  * `[...]` in ordinary prose or an array index cannot be mistaken for a class. */
 export const BYPASS_PATTERN = `-\\[(#[0-9a-fA-F]{3,8}|(rgb|hsl)a?\\(|[0-9]+(\\.[0-9]+)?px)`;
 
@@ -87,12 +87,12 @@ export interface IdiomRule {
     readonly framework: string;
     // What the repository still has, named as the reader would name it.
     readonly label: string;
-    // What replaced it. Carried so the prompt can say where to go rather than only what to leave — an agent told
+    // What replaced it. Carried so the prompt can say where to go rather than only what to leave, an agent told
     // "you still use NgModule" and nothing else will pick a destination, and it may not pick this one.
     readonly replacement: string;
     readonly pattern: string;
     readonly globs: readonly string[];
-    /* THE IDIOM IS THE PATTERN BEING MISSING, not present — `pattern` names the NEW way, and the file is on the
+    /* THE IDIOM IS THE PATTERN BEING MISSING, not present, `pattern` names the NEW way, and the file is on the
      * old one precisely because the new one does not appear in it anywhere. The sweep spells this
      * `--files-without-match`.
      *
@@ -100,7 +100,7 @@ export interface IdiomRule {
      * <script setup>" was first written as a lookahead over `<script`, which matches per LINE: a migrated
      * component with a second plain `<script>` block for defineOptions, or one that merely mentions `<script` in
      * a comment, both read as un-migrated. It reported five files in an application whose 167 SFCs are every one
-     * of them migrated. The question was never "is there a line like this" — it is "does this file contain the
+     * of them migrated. The question was never "is there a line like this", it is "does this file contain the
      * new idiom at all", which is one flag rather than a cleverer regex, and it costs no PCRE2.
      *
      * The globs carry more weight on an absent rule than on a normal one, and narrowly is the only safe way to
@@ -110,7 +110,7 @@ export interface IdiomRule {
 }
 
 /* THE IDIOMS THEIR OWN MAINTAINERS HAVE MOVED ON FROM. Every rule here names something the framework's own
- * documentation now steers people away from, and every one of them still works — which is exactly why they
+ * documentation now steers people away from, and every one of them still works, which is exactly why they
  * accumulate, and why no editor and no linter will bring them up unprompted.
  *
  * High confidence over coverage. Each pattern is one a reader can check by eye against a file, and the ones that
@@ -156,7 +156,7 @@ export const IDIOM_RULES: readonly IdiomRule[] = [
         framework: `vue`,
         label: `the Options API`,
         replacement: `<script setup> with the Composition API`,
-        // The new idiom, inverted by `absent` below — an SFC that never opens a `<script setup>` tag is still on
+        // The new idiom, inverted by `absent` below, an SFC that never opens a `<script setup>` tag is still on
         // the old one. A file with no script block at all is swept up too, and that is the honest reading: it has
         // not been migrated because there was nothing there to migrate.
         pattern: `<script[^>]*\\bsetup\\b`,
@@ -213,14 +213,14 @@ export const idiomRule = (id: string): IdiomRule | undefined => IDIOM_RULES.find
  * side had two extra characters. */
 export const normalizePath = (path: string): string => path.replace(/^\.\//, ``);
 
-// Below this a stem is too short to have survived the stripping above with its meaning intact — `H1` and `H2`
+// Below this a stem is too short to have survived the stripping above with its meaning intact, `H1` and `H2`
 // would both reduce to `h` and read as one family of heading components that are not duplicates of anything.
 const MIN_STEM = 3;
 
 const QUALIFIER_PREFIX = /^(base|the)/;
 const QUALIFIER_SUFFIX = /(v[0-9]+|new|old|legacy|copy|component|[0-9]+)$/;
 
-/* THE NAME TWO COMPONENTS SHARE WHEN THEY ARE THE SAME COMPONENT TWICE — or `undefined` when the file has no
+/* THE NAME TWO COMPONENTS SHARE WHEN THEY ARE THE SAME COMPONENT TWICE, or `undefined` when the file has no
  * name worth comparing.
  *
  * This is a normaliser, not a similarity score, and that is the point: it answers a question the reader can check
@@ -232,7 +232,7 @@ const QUALIFIER_SUFFIX = /(v[0-9]+|new|old|legacy|copy|component|[0-9]+)$/;
  * forty index files is a finding about the naming convention rather than about any duplication. */
 export const componentStem = (path: string): string | undefined => {
     const file = normalizePath(path).split(`/`).pop() ?? ``;
-    // `.component.ts` loses both suffixes, `.vue` loses one — taking everything before the first dot handles both
+    // `.component.ts` loses both suffixes, `.vue` loses one, taking everything before the first dot handles both
     // without a table, since a component's name is never the part after a dot.
     const base = (file.split(`.`)[0] ?? ``).toLowerCase().replace(/[^a-z0-9]/g, ``);
     if (base === `` || base === `index`) {