@intentic/sandbox-contract 1.223.0 → 1.224.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/**' ` +

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.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`) {

package/src/chores/verdict.ts

@@ -2,18 +2,18 @@ import type { ChoreLedgerEntry, ChoresReport, ProbeId, ProbeResult } from "../sc
 import { type Chore, type ChoreContext, type ChoreFinding, CHORES, chorePrompt } from "./chores.js";
 import { probeSpec } from "./probes.js";
 
-/* FROM EVIDENCE TO A VERDICT — the one place that decides whether a chore is due, and the only place that is
+/* FROM EVIDENCE TO A VERDICT, the one place that decides whether a chore is due, and the only place that is
  * allowed to. Both the Maintenance panel and its rail badge run this function over the same report, so the number
  * on the tile and the reason in the panel are the same computation and cannot drift apart.
  *
  * Six states, and the distinctions between them are the whole design:
  *
- *   not-applicable  this chore is not a QUESTION worth asking of this repository — there is no Dockerfile to
+ *   not-applicable  this chore is not a QUESTION worth asking of this repository, there is no Dockerfile to
  *                slim, no pipeline to tighten, no documentation to re-read. Dropped from the panel entirely
  *                rather than shown as clear, because "clear" claims we checked, and there was nothing to check.
  *                The reason survives in the scope strip, so "why is there no Docker chore here?" has an answer.
  *   unavailable  we have not measured this. knip is not a devDependency; there is no lockfile to audit. Rendered
- *                greyed, never badged, and never collapsed into `clear` — a maintenance surface reporting a green
+ *                greyed, never badged, and never collapsed into `clear`, a maintenance surface reporting a green
  *                repository it has never actually measured is worse than one that says nothing.
  *   clear        we measured, and there is nothing to do. This is the common state, and it has to be visibly
  *                reachable or the panel is just a list of complaints.
@@ -23,23 +23,23 @@ import { probeSpec } from "./probes.js";
  *   due          there is something to do.
  *
  * The first three are all ways of saying "no", and keeping them apart is what makes the surface trustworthy: they
- * mean we cannot ask, we did not measure, and we measured and found nothing — three different claims, and only
+ * mean we cannot ask, we did not measure, and we measured and found nothing, three different claims, and only
  * the last one is reassurance.
  *
  * And one flag that is not a state: `settled`. A due chore that has been RE-MEASURED since a turn was spent on
- * it, and whose evidence did not move, stays due — because it is — but must never light the rail again. This is
+ * it, and whose evidence did not move, stays due, because it is, but must never light the rail again. This is
  * what stops the surface repeating itself while a fix sits in review, and it is why the ledger stores a digest
  * rather than a timestamp: "ran 3 days ago" cannot tell you whether it ran against THIS.
  *
  * `stale` is the other half of that sentence, and it exists because the digest alone cannot tell the two apart.
  * A probe that never re-ran produces an unchanged digest for free, so "the fix did not move the numbers" and "we
- * have not looked since the fix" arrived at this function looking identical — and the panel showed the second as
+ * have not looked since the fix" arrived at this function looking identical, and the panel showed the second as
  * the first, quoting a week-old count an hour after the work that invalidated it. Comparing the run's time to the
  * MEASUREMENT's time is what separates them, and it is a comparison of two numbers the report already carries.
  *
  * Nothing here can hide a problem. Snoozing and settling change whether the rail SPEAKS; the panel still shows
  * the chore, its evidence and its state. The one thing that removes a row entirely is `not-applicable`, and that
- * is not hiding — it is the absence of a subject, counted in the panel's scope strip and expandable to the reason.
+ * is not hiding, it is the absence of a subject, counted in the panel's scope strip and expandable to the reason.
  * A maintenance surface you can quietly bury findings in is a maintenance surface nobody trusts. */
 
 export type ChoreState = "due" | "clear" | "snoozed" | "stale" | "unavailable" | "not-applicable";
@@ -49,16 +49,16 @@ export interface ChoreVerdict {
     readonly repo: string;
     readonly state: ChoreState;
     readonly severity: ChoreFinding["severity"];
-    // Always present, in every state — "nothing to do" and "not measured" are answers a reader deserves in words.
+    // Always present, in every state, "nothing to do" and "not measured" are answers a reader deserves in words.
     readonly headline: string;
     readonly detail: readonly string[];
     // The evidence identity. Empty for `unavailable`, where there is no evidence to identify.
     readonly digest: string;
-    /* WHEN THE EVIDENCE WAS TAKEN — the fact every row shows beside its numbers, and the one whose absence let a
+    /* WHEN THE EVIDENCE WAS TAKEN, the fact every row shows beside its numbers, and the one whose absence let a
      * measurement from last Tuesday read as this morning's. Undefined when the verdict rests on no measurement at
      * all: a survey is decided by the calendar, and an unavailable chore has nothing to be out of date. */
     readonly measuredAt: number | undefined;
-    // The turn. Present only when there is something to do — a "start an agent" button on a clear chore is an
+    // The turn. Present only when there is something to do, a "start an agent" button on a clear chore is an
     // invitation to spend money proving that nothing is wrong.
     readonly prompt: string | undefined;
     readonly lastRun: ChoreLedgerEntry | undefined;
@@ -68,7 +68,7 @@ export interface ChoreVerdict {
 }
 
 /* HOW OLD THE EVIDENCE IS: the OLDEST of the measurements a verdict rests on, because a claim is only as current
- * as the least current thing it was computed from. Undefined when it rests on none — a survey has no measurement,
+ * as the least current thing it was computed from. Undefined when it rests on none, a survey has no measurement,
  * and an unavailable chore's probe did not produce one. */
 const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId, ProbeResult>): number | undefined => {
     const taken = needs.flatMap((id) => {
@@ -79,7 +79,7 @@ const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId,
 };
 
 // A survey that is clear is clear because it was READ recently, and saying so is the only way its row means
-// anything — "nothing to do" under a chore that has no measurement would be a claim about the code rather than
+// anything, "nothing to do" under a chore that has no measurement would be a claim about the code rather than
 // about the calendar.
 const clearHeadline = (chore: Chore, lastRun: ChoreLedgerEntry | undefined, nowMs: number): string =>
     chore.survey === true && lastRun !== undefined ? `Surveyed ${Math.round((nowMs - lastRun.ranAt) / 86_400_000)} days ago` : `Nothing to do`;
@@ -109,9 +109,9 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
     const base = { chore, repo: context.repo, lastRun: ledger, settled: false, prompt: undefined } as const;
 
     /* APPLICABILITY FIRST, before anything is measured or any evidence is read. A chore that does not apply is
-     * not "clear" and not "unmeasured" — the question does not arise here, and every subsequent branch of this
-     * function would be answering it anyway. The cause is carried as the headline, because the scope strip — which
-     * groups these rows BY it — is the only place it will ever be read. */
+     * not "clear" and not "unmeasured", the question does not arise here, and every subsequent branch of this
+     * function would be answering it anyway. The cause is carried as the headline, because the scope strip, which
+     * groups these rows BY it, is the only place it will ever be read. */
     const inapplicable = chore.applies?.(context.signals);
     if (inapplicable !== undefined) {
         return { ...base, state: `not-applicable`, severity: `info`, headline: inapplicable, detail: [], digest: ``, measuredAt: undefined };
@@ -138,7 +138,7 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* Has the last run's settlement lapsed? A cadence of 0 means "this is decided by evidence alone" — an advisory
+    /* Has the last run's settlement lapsed? A cadence of 0 means "this is decided by evidence alone", an advisory
      * does not become worth looking at again because ninety days passed, it becomes worth looking at again when
      * the advisory set changes. Anything with a cadence expires its own settlement, so "we looked and chose not to
      * act" cannot silence a chore for good. */
@@ -176,7 +176,7 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* The agent looked at exactly this evidence and reported that there was nothing in it — knip's findings were
+    /* The agent looked at exactly this evidence and reported that there was nothing in it, knip's findings were
      * all public entry points, the clones were all generated files. That verdict has to stick, or the next poll
      * starts the same turn again and the surface has taught the owner that its rows are wrong. It stops sticking
      * when the evidence changes (a different digest) or the cadence lapses. */
@@ -193,10 +193,10 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
     }
 
     /* THE MEASUREMENT IS OLDER THAN THE WORK. A turn landed after the last time we looked, so the evidence below
-     * describes a tree that no longer exists — an hour after a run deleted the dead code, the row was still
+     * describes a tree that no longer exists, an hour after a run deleted the dead code, the row was still
      * quoting the count from six days before it. `sameEvidence` cannot catch this: an unchanged digest is exactly
      * what a probe that never re-ran produces, so the flag says "settled" at its most confident when it knows
-     * least. The chore steps down instead — evidence stays on the row, the CLAIM comes off it — and carries no
+     * least. The chore steps down instead, evidence stays on the row, the CLAIM comes off it, and carries no
      * prompt, because the honest next move is to measure again rather than to spend a second turn on a finding
      * nobody has re-checked. It cannot badge either, which is what stops the tile lighting for work already done. */
     if (ledger !== undefined && measuredAt !== undefined && ledger.ranAt > measuredAt) {
@@ -220,8 +220,8 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
 // two independent questions with two independent answers.
 export const ledgerKey = (repo: string, chore: string): string => `${repo}|${chore}`;
 
-/* Every chore in every repo, from one report. This is what both surfaces call — the panel groups the result, the
- * badge filters it — so there is exactly one traversal of the book in the codebase and adding a chore to CHORES
+/* Every chore in every repo, from one report. This is what both surfaces call, the panel groups the result, the
+ * badge filters it, so there is exactly one traversal of the book in the codebase and adding a chore to CHORES
  * reaches both surfaces without touching either. */
 export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[] => {
     const ledger = new Map(report.ledger.map((entry) => [ledgerKey(entry.repo, entry.chore), entry]));
@@ -232,10 +232,10 @@ export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[
 };
 
 /* WHAT THE RAIL IS ALLOWED TO SAY. A badge must mean "something happened here that you don't already know about",
- * never "here is a statistic" — the extension API states that bar and this is the function that holds this
+ * never "here is a statistic", the extension API states that bar and this is the function that holds this
  * surface to it. Three filters, and every one of them removes a case that would otherwise light the tile forever:
  *
- *   state === due   the obvious one — and it is also what keeps `stale` silent, since a measurement taken before
+ *   state === due   the obvious one, and it is also what keeps `stale` silent, since a measurement taken before
  *                   the last turn is not a fact anyone should be interrupted about.
  *   !settled        a turn has been spent on this chore and the re-measured evidence did not move.
  *   unseen digest   the owner has already LOOKED at this evidence in the panel. Acknowledgement is per digest

package/src/contract-lock.ts

@@ -1,24 +1,24 @@
-/* THE WIRE SURFACE, AS ONE COMPARABLE DOCUMENT — every zod schema this package exports, serialized to JSON
+/* THE WIRE SURFACE, AS ONE COMPARABLE DOCUMENT, every zod schema this package exports, serialized to JSON
  * Schema and sorted into a canonical shape. `contract.lock.json` at the package root is this function's
  * committed output, and the pair is what makes "did the contract change?" a question git can answer.
  *
  * Two readers depend on that answer. contract-lock.test.ts fails whenever the committed file is out of step
- * with the code, so a contract change always lands WITH its lock diff — visible in review, attributable to a
+ * with the code, so a contract change always lands WITH its lock diff, visible in review, attributable to a
  * commit. And prepass.mjs (invariant 6) compares the committed lock against its merge-base to insist that a
- * SHRUNK surface — a schema or field removed, a type changed — arrives as a `!` commit carrying a
+ * SHRUNK surface, a schema or field removed, a type changed, arrives as a `!` commit carrying a
  * `Breaking-Note:` trailer, which is what feeds the release's "Breaking changes" section and the update card's
  * warning. Additions pass freely; every persisted-manifest reader parses loosely, so growth breaks nobody.
  *
  * Serialized from the package's EXPORTS rather than a hand-kept list, on the repo's own rule (AGENTS.md:
  * "guard invariants by discovery, not enumeration"): a schema added tomorrow is in the lock tomorrow, and a
  * schema that stops being exported is a removal the lock shows. `unrepresentable: "any"` keeps the rare
- * function-valued corner from throwing — it serializes as `{}`, which still diffs when it moves. */
+ * function-valued corner from throwing, it serializes as `{}`, which still diffs when it moves. */
 
 import { z } from "zod";
 import * as contract from "./index.js";
 
 // Canonical ordering, so two runs of the same code are byte-identical and a lock diff is a contract diff
-// rather than a key-order shuffle. Arrays keep their order — for `required` and `enum` lists the order zod
+// rather than a key-order shuffle. Arrays keep their order, for `required` and `enum` lists the order zod
 // emits is stable, and sorting them would hide a reorder that is genuinely no change at all anyway.
 const sorted = (value: unknown): unknown => {
     if (Array.isArray(value)) {
@@ -43,7 +43,7 @@ export const currentLock = (): Record<string, unknown> => {
         }
         try {
             const schema = sorted(z.toJSONSchema(value, { unrepresentable: "any" })) as Record<string, unknown>;
-            // The dialect banner is identical on all ~500 entries — pure weight, no surface.
+            // The dialect banner is identical on all ~500 entries, pure weight, no surface.
             delete schema["$schema"];
             lock[name] = schema;
         } catch {
@@ -55,7 +55,7 @@ export const currentLock = (): Record<string, unknown> => {
     return lock;
 };
 
-/* ONE LINE PER SCHEMA, on purpose — not JSON.stringify(lock, null, 4). Pretty-printed, the lock is a 35k-line
+/* ONE LINE PER SCHEMA, on purpose, not JSON.stringify(lock, null, 4). Pretty-printed, the lock is a 35k-line
  * wall nobody scrolls; a line per export keeps it ~500 lines and makes `git diff` read as the list of WHICH
  * surfaces moved, which is the level a reviewer reviews at. The path-level detail lives in the tooling: the
  * lock test diffs parsed objects and prepass invariant 6 names the exact removed paths, so nothing is lost by

package/src/contracts/activity.contract.ts

@@ -1,7 +1,7 @@
 import { oc } from "@orpc/contract";
 import { ActivityListSchema, ActivityQuerySchema, ActivityStatusSchema } from "../schemas.js";
 
-// The activity audit feed (provider-agnostic; Discord is the first source). Read-only by design —
+// The activity audit feed (provider-agnostic; Discord is the first source). Read-only by design,
 // events are appended daemon-side only, so the log stays a trustworthy record of what the agent did.
 export const activityContract = {
     list: oc.route({ method: "GET", path: "/activity" }).input(ActivityQuerySchema).output(ActivityListSchema),

package/src/contracts/agent.contract.ts

@@ -14,7 +14,7 @@ import {
 } from "../schemas.js";
 
 // A turn EXECUTES as a detached daemon-side run: `run` starts it and acks with the run id; any number of
-// clients render it via `attach` (replay from a seq cursor, then live) — the initiating window holds no
+// clients render it via `attach` (replay from a seq cursor, then live), the initiating window holds no
 // special stream, so a reload, a second window, or another device attaches identically. `reply` un-parks a
 // turn waiting on any interactive card (plan approval, clarifying questions, a per-tool permission prompt);
 // steer injects a user message into the running turn; stop hard-cancels it daemon-side.
@@ -25,7 +25,7 @@ export const agentContract = {
     steer: oc.route({ method: "POST", path: "/agent/steer" }).input(SteerSchema).output(OkSchema),
     stop: oc.route({ method: "POST", path: "/agent/stop" }).input(StopTurnSchema).output(OkSchema),
     // Go back to a message: restore the workspace to that turn's checkpoint, drop the messages after it, and
-    // forget the provider session. CONFLICT while a turn is running — a restore cannot overwrite files an
+    // forget the provider session. CONFLICT while a turn is running, a restore cannot overwrite files an
     // agent is editing. NOT_FOUND when that message has no checkpoint to go back to.
     rewind: oc.route({ method: "POST", path: "/agent/rewind" }).input(RewindTurnSchema).output(RewindResultSchema),
     // The provider's slash commands as last published by one of its turns, so a conversation's `/` popover is

package/src/contracts/agents.contract.ts

@@ -24,14 +24,14 @@ import {
 
 // The fleet: every registered conversation-agent (see AgentSummarySchema). Registry-level actions (read,
 // rename, seen, archive) apply uniformly. For branch-backed conversations, `diff` is the worktree's CUMULATIVE
-// multi-repo delta vs its recorded per-repo bases — one flat change set per repo
+// multi-repo delta vs its recorded per-repo bases, one flat change set per repo
 // (AgentChanges), each file flagged `landed` or not, deliberately not the working tree's staged/unstaged
 // shape: a worktree the user never checks out has no index they could stage into. `land` merges the worktree
 // branches into the main tree (per-repo, conflicts reported, nothing lost on failure); `discard` removes
 // worktrees + branches + registry entry. Those branch actions reject workspace conversations explicitly. An
 // unknown {id} is NOT_FOUND; land/discard while the turn runs is CONFLICT.
-// `rename` sets the user-chosen display title — legal mid-turn (it touches no worktree state).
-// `seen`/`seenAll` stamp the read marker behind the cards' unread badge (AgentSummarySchema.seenAt) — also
+// `rename` sets the user-chosen display title, legal mid-turn (it touches no worktree state).
+// `seen`/`seenAll` stamp the read marker behind the cards' unread badge (AgentSummarySchema.seenAt), also
 // legal mid-turn, and like `rename` they never bump `updatedAt` (reading is not activity).
 //
 // ARCHIVE is the non-destructive counterpart to discard, and the one the board leans on: for an isolated
@@ -41,7 +41,7 @@ import {
 // surviving branch. Archiving a running agent is CONFLICT, same as land/discard.
 //
 // PURGE empties the archive, and it is `discard` applied to every agent already in there: worktree remnants,
-// branches and entries all go. Deliberately the whole archive and not a list of ids — the archive is the pile
+// branches and entries all go. Deliberately the whole archive and not a list of ids, the archive is the pile
 // of agents the user has already decided are over, so "clean it up" is one act with one confirmation, and a
 // per-id purge would be `discard`, which already exists. Never touches a running agent (a turn un-archives its
 // own agent, so there should be none) and answers with what it actually deleted: a teardown that fails on one
@@ -49,31 +49,31 @@ import {
 export const agentsContract = {
     list: oc.route({ method: "GET", path: "/agents" }).output(AgentsListSchema),
     archived: oc.route({ method: "GET", path: "/agents/archived" }).output(AgentsListSchema),
-    // The board's filter. Answers over BOTH halves of the fleet — the live roster and the archive — because
+    // The board's filter. Answers over BOTH halves of the fleet, the live roster and the archive, because
     // the board hides by design (the Finished lane windows to a handful, archived agents are off the roster
     // entirely), and a filter that reports "no matches" while the agent sits one click away is a lie. The
     // never-carded conversations that are neither are `sessions.list`'s query, which matches by the same rule.
     search: oc.route({ method: "GET", path: "/agents/search" }).input(AgentSearchQuerySchema).output(AgentSearchResultSchema),
     get: oc.route({ method: "GET", path: "/agents/{id}" }).input(AgentIdSchema).output(AgentSummarySchema),
     transcript: oc.route({ method: "GET", path: "/agents/{id}/transcript" }).input(AgentIdSchema).output(AgentTranscriptSchema),
-    /* SPEAK AS THE AGENT — append the user's words to the conversation's record as an assistant row, with no
+    /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
      * turn behind them and no reply. The row is marked `placed` for human readers (RestoredMessageSchema); the
      * provider session is FORGOTTEN in the same breath, rewind-style, so the next real turn opens a fresh
-     * runtime session seeded from the record — where the placed line reads as the agent's own words, because
+     * runtime session seeded from the record, where the placed line reads as the agent's own words, because
      * the handoff renders every assistant row identically. A running turn is CONFLICT: the illusion can only be
      * established between turns, and a concurrent turn would resume the very session this exists to retire. */
     place: oc.route({ method: "POST", path: "/agents/{id}/place" }).input(AgentPlaceSchema).output(OkSchema),
     rename: oc.route({ method: "POST", path: "/agents/{id}/rename" }).input(AgentRenameSchema).output(AgentSummarySchema),
-    // This agent's own land-at-completion posture — an override of the sandbox-wide `autoLand` setting; null
+    // This agent's own land-at-completion posture, an override of the sandbox-wide `autoLand` setting; null
     // clears it back to "inherit". Legal mid-turn on purpose: the setting is read at turn COMPLETION, so
     // flipping it while the agent works is exactly "hold THIS turn's work for review", the press that matters.
     autoLand: oc.route({ method: "POST", path: "/agents/{id}/auto-land" }).input(AgentAutoLandSchema).output(AgentSummarySchema),
-    /* THIS conversation's answer to a provider outage — an override of the sandbox-wide `resumeAfterOutage`
+    /* THIS conversation's answer to a provider outage, an override of the sandbox-wide `resumeAfterOutage`
      * setting; null clears it back to "inherit". The chat's offer at the moment a turn dies writes this and
      * never the global: the press happens inside one conversation and means "finish this piece of work", so
-     * its honest blast radius is that conversation. Sandbox ▸ Agent owns the default for everything else.
+     * its honest scope is that conversation. Sandbox > Agent owns the default for everything else.
      *
-     * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too — an outage kills a
+     * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too, an outage kills a
      * main-tree chat exactly as readily as an isolated one, and there is no branch involved either way. */
     resumeAfterOutage: oc
         .route({ method: "POST", path: "/agents/{id}/resume-after-outage" })