@intentic/sandbox-contract 1.176.2 → 1.209.0

package/src/chores/chores.ts

@@ -1,6 +1,7 @@
 import type { Advisory, ChoreSignals, OutdatedPackage, ProbeId, ProbeResult } from "../schemas.js";
 import { bucketOf, digestOf } from "./digest.js";
 import { CHORE_INVARIANTS, composeAsk, REPORT_INVARIANTS, TRIAGE_NOTE } from "./prompt.js";
+import { componentStem, frameworksOf, idiomRule, normalizePath, UI_FRAMEWORKS, usesTailwind } from "./stack.js";
 
 /* THE CHORE BOOK — what routine maintenance a repository is owed, and what has to be TRUE before we say so.
  *
@@ -36,6 +37,11 @@ import { CHORE_INVARIANTS, composeAsk, REPORT_INVARIANTS, TRIAGE_NOTE } from "./
 
 export type ChoreStance = "act" | "report";
 
+/* WHAT KIND OF CLAIM A CHORE MAKES ON SOMEONE'S ATTENTION. Four of them, ordered from "this is a risk you are
+ * carrying right now" to "this is worth thinking about this quarter" — see CHORE_KINDS at the foot of this file,
+ * which carries the argument and the words the panel groups under. */
+export type ChoreKind = "carrying" | "accruing" | "drifting" | "surveying";
+
 export interface ChoreContext {
     // Root-relative repo dir; the empty string is the workspace's own root repo.
     readonly repo: string;
@@ -70,6 +76,11 @@ export interface Chore {
     readonly icon: string;
     // The one-line standing description, shown whether or not the chore is currently due.
     readonly description: string;
+    /* WHICH OF THE FOUR KINDS OF CLAIM THIS IS (CHORE_KINDS, at the foot of this file). It decides the book's
+     * order and the panel's grouping, and it is a FIELD rather than a comment above the array for exactly that
+     * reason: the reading order is the one editorial claim this surface makes, and a claim spelled as a comment
+     * beside a hand-maintained list is one nobody can check and the compiler cannot keep. */
+    readonly kind: ChoreKind;
     /* THE RULE, in words — what has to be true for this chore to be due, stated so a reader can check it against
      * the evidence below it and disagree.
      *
@@ -82,14 +93,21 @@ export interface Chore {
      * cannot check English. The rule for writing one: say the THRESHOLD, not the subject. "Duplication is high"
      * is a topic; "more than 5% of the tree is duplicated" is a criterion. */
     readonly criterion: string;
-    /* WHETHER THIS IS A QUESTION WORTH ASKING OF THIS REPOSITORY AT ALL — returns undefined when it is, and a
-     * plain-language reason when it is not ("this repository ships no Dockerfile").
+    /* WHETHER THIS IS A QUESTION WORTH ASKING OF THIS REPOSITORY AT ALL — returns undefined when it is, and what
+     * is MISSING when it is not.
      *
      * Distinct from `assess`, and the distinction is the whole point: `assess` asks whether the answer is yes,
      * this asks whether the question makes sense. "Re-read the documentation against the code" in a repository
      * with no documentation is not a chore that is currently clear — it is one that will never apply here, and
      * showing it as clear says we checked something we cannot check. A chore that does not apply is dropped from
-     * the panel entirely; only a footer records that it was considered.
+     * the panel entirely; a line in the scope strip records that it was considered.
+     *
+     * A BARE CAUSE — "no Dockerfile", never "this repository ships no Dockerfile, so there is no image to slim".
+     * Same spelling as `ProbeSpec.unavailable`, and for the same reason both surfaces need: one absent
+     * package.json rules out five chores, and five sentences saying so at length is the wall of text this phrasing
+     * exists to prevent. The panel groups by this string, so the CONSEQUENCE — which chores it costs — is the list
+     * beside it rather than a clause repeated inside every entry. Identical causes must be spelled identically or
+     * they group apart.
      *
      * Reads `signals` rather than probes on purpose: applicability is about what the repository IS, which is a
      * fact the daemon holds without measuring anything. If a gate needed a probe it would be describing the
@@ -152,6 +170,11 @@ const JSCPD_REPORT = `${JSCPD_DIR}/jscpd-report.json`;
 // called "root" — so it is spelled out here, once, rather than at every call site that builds a prompt.
 export const repoLabel = (repo: string): string => (repo === `root` || repo === `` ? `the workspace root repository` : repo);
 
+// The same repository, named for a surface that has a 16rem column or a chip to say it in. `repoLabel` is prose
+// and reads as prose inside a sentence ("update dependencies in the workspace root repository"); a rail row wants
+// the name on its own, and "the workspace root repository" truncates to "the workspace root reposi…" there.
+export const repoName = (repo: string): string => (repo === `root` || repo === `` ? `workspace root` : repo);
+
 const plural = (count: number, one: string, many = `${one}s`): string => `${count} ${count === 1 ? one : many}`;
 
 // One outdated dependency, as the panel lists it. The semver step leads, because it is what decides whether the
@@ -182,8 +205,9 @@ const security: Chore = {
     title: `Patch security advisories`,
     icon: `shield`,
     description: `Published advisories against this dependency tree, and the ones whose fix is a version bump.`,
+    kind: `carrying`,
     criterion: `pnpm audit reports an advisory of high or critical severity against the resolved tree.`,
-    applies: (signals) => (signals.shape.lockfile ? undefined : `there is no lockfile here, so nothing resolves to a tree that could be audited`),
+    applies: (signals) => (signals.shape.lockfile ? undefined : `no lockfile`),
     stance: `act`,
     needs: [`audit`],
     cadenceMs: 0,
@@ -211,7 +235,10 @@ const security: Chore = {
             headline: `${plural(blocking.length, `advisory`, `advisories`)}, ${patchable.length} with a published fix`,
             detail: blocking
                 .toSorted((left, right) => left.name.localeCompare(right.name))
-                .map((advisory) => `${advisory.severity} · ${advisory.name} — ${advisory.title}${advisory.patched === undefined ? ` (no patch yet)` : ``}`),
+                .map(
+                    (advisory) =>
+                        `${advisory.severity} · ${advisory.name} — ${advisory.title}${advisory.patched === undefined ? ` (no patch yet)` : ``}`,
+                ),
             // Identities, not counts: every advisory that appears or is fixed is genuinely news, and there is no
             // ordinary drift here to absorb.
             digest: digestOf(...blocking.map((advisory) => `${advisory.name}@${advisory.severity}`).toSorted()),
@@ -245,8 +272,9 @@ const dependencies: Chore = {
     title: `Update dependencies`,
     icon: `arrow-circle-up`,
     description: `How far behind the registry this tree has drifted, and which majors are waiting.`,
+    kind: `accruing`,
     criterion: `A dependency is a major version behind, or more than 20 are behind by any amount.`,
-    applies: (signals) => (signals.shape.packageManifest ? undefined : `this repository has no package.json, so there is no npm dependency tree to be behind`),
+    applies: (signals) => (signals.shape.packageManifest ? undefined : `no package.json`),
     stance: `act`,
     needs: [`outdated`],
     cadenceMs: 30 * DAY_MS,
@@ -294,8 +322,9 @@ const deadCode: Chore = {
     title: `Clear out dead code`,
     icon: `trash`,
     description: `Files, exports and dependencies nothing in this repository references any more.`,
+    kind: `accruing`,
     criterion: `knip reports at least one unreferenced file, export or dependency.`,
-    applies: (signals) => (signals.shape.packageManifest ? undefined : `this repository is not a Node project, and knip only reads those`),
+    applies: (signals) => (signals.shape.packageManifest ? undefined : `no package.json`),
     stance: `act`,
     needs: [`knip`],
     cadenceMs: 14 * DAY_MS,
@@ -358,6 +387,7 @@ const duplication: Chore = {
     title: `Find duplication worth collapsing`,
     icon: `clone`,
     description: `Copy-paste that has grown past a fifth of a percent of the tree. Reports only — extracting is a design call.`,
+    kind: `drifting`,
     criterion: `jscpd reports more than 5% of the scanned tree duplicated.`,
     stance: `report`,
     needs: [`jscpd`],
@@ -400,7 +430,9 @@ const duplication: Chore = {
     done: `Done when every clone in the report has either a named extraction or a one-line reason it should stay.`,
 };
 
-/* DOCUMENTATION. The evidence is a package with no architecture document, which sounds like a coverage statistic
+/* DOCUMENTATION. The evidence is a package with no README — which IS its architecture document in this
+ * workspace, so this is a stat on the package directory rather than a lookup in a parallel tree. It sounds like
+ * a coverage statistic
  * and would be one if the rail read it directly. It does not: the digest is the SET of undocumented package
  * directories, so a long-standing backlog goes quiet after it is seen once, and a package appearing that nothing
  * explains is an event that speaks. That is the whole difference between this being useful and being a nag. */
@@ -408,9 +440,10 @@ const documentation: Chore = {
     id: `documentation-refresh`,
     title: `Document what nothing explains`,
     icon: `file-edit`,
-    description: `Packages in this repository with no architecture document — new ones first.`,
-    criterion: `A workspace package has no docs/architecture document.`,
-    applies: (signals) => (signals.packages.length > 0 ? undefined : `this repository is not a workspace, so it has no packages to document one by one`),
+    description: `Packages in this repository with no README — new ones first.`,
+    kind: `drifting`,
+    criterion: `A workspace package has no README.`,
+    applies: (signals) => (signals.packages.length > 0 ? undefined : `not a workspace`),
     stance: `act`,
     needs: [],
     cadenceMs: 90 * DAY_MS,
@@ -426,7 +459,7 @@ const documentation: Chore = {
             severity: `info`,
             why:
                 `${plural(undocumented.length, `package`)} of ${context.signals.packages.length} in ${repoLabel(context.repo)} have no ` +
-                `docs/architecture document: ${undocumented.map((entry) => entry.dir).join(`, `)}.`,
+                `README: ${undocumented.map((entry) => entry.dir).join(`, `)}.`,
         };
     },
     diagnosis: `A package nobody can read the shape of gets worked in by guesswork, and the guesses accumulate.`,
@@ -464,6 +497,7 @@ const complexity: Chore = {
     title: `Simplify what everything waits on`,
     icon: `wave-pulse`,
     description: `Files that both churn and carry the repository — where edits are slow and ripple outward.`,
+    kind: `accruing`,
     criterion: `A file in the hotspot ranking is also a key module, or its branching is three times the median of that ranking.`,
     stance: `act`,
     needs: [],
@@ -524,8 +558,9 @@ const runtime: Chore = {
     title: `Move off an end-of-life runtime`,
     icon: `bolt`,
     description: `Whether the Node this sandbox runs still receives security patches.`,
+    kind: `carrying`,
     criterion: `The Node release this sandbox runs is past its end-of-life date, or within 90 days of it.`,
-    applies: (signals) => (signals.shape.packageManifest ? undefined : `this repository is not a Node project, so the sandbox's runtime is not its concern`),
+    applies: (signals) => (signals.shape.packageManifest ? undefined : `no package.json`),
     stance: `act`,
     needs: [],
     cadenceMs: 0,
@@ -544,7 +579,9 @@ const runtime: Chore = {
         // Which packages would have to be argued with, so the finding names the work rather than only the fact.
         const pinned = context.signals.packages.filter((entry) => entry.engines?.[`node`] !== undefined);
         return {
-            headline: past ? `Node ${major} stopped receiving security patches ${days} days ago` : `Node ${major} reaches end of life in ${days} days`,
+            headline: past
+                ? `Node ${major} stopped receiving security patches ${days} days ago`
+                : `Node ${major} reaches end of life in ${days} days`,
             detail: [
                 `running · ${context.node}`,
                 `end of life · ${eol}`,
@@ -586,8 +623,9 @@ const libraries: Chore = {
     title: `Settle on one library per job`,
     icon: `box`,
     description: `Two dependencies solving the same problem — both shipped, both maintained, one picked at random.`,
+    kind: `drifting`,
     criterion: `Two or more installed dependencies do the same job.`,
-    applies: (signals) => (signals.packages.length > 0 ? undefined : `this repository is not a workspace, so there are no package manifests to compare`),
+    applies: (signals) => (signals.packages.length > 0 ? undefined : `not a workspace`),
     stance: `report`,
     needs: [],
     cadenceMs: 90 * DAY_MS,
@@ -618,6 +656,351 @@ const libraries: Chore = {
     done: `Done when every overlapping pair has a recommendation with a call-site count behind it, or a reason the overlap is fine.`,
 };
 
+/* ---- THE FRONT-END CHORES -------------------------------------------------------------------------------------
+ *
+ * Four chores that only exist where a UI framework does, kept together because they share one gate and one
+ * probe — and split across the reading order in CHORES, since where a row belongs is decided by what KIND of
+ * finding it is, not by which file paragraph it was written in.
+ *
+ * They gate on `shape.deps` rather than on `signals.packages`, and that is not interchangeable. `packages` is
+ * populated from pnpm-workspace.yaml, so it is EMPTY for a repository that is not a monorepo — which is what a
+ * Vite app, a Next app and an Angular CLI project all are. A framework gate reading it would be permanently dark
+ * in the overwhelming majority of the repositories these four were written for, and dark silently: the chores
+ * would not appear, the footer would say the repository has no packages, and nothing would look broken.
+ *
+ * All four also say something the rest of the book does not have to. A component, a class name and a bundle chunk
+ * are things nobody sees the whole of — you read one component at a time, and the tenth copy of a button looks
+ * exactly like the first nine did. That is the same argument the whole surface rests on, just further from the
+ * places a compiler will ever help. */
+
+// How many rows of evidence a UI finding lists before it is a wall rather than a list. The standing count still
+// leads the headline; this only bounds what is enumerated underneath it.
+const DETAIL_LIMIT = 8;
+
+const FRAMEWORK_LABELS = UI_FRAMEWORKS.map((framework) => framework.label).join(`, `);
+
+// One gate, one cause, four chores. Built from the table so that a framework added to stack.ts cannot leave a
+// stale list of names behind in a reason nobody re-reads.
+const needsFramework = (signals: ChoreSignals): string | undefined =>
+    frameworksOf(signals.shape.deps).length > 0 ? undefined : `no ${FRAMEWORK_LABELS}`;
+
+const bytesLabel = (bytes: number): string => (bytes >= 1024 * 1024 ? `${(bytes / (1024 * 1024)).toFixed(1)} MB` : `${Math.round(bytes / 1024)} kB`);
+
+/* BUNDLE. What a browser downloads before anything appears, which is the fact about a front-end that is furthest
+ * from anything visible in an editor: every dependency looks the same size in an import statement.
+ *
+ * The criterion is a SHARE, and that is deliberate — it is the second exception to the book's leader-relative
+ * rule, and it earns the same defence duplication's 5% does. A byte threshold would need a different value for a
+ * marketing page and an IDE, would be argued about forever, and would be wrong the moment either one grew. "One
+ * chunk is more than half of everything you ship" needs no calibration: it says the build is not split, which is
+ * true or false at any size. A well-split app has its largest chunk well under this whatever it weighs, and a
+ * small app that genuinely is one chunk trips it and is right to — that IS its entire download.
+ *
+ * Report-stance. Where the split boundaries go is a routing and product decision, and an agent that lazily
+ * imported things unattended at three in the morning would be making it. */
+const BUNDLE_SHARE_FLOOR = 50;
+// Below this there is no ranking to be an outlier in — two files cannot tell you anything about how a build is
+// divided, and the largest of them is over half by arithmetic rather than by fault.
+const BUNDLE_MIN_ASSETS = 3;
+
+/* An asset's name with its content hash taken out — `assets/vendor-DlAUqK2U.js` becomes `assets/vendor.js`.
+ *
+ * Without this the digest changes on every single build, because a content hash changing is the entire point of a
+ * content hash. The chore would badge after every `pnpm build` while reporting nothing new, which is precisely
+ * the lit-every-day failure the digest exists to prevent.
+ *
+ * Eight or more characters containing a digit, immediately before the final extension: long enough to leave
+ * `vendor-react.js` and `.min.js` alone, specific enough to catch Vite's `-DlAUqK2U` and webpack's `.9f2a1b0c`. */
+const stableAsset = (path: string): string => path.replace(/[.-](?=[A-Za-z0-9_-]*[0-9])[A-Za-z0-9_-]{8,}(\.[a-z0-9]+)$/, `$1`);
+
+const bundleWeight: Chore = {
+    id: `bundle-weight`,
+    title: `Split what the browser downloads first`,
+    icon: `download`,
+    description: `What the last build put on disk, and whether it arrives as one download or several.`,
+    kind: `accruing`,
+    criterion: `A single asset is more than half of the build's total transfer size.`,
+    applies: needsFramework,
+    stance: `report`,
+    needs: [`bundle`],
+    cadenceMs: 30 * DAY_MS,
+    assess: (context) => {
+        const facts = factsOf(context, `bundle`);
+        if (facts === undefined) {
+            return undefined;
+        }
+        const { assets, totalGzip, dir } = facts.bundle;
+        if (assets.length < BUNDLE_MIN_ASSETS || totalGzip === 0) {
+            return undefined;
+        }
+        // By GZIP, not by raw bytes. What is on disk is not what crosses the wire, and a large but highly
+        // compressible asset — a source map comment, a big JSON blob — is not the download this is about.
+        const ranked = assets.toSorted((left, right) => right.gzip - left.gzip);
+        const largest = ranked[0];
+        if (largest === undefined) {
+            return undefined;
+        }
+        const share = (largest.gzip / totalGzip) * 100;
+        if (share < BUNDLE_SHARE_FLOOR) {
+            return undefined;
+        }
+        return {
+            headline: `${largest.path} is ${Math.round(share)}% of the ${bytesLabel(totalGzip)} this build ships`,
+            detail: ranked
+                .slice(0, DETAIL_LIMIT)
+                .map((asset) => `${bytesLabel(asset.gzip)} gzipped · ${asset.path} (${bytesLabel(asset.bytes)} on disk)`),
+            // The bucketed total and the hash-stripped identities of the biggest chunks. A rebuild of the same
+            // code is silent; a new heavy chunk appearing, or the whole thing doubling, is not.
+            digest: digestOf(
+                `total:${bucketOf(totalGzip)}`,
+                ...ranked
+                    .slice(0, 5)
+                    .map((asset) => stableAsset(asset.path))
+                    .toSorted(),
+            ),
+            // Not a risk being carried, however large. `warning` is reserved for something with a clock on it.
+            severity: `info`,
+            why:
+                `The build output in ${dir}/ of ${repoLabel(context.repo)} is ${bytesLabel(totalGzip)} gzipped across ` +
+                `${plural(assets.length, `asset`)}, and ${largest.path} alone is ${bytesLabel(largest.gzip)} of it — ${Math.round(share)}%. ` +
+                `The next largest are ${ranked
+                    .slice(1, 4)
+                    .map((asset) => `${asset.path} (${bytesLabel(asset.gzip)})`)
+                    .join(`, `)}. ` +
+                `This is the last build someone ran, read off disk; nothing rebuilt it to measure.`,
+        };
+    },
+    diagnosis: `Everything in the first chunk is downloaded and parsed before anything renders, whether or not the visitor needed it.`,
+    goal:
+        `Find out what is actually IN the dominant chunk before proposing anything — the repository's own bundler can report this, and a ` +
+        `recommendation made without it is guesswork. Then report the split worth making: which routes or features could load on demand, ` +
+        `which dependencies are pulled in wholesale for one function, and which are only used behind an interaction nobody has yet had. ` +
+        `Name the boundary for each and estimate what it saves. Where the chunk is genuinely all first-paint code, say so and close it.`,
+    done: `Done when every recommendation names a specific import boundary and the bytes it would move out of the first download.`,
+};
+
+/* FRAMEWORK IDIOMS. A migration nobody finished, which is the most ordinary state for a front-end of any age: the
+ * new way arrived, the new files use it, and the old files keep working — so nothing ever forces the rest.
+ *
+ * The digest is the one place this chore differs in shape from its neighbours, and it has to. Digesting the file
+ * identities, the way the documentation chore does, would re-badge every time anyone touched any of two hundred
+ * files, because a migration in progress is a set that changes constantly. So it digests the BUCKETED COUNT per
+ * idiom instead: a kind of legacy code appearing where there was none speaks, real progress through a bucket
+ * speaks, and one more file drifting in or out of a set of two hundred does not. */
+const frameworkIdiom: Chore = {
+    id: `framework-idiom`,
+    title: `Finish the framework migrations`,
+    icon: `history`,
+    description: `Code still written the way the framework used to recommend, long after it stopped.`,
+    kind: `accruing`,
+    criterion: `A file uses a framework idiom that framework's own maintainers have replaced.`,
+    applies: needsFramework,
+    stance: `act`,
+    needs: [`ui`],
+    cadenceMs: 60 * DAY_MS,
+    assess: (context) => {
+        const facts = factsOf(context, `ui`);
+        if (facts === undefined) {
+            return undefined;
+        }
+        /* Two rules are dropped rather than shown, and the second is the one that would have made this chore
+         * embarrassing.
+         *
+         * AN IDIOM THIS BUILD HAS NEVER HEARD OF. The daemon composes the sweep from its own copy of the table, so
+         * a sandbox image ahead of the browser can report a rule that has no label or replacement here — and a row
+         * saying "42 files use react-foo" with no idea what to do about them is worse than no row.
+         *
+         * AN IDIOM BELONGING TO A FRAMEWORK THIS REPOSITORY DOES NOT USE. A probe's command is a fixed string, so
+         * every rule in the table is swept in every repository, and an Angular pattern gets its chance in a Vue
+         * codebase: `RouterModule.forRoot` inside a comment, a `*ngIf` in an example string, and — the case that
+         * caught this — the book's own rule table quoting its own patterns back at it. What the repository
+         * DECLARES is the arbiter, the same `deps` the gate above reads. */
+        const frameworks = new Set(frameworksOf(context.signals.shape.deps).map((framework) => framework.id));
+        const found = facts.scan.idioms.flatMap(({ id, files }) => {
+            const rule = idiomRule(id);
+            return rule === undefined || !frameworks.has(rule.framework) || files.length === 0 ? [] : [{ rule, files }];
+        });
+        if (found.length === 0) {
+            return undefined;
+        }
+        const total = found.reduce((sum, entry) => sum + entry.files.length, 0);
+        const ranked = found.toSorted((left, right) => right.files.length - left.files.length);
+        return {
+            headline: `${plural(found.length, `retired idiom`)} still in use, across ${plural(total, `file`)}`,
+            detail: ranked.map((entry) => `${plural(entry.files.length, `file`)} · ${entry.rule.label} → ${entry.rule.replacement}`),
+            digest: digestOf(...ranked.map((entry) => `${entry.rule.id}:${bucketOf(entry.files.length)}`).toSorted()),
+            severity: `info`,
+            why:
+                `${repoLabel(context.repo)} still uses ${plural(found.length, `idiom`)} its framework has replaced: ` +
+                `${ranked.map((entry) => `${entry.rule.label} in ${plural(entry.files.length, `file`)} (replaced by ${entry.rule.replacement})`).join(`; `)}. ` +
+                `A sample of the files: ${ranked
+                    .flatMap((entry) => entry.files.slice(0, 3))
+                    .slice(0, DETAIL_LIMIT)
+                    .join(`, `)}.`,
+        };
+    },
+    diagnosis: `A retired idiom keeps working until the major release that drops it, and then it is an emergency inside somebody else's upgrade.`,
+    goal:
+        `Take ONE idiom, the one with the most files, and no more. Convert the files where the conversion is mechanical and the behaviour ` +
+        `is provably identical. Stop at the first file that needs a design decision — a class component with genuine error-boundary ` +
+        `semantics, an NgModule that something outside the repository imports — leave it, and say what it would take. Do not convert an ` +
+        `idiom the repository has deliberately kept: if the newest code uses it too, that is a choice, and reporting it as one is the ` +
+        `useful answer.`,
+    done: `Done when a re-scan reports fewer files on that idiom, the repository's type-check and tests pass, and every file you skipped has a one-line reason.`,
+};
+
+/* COMPONENTS. Two components that are the same component, which is the `library-overlap` finding turned inward:
+ * somebody needed a button, did not find the one that existed, and wrote a second one. It is the most ordinary
+ * kind of duplication in a front-end and the one no tool complains about, because both files are perfectly good
+ * code and neither knows the other exists.
+ *
+ * TWO KINDS OF EVIDENCE, and they catch opposite failures. A NAME FAMILY catches components that were written
+ * separately and never shared a line — `BaseButton.vue` and `ButtonV2.tsx` reduce to the same stem, and no clone
+ * detector will ever connect them. A CLONE PAIR catches the reverse: two components with unrelated names doing
+ * the same work, which is what jscpd is actually good at, filtered to the pairs where both sides are components
+ * so it is a finding about the UI rather than a slice of the repo-wide duplication chore.
+ *
+ * It needs jscpd rather than reading it if present. Half a measurement would let the row claim it had looked for
+ * shared logic in a repository where that sweep has never run — the exact "measured and found nothing" lie the
+ * `unavailable` state exists to make impossible. jscpd is already running weekly for the duplication chore in any
+ * Node repository, so the honest choice is also the free one. */
+const componentOverlap: Chore = {
+    id: `component-overlap`,
+    title: `Settle on one component per job`,
+    icon: `copy`,
+    description: `Components built twice — the same name in two places, or the same logic under two names.`,
+    kind: `drifting`,
+    criterion: `Two component files reduce to the same name, or a duplicated block spans two components.`,
+    applies: needsFramework,
+    stance: `report`,
+    needs: [`ui`, `jscpd`],
+    cadenceMs: 90 * DAY_MS,
+    assess: (context) => {
+        const ui = factsOf(context, `ui`);
+        const jscpd = factsOf(context, `jscpd`);
+        if (ui === undefined || jscpd === undefined) {
+            return undefined;
+        }
+        const byStem = new Map<string, string[]>();
+        for (const path of ui.scan.components) {
+            const stem = componentStem(path);
+            if (stem !== undefined) {
+                byStem.set(stem, [...(byStem.get(stem) ?? []), normalizePath(path)]);
+            }
+        }
+        const families = [...byStem]
+            .filter(([, paths]) => paths.length > 1)
+            .map(([stem, paths]) => ({ stem, paths: paths.toSorted() }))
+            .toSorted((left, right) => right.paths.length - left.paths.length);
+        // Only the clones with a component on BOTH sides. A component that shares a block with a utility module
+        // is the duplication chore's finding, not this one, and reporting it here would be two rows lighting for
+        // one fact.
+        const inventory = new Set(ui.scan.components.map(normalizePath));
+        const pairs = jscpd.duplication.top.filter(
+            (clone) => inventory.has(normalizePath(clone.first)) && inventory.has(normalizePath(clone.second)),
+        );
+        if (families.length === 0 && pairs.length === 0) {
+            return undefined;
+        }
+        const parts = [
+            ...(families.length === 0 ? [] : [`${plural(families.length, `name`)} used by more than one component`]),
+            ...(pairs.length === 0 ? [] : [`${plural(pairs.length, `clone`)} spanning two of them`]),
+        ];
+        return {
+            headline: parts.join(`, `),
+            detail: [
+                ...families.slice(0, DETAIL_LIMIT).map((family) => `${family.stem} · ${family.paths.join(`, `)}`),
+                ...pairs.map((clone) => `${clone.lines} shared lines · ${normalizePath(clone.first)} ↔ ${normalizePath(clone.second)}`),
+            ],
+            // Identities on both halves: every component that joins or leaves a family, and every clone pair that
+            // appears, is genuinely a new fact rather than drift in a number.
+            digest: digestOf(
+                ...families.map((family) => `${family.stem}:${family.paths.join(`+`)}`).toSorted(),
+                ...pairs.map((clone) => `${normalizePath(clone.first)}|${normalizePath(clone.second)}`).toSorted(),
+            ),
+            severity: `info`,
+            why:
+                `${repoLabel(context.repo)} has ${parts.join(` and `)}, out of ${plural(ui.scan.components.length, `component file`)} scanned. ` +
+                `${
+                    families.length === 0
+                        ? ``
+                        : `The names: ${families
+                              .slice(0, DETAIL_LIMIT)
+                              .map((family) => `${family.stem} (${family.paths.join(`, `)})`)
+                              .join(`; `)}. `
+                }` +
+                `${pairs.length === 0 ? `` : `The clones: ${pairs.map((clone) => `${normalizePath(clone.first)} ↔ ${normalizePath(clone.second)}, ${clone.lines} lines`).join(`; `)}.`}`,
+        };
+    },
+    diagnosis: `A component built twice is maintained once — whichever copy the next person happens to open is the one that gets the fix.`,
+    goal:
+        `Read every file in each group before saying anything about it; a shared name is a reason to look, not a finding on its own. For ` +
+        `each group, say whether these genuinely do the same job, and if they do, name the one to keep and count the call sites that would ` +
+        `have to move. Where the answer is that the same LOGIC is duplicated rather than the whole component — the same fetch and loading ` +
+        `state, the same form validation, the same list virtualization written twice — say so, and name the hook or composable it should ` +
+        `become and where it would live. Where two components share a name and nothing else, say that too and close it: a false family is ` +
+        `worth one line, and the next reader needs to know it was considered.`,
+    done: `Done when every group has either a component to keep with a call-site count, a shared unit to extract with a home, or a reason it is fine.`,
+};
+
+/* TAILWIND. A design system exists to make a decision once; an arbitrary value is that decision being made again,
+ * inline, by whoever was in the file. What makes this measurable rather than a matter of taste is that Tailwind
+ * spells the bypass out loud — `bg-[#3b82f6]` is the palette being stepped around, in the markup, in a form no
+ * reviewer can miss and no linter mentions.
+ *
+ * Deliberately NOT every arbitrary value. `grid-cols-[1fr_auto]` is the feature working as intended and there is
+ * no token it should have been; matching those would make this an objection to Tailwind rather than a finding
+ * about this repository. Only colours and pixel sizes, which are the two things the theme definitely already has
+ * an answer for. */
+const tailwindBypass: Chore = {
+    id: `tailwind-arbitrary-values`,
+    title: `Put hard-coded styles back on the scale`,
+    icon: `palette`,
+    description: `Colours and sizes written inline in the markup, around the theme that already defines them.`,
+    kind: `drifting`,
+    criterion: `A Tailwind class hard-codes a colour or a pixel size instead of using the theme's scale.`,
+    applies: (signals) => (usesTailwind(signals.shape.deps) ? undefined : `no Tailwind`),
+    stance: `act`,
+    needs: [`ui`],
+    cadenceMs: 30 * DAY_MS,
+    assess: (context) => {
+        const facts = factsOf(context, `ui`);
+        if (facts === undefined) {
+            return undefined;
+        }
+        const { bypasses } = facts.scan;
+        if (bypasses.length === 0) {
+            return undefined;
+        }
+        const total = bypasses.reduce((sum, entry) => sum + entry.count, 0);
+        const worst = bypasses.toSorted((left, right) => right.count - left.count).slice(0, DETAIL_LIMIT);
+        return {
+            headline: `${plural(total, `hard-coded value`)} across ${plural(bypasses.length, `file`)}`,
+            detail: worst.map((entry) => `${entry.path} · ${plural(entry.count, `value`)}`),
+            // The worst files by identity — a new file arriving at the top of this list is the event — with the
+            // spread and the total riding along bucketed, because both drift by one every time anyone writes
+            // markup and neither is worth interrupting somebody about.
+            digest: digestOf(...worst.map((entry) => entry.path).toSorted(), `files:${bucketOf(bypasses.length)}`, `total:${bucketOf(total)}`),
+            severity: `info`,
+            why:
+                `${repoLabel(context.repo)} has ${plural(total, `Tailwind class`, `Tailwind classes`)} hard-coding a colour or a pixel size ` +
+                `across ${plural(bypasses.length, `file`)}; the heaviest are ` +
+                `${worst
+                    .slice(0, 5)
+                    .map((entry) => `${entry.path} (${entry.count})`)
+                    .join(`, `)}.`,
+        };
+    },
+    diagnosis: `Every inline colour is a place the theme cannot reach — a palette change lands everywhere except the files that opted out of it.`,
+    goal:
+        `Read the theme first — the Tailwind config, or the CSS that defines the tokens — so you know what the scale actually offers. Then ` +
+        `replace the values that have a token: an exact palette match, a spacing step, a type size. Where a value is CLOSE to a token but ` +
+        `not equal, do not round it silently; that is a visual change wearing a refactor's clothes. List those separately with both values ` +
+        `and let the owner decide. Where a value has no token and should — a brand colour used in nine places — say that the theme is ` +
+        `missing an entry rather than editing nine files.`,
+    done: `Done when a re-scan reports fewer hard-coded values, nothing renders differently, and every value you left has a one-line reason.`,
+};
+
 /* THE SURVEYS. Chores with no measurement at all, and they are here because the absence of a measurement is not
  * the absence of value — these are the reviews a codebase silently rots without, and none of them can be detected
  * by a tool. Their trigger is the calendar, and the ledger is what makes that trigger honest: a survey is due
@@ -655,6 +1038,10 @@ const survey = ({ id, title, icon, description, diagnosis, goal, done, cadenceDa
     title,
     icon,
     description,
+    // Not a parameter of SurveySpec, and it never will be: a survey has no measurement, so "due because it has
+    // been that long" IS the surveying kind. The two are the same claim spelled twice, and the test below holds
+    // them to it in both directions.
+    kind: `surveying`,
     criterion: `${cadenceDays} days have passed since this review was last run.`,
     applies,
     stance: `report`,
@@ -693,10 +1080,9 @@ const patterns = survey({
         `estimate the size of the conversion. Do not convert anything.`,
     done: `Done when each concern has a named convention, a reference file, and a count of the sites that diverge from it.`,
     cadenceDays: 90,
-    applies: (signals) =>
-        signals.totals.files >= PATTERNS_FLOOR
-            ? undefined
-            : `this repository has ${signals.totals.files} indexed files — too few for cross-cutting patterns to have diverged`,
+    // The one cause that is a measurement rather than an absence, and it still groups: every chore gated on size
+    // is gated on the SAME size, so the string is the same string.
+    applies: (signals) => (signals.totals.files >= PATTERNS_FLOOR ? undefined : `only ${signals.totals.files} indexed files`),
 });
 
 const deprecated = survey({
@@ -712,7 +1098,7 @@ const deprecated = survey({
         `replacement for each. Change nothing.`,
     done: `Done when every deprecation has call sites cited, a replacement named, and the release it is expected to break in.`,
     cadenceDays: 90,
-    applies: (signals) => (signals.shape.packageManifest ? undefined : `this repository declares no dependencies whose deprecations could be read`),
+    applies: (signals) => (signals.shape.packageManifest ? undefined : `no package.json`),
 });
 
 /* THE CHORE THAT NAMED THE PROBLEM. Gated on documents actually EXISTING, which is the whole reason `applies`
@@ -720,8 +1106,10 @@ const deprecated = survey({
  * re-read, and the first thing an owner of a fresh workspace sees is an offer to re-read documentation they have
  * never written. That is not a chore being wrong about a threshold — it is the surface admitting it never looked.
  *
- * Note which fact it gates on: the DOCUMENTS, not the directory. An empty `docs/architecture/` is a directory
- * somebody made and never filled, and a gate on the directory would put the chore back exactly where it started. */
+ * Note which fact it gates on: the MAP, not the directory. An empty `docs/architecture/` is a directory somebody
+ * made and never filled, and a gate on the directory would put the chore back exactly where it started. The
+ * survey then reads the package READMEs too — they are the package pages — but a repo with no map has not been
+ * documented at all, and that is the case worth staying quiet for. */
 const documentationDrift = survey({
     id: `documentation-drift`,
     title: `Re-read the documentation against the code`,
@@ -734,7 +1122,7 @@ const documentationDrift = survey({
         `what, which file to change — over prose that has merely aged. Do not rewrite the documents; produce the list of what is wrong.`,
     done: `Done when every architecture document has been read and every false claim is listed with both sides cited.`,
     cadenceDays: 90,
-    applies: (signals) => (signals.shape.docs.length > 0 ? undefined : `this repository has no architecture documents to re-read`),
+    applies: (signals) => (signals.shape.docs.length > 0 ? undefined : `no architecture documents`),
 });
 
 /* THE TWO CHORES THAT ONLY EXIST WHERE THEIR SUBJECT DOES. Both are surveys — nothing here can measure whether a
@@ -756,7 +1144,7 @@ const pipelines = survey({
         `because it genuinely has to be, say so — a pipeline that is honestly expensive is not a finding.`,
     done: `Done when every finding names a file, a step, and a concrete change, and anything deliberately slow is called out as such.`,
     cadenceDays: 90,
-    applies: (signals) => (signals.shape.ci.length > 0 ? undefined : `this repository defines no CI pipeline`),
+    applies: (signals) => (signals.shape.ci.length > 0 ? undefined : `no CI pipeline`),
 });
 
 const images = survey({
@@ -772,28 +1160,58 @@ const images = survey({
         `Dockerfiles — an image that fails to build is a much worse problem than one that is larger than ideal.`,
     done: `Done when every finding cites a Dockerfile line and names the change, with the ones that would need a base-image swap called out separately.`,
     cadenceDays: 90,
-    applies: (signals) => (signals.shape.dockerfiles.length > 0 ? undefined : `this repository ships no Dockerfile`),
+    applies: (signals) => (signals.shape.dockerfiles.length > 0 ? undefined : `no Dockerfile`),
 });
 
 /* THE BOOK'S ORDER, which is the panel's reading order and therefore a product decision rather than whatever
  * order these were written in. It narrows from "this is a risk you are carrying right now" to "this is worth
- * thinking about this quarter":
- *   carrying   security, runtime — someone else decides when these become urgent
- *   accruing   dependencies, dead code, complexity — cheap now, expensive later, and always getting later
- *   drifting   documentation, duplication, libraries — the shape of the thing is diverging from the idea of it
- *   surveying  the periodic reads, which have no urgency by construction
+ * thinking about this quarter".
+ *
+ * This used to be a comment above a hand-sorted array — the four kinds named in prose, the order maintained by
+ * whoever added the last chore, and nothing anywhere that could check the two agreed. It was also thrown away at
+ * render: the panel listed every chore in one flat column, so the single editorial claim this surface makes
+ * ("a live advisory and a quarterly re-read are not the same kind of thing") was invisible and therefore
+ * unarguable — on a page whose whole design is that every claim shows its working.
+ *
+ * So the kinds are data. They order the book here, they group the rows in the panel, and `caption` is the
+ * sentence the panel puts beside each group so the grouping argues for itself.
  *
  * Ordering is by KIND, not by whether a given repository will see them: a chore that does not apply is dropped
- * from that repository's list entirely (verdict.ts), so the reading order never has holes in it. */
-export const CHORES: readonly Chore[] = [
+ * from that repository's list entirely (verdict.ts), so the reading order never has holes in it. It is also why
+ * a block of chores written together does not READ together: the front-end four are one paragraph in this file
+ * because they share a gate and a probe, and `kind` is what puts a Vue repository's bundle row next to its
+ * dependency row rather than in a "front-end" section at the bottom. Where a chore is written and where it is
+ * ranked are two separate facts, and only one of them is a product decision. */
+export interface ChoreKindSpec {
+    readonly kind: ChoreKind;
+    // Title case, because the panel renders it as a group heading rather than as a sentence.
+    readonly label: string;
+    // Why these belong together, in the reader's terms — what the group is CLAIMING about the rows under it.
+    readonly caption: string;
+}
+
+export const CHORE_KINDS: readonly ChoreKindSpec[] = [
+    { kind: `carrying`, label: `Carrying`, caption: `a risk this repository is running today — someone else decides when it becomes urgent` },
+    { kind: `accruing`, label: `Accruing`, caption: `cheap now, expensive later, and always getting later` },
+    { kind: `drifting`, label: `Drifting`, caption: `the shape of the thing is diverging from the idea of it` },
+    { kind: `surveying`, label: `Surveying`, caption: `periodic reads with nothing measuring them — due because it has been that long` },
+];
+
+// Declaration order, which decides nothing but the order WITHIN a kind — the sort below is stable, so the two
+// facts stay separable: this list is where a chore is written down, CHORE_KINDS is where it is ranked.
+const BOOK: readonly Chore[] = [
     security,
     runtime,
     dependencies,
     deadCode,
     complexity,
+    bundleWeight,
+    frameworkIdiom,
     documentation,
     duplication,
     libraries,
+    componentOverlap,
+    tailwindBypass,
     patterns,
     deprecated,
     documentationDrift,
@@ -801,6 +1219,12 @@ export const CHORES: readonly Chore[] = [
     images,
 ];
 
+const KIND_ORDER: readonly ChoreKind[] = CHORE_KINDS.map(({ kind }) => kind);
+
+// Sorted rather than filtered into groups, so no chore can ever be dropped out of the book by a kind the list
+// above forgot — a missing kind sorts to the front, where it is visible, instead of vanishing.
+export const CHORES: readonly Chore[] = BOOK.toSorted((left, right) => KIND_ORDER.indexOf(left.kind) - KIND_ORDER.indexOf(right.kind));
+
 export const choreById = (id: string): Chore | undefined => CHORES.find((chore) => chore.id === id);
 
 // The prompt for one chore against one finding. Built here rather than in the view because the panel, the badge's