@lifeaitools/rdc-skills 0.34.0 → 0.35.0

package/skills/pattern-refactoring-guide/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: pattern-refactoring-guide
+description: >-
+  Usage `rdc:pattern-refactoring-guide <path>` — turns a pattern-advisor
+  recommendation (or a solid-validator/architecture-reviewer finding) into a
+  concrete before/after refactor plan. Produces a plan, does not apply it.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# pattern-refactoring-guide — Concrete Refactor Plans
+
+## Input contract
+
+Takes a finding from one of two sources — an upstream surface (a
+`pattern-advisor` recommendation, a `solid-validator` low-score criterion, an
+`architecture-reviewer` boundary violation), OR this skill's own mechanical
+detection layer, `rdc-refactoring-score` (`scripts/refactoring-score.mjs`) —
+and produces a step-ordered plan a build agent can execute. It does not
+invent new findings beyond what a cited detector reported; it does not apply
+the refactor itself.
+
+## Procedure
+
+1. **Find or receive the finding.** Two paths, either is a valid start:
+   - **Upstream finding already exists** — an emitted `pattern-advisor` /
+     `solid-validator` / `architecture-reviewer` result. Skip to step 2.
+   - **No finding yet — detect candidates directly.** Run
+     `node scripts/refactoring-score.mjs <path> --format json` (installed
+     bin: `rdc-refactoring-score`). It is a real, deterministic, AST-based
+     scanner — NOT this skill reasoning about the code — covering nine
+     refactoring types: `extract-method`, `extract-class`,
+     `introduce-parameter-object`, `replace-magic-number`,
+     `consolidate-duplicate-code`, `decompose-conditional`,
+     `strategy-transform`, `factory-transform`, `null-object-transform`.
+     Detection logic: `scripts/lib/refactoring-scoring.mjs`. Every finding
+     carries a real file:line and a mechanical effort signal (see step 5).
+     A "zero findings" result on a real target is only trustworthy once the
+     tool's own positive control passed (it runs one automatically and
+     reports `effortScope.positiveControlOk` in JSON output / the "Effort
+     scan" line in text output — per
+     `.claude/rules/prove-absence-positive-control.md`, treat a failed
+     control as "unmeasured", never as "clean").
+     Two thresholds here are DELIBERATELY DIFFERENT from
+     `clean-code-analyzer`'s mechanical rules even though they read the same
+     underlying fact: `extract-method` fires at >25 statements (this tool)
+     vs. clean-code's F1 at >20 statements; `introduce-parameter-object`
+     fires at >4 params (this tool) vs. clean-code's F2 at >3 params. Both
+     numbers are architecture-toolkit's own real thresholds for their
+     respective domains (`refactoring-analyzer.ts:49,171`) — cite the
+     difference, do not silently merge the two tools' output.
+
+2. **Restate the finding** exactly as reported by the upstream skill or by
+   `rdc-refactoring-score` — file:line, the score/violation, the evidence.
+
+3. **Write the BEFORE** — the actual current code (a real excerpt, not a
+   paraphrase).
+
+4. **Write the AFTER** — the concrete target shape, real code, not a
+   description of code.
+
+5. **Order the steps** so each one leaves the codebase in a working state:
+   - Extract the new shape ALONGSIDE the old one first (new class/module,
+     unused by anything yet).
+   - Migrate ONE call site, verify.
+   - Migrate remaining call sites incrementally, verifying after each.
+   - Delete the old shape only after zero call sites remain — verify with
+     the same call-graph-with-positive-control method `clean-code-analyzer`
+     uses for dead code, don't assume.
+
+6. **Estimate effort — low/medium/high — using named criteria, not a gut
+   call.** Adapted from the `estimatedEffort` field actually shipped in
+   [OnSightTeam/architecture-toolkit](https://github.com/OnSightTeam/architecture-toolkit)'s
+   `src/agents/pattern-refactoring-guide/tools/*.ts`, extended with the
+   criterion its own examples expose a gap in (see below). When the finding
+   came from `rdc-refactoring-score` (step 1), don't re-derive this table by
+   hand — the tool already computed the mechanical half of it: it re-walks
+   the SAME cross-file reference-graph mechanism `clean-code-scoring.mjs`'s
+   G9 dead-export check uses (`plugin.referenceSitesOf`, built on
+   `findReferencesAsNodes`, gated behind its own positive control) and
+   reports each unit's real call-site count and whether any reference
+   crosses a `packages/*`/`apps/*` boundary. The one criterion below it
+   CANNOT compute — a cross-cutting invariant that isn't locally checkable —
+   is always a human judgment call; the tool flags `invariantCheckRequired:
+   true` as a reminder wherever boundary-crossing or >15 call sites already
+   pushed it to High, but never claims to have evaluated the invariant
+   itself.
+
+   | Effort | Criteria (any ONE qualifies) | toolkit precedent |
+   |---|---|---|
+   | **Low** | Single file, ≤3 call sites, no package-boundary crossing, mechanical (rename, extract-constant, extract-condition-to-named-method). | `introduce_parameter_object` (`refactoring-analyzer.ts:179`), `replace_magic_number` (`:234`), `decompose_conditional` (`code-smell-refactoring-guide.ts:121`) — all single-function, in-place edits. |
+   | **Medium** | 4-15 call sites within the SAME package, OR a new abstraction introduced but consumed only inside the current package/module. | `extract_method` (`refactoring-analyzer.ts:57`) — "may need to pass many parameters" but stays in one file. `consolidate_duplicate_code` (`code-smell-refactoring-guide.ts:59`), Strategy/Factory/Null-Object pattern transforms (`pattern-transformation-guide.ts:52,110,168`) — new types, but all call sites are local. |
+   | **High** | **Crosses a package boundary** (the extraction moves logic into or out of a different `packages/*`/`@regen/*` workspace), OR >15 call sites, OR — the criterion the toolkit's own field values don't cover — **the target carries a cross-cutting invariant that isn't locally checkable** (event ordering, transactional/append-only integrity, freeze-after-mutation semantics): call-site count alone UNDER-counts effort here, because migrating the invariant correctly matters more than how many call sites exist. | `extract_class` (`refactoring-analyzer.ts:116`) is the toolkit's own high-effort case — ">15 methods... requires careful dependency management" is the package-boundary risk stated in words even though the field only tracks method count. |
+
+   **Call-site count is not sufficient on its own** — see the worked example
+   below, where the real count (8) sits in the Medium range by call-site
+   count alone, yet the target is still HIGH effort because of the
+   package-boundary and invariant clauses.
+
+7. **Name the test that must go from red to green** (or the golden-capture
+   delta that must appear) at each step — route through `testing-strategy`
+   for the right level/shape if the finding doesn't already specify one.
+
+8. **Every step names what proves it succeeded — no exceptions, including
+   intermediate steps.** This is stricter than the toolkit's own shipped
+   examples: `refactoring-analyzer.ts`'s own `extract_method` plan has a
+   `validation` field on steps 1, 3, 4 (`:69`, `:79`, `:84`) but step 2 — "extract
+   each section into a separate method" (`:72-75`) — carries only a `code`
+   field and NO validation, i.e. the toolkit's own reference plan has a step
+   whose success is unstated. That gap is exactly what this rule closes: a
+   step that only shows the code to write, with no stated proof it worked,
+   is incomplete here even if the toolkit's own precedent shipped that way.
+   Every step gets one of: a specific test name, a `tsc`/lint exit code, a
+   call-site grep returning zero, or an explicit "no assertion possible,
+   inspect manually" — never a bare code sample standing in for proof.
+
+9. **Report:**
+   ```
+   ## Refactor Plan — <finding source>: <file:line>
+   ### Before
+   ### After
+   ### Effort: low/medium/high — <which criterion triggered it>
+   ### Steps (each leaves the tree working; each names its own proof)
+   ### Verification per step
+   ```
+
+## Rules
+
+- Never skip straight from BEFORE to AFTER in one step for anything touching
+  more than one call site — the incremental-migration order is the point;
+  a plan that says "rewrite it" is not a plan.
+- A plan with no verification step per stage is incomplete — and "per
+  stage" means literally every step, not just the final one; a step with a
+  code sample and no proof is a rewrite instruction wearing a plan's
+  clothing.
+- Never report effort from call-site count alone — always check the
+  package-boundary and cross-cutting-invariant criteria too; a low
+  call-site count on an invariant-bearing target is still HIGH.
+- This skill does not execute the plan — hand off to `rdc:build`/`rdc:fixit`.
+
+## Worked Example — extracting `rdc-harness`'s `Harness` god-object
+
+Chained input: the `architecture-reviewer` worked example (see that skill's
+own SKILL.md) found `Harness` in
+[`C:/Dev/rdc-harness/packages/core/src/index.mjs`](file:///C:/Dev/rdc-harness/packages/core/src/index.mjs)
+reimplementing transaction/delivery/deploy/orchestration logic inline instead
+of delegating to the sibling packages that already exist for each. `rdc-
+refactoring-score` independently detects the SAME target via step 1's own
+mechanical path — a real run (`node scripts/refactoring-score.mjs
+C:/Dev/rdc-harness/packages/core/src/index.mjs`) reports:
+
+```
+[extract-class] [high] Harness — 24 methods (over 15) — violates Single
+Responsibility, candidate for Extract Class
+```
+
+24 methods, not the loose "+ 9 more methods" this example previously said —
+the real count once `memberEntries()` visits constructors, getters/setters,
+and arrow-property methods too, not just `cls.getMethods()`. This is that
+finding turned into a plan.
+
+```
+## Refactor Plan — architecture-reviewer: packages/core/src/index.mjs:49-394 (Harness)
+
+### Before
+class Harness {
+  deploy({ handleId }) {
+    const { handle, target, snapshot } = this.#bind(handleId, 'deploy');
+    const approved = Object.values(snapshot.decisions).some(...);
+    if (!approved) throw new RefusedError(...);
+    const to = join(this.#root, 'artifacts', 'production', ...);
+    this.#adapters.writeArtifact({ from: src.path, to });   // inline delivery
+    this.#emit({ type: 'deployed', ... });
+  }
+  // + 23 more methods, same shape: inline logic that belongs to a sibling package
+}
+
+### After
+class Harness {
+  constructor({ root, clock, adapters, deployPort } = {}) {
+    ...
+    this.#deployPort = deployPort ?? new DefaultDeployPort({ root, adapters });
+  }
+  deploy({ handleId }) {
+    const { handle, target, snapshot } = this.#bind(handleId, 'deploy');
+    const receipt = this.#deployPort.deploy({ handle, target, snapshot });
+    this.#emit({ type: 'deployed', ...receipt });
+  }
+}
+// packages/deploy/src/default-deploy-port.mjs — owns the artifact-path/approval logic
+
+### Effort: HIGH — package-boundary crossing and the invariant clause, NOT
+call-site count. `rdc-refactoring-score`'s real reference-graph scan
+(`plugin.referenceSitesOf('packages/core/src/index.mjs', 'Harness', ...)`,
+positive control passed) reports **8 cross-file references**, all within
+`packages/core` itself: `index.mjs:75`'s own internal factory call
+(`new Harness(...)`), plus 7 in `packages/core/test/site-html-lifecycle.test.mjs`
+— the `import { Harness, ... }` statement (line 20), 4 `new Harness(...)`
+construction sites (lines 40/55/70/94), and 2 static-method calls,
+`Harness.resume(...)` (line 142) and `Harness.replay(...)` (line 296). This
+is a REAL demonstration of why the real reference-graph walk
+(`findReferencesAsNodes`) is used here instead of a text grep: a naive
+`grep -rn "new Harness(" --include="*.mjs"` finds only 5 of these 8 —
+the import statement and both static-method calls are invisible to that
+grep, and a `new Harness(...)` regex would silently undercount call sites on
+any class whose API includes static factory/replay methods. By call-site
+count alone (8, same package) criterion 2 says **Medium** — this example
+previously speculated a call-site count of zero and a resulting "criterion 2
+would say LOW", which the tool's real output does not bear out; correcting
+that here matters because it is exactly the trap this rule exists to prevent
+(see "Call-site count is not sufficient on its own" above). What actually drives
+this to HIGH is criterion 3: the refactor's real target is package-boundary
+crossing (the extraction moves deploy/delivery/transaction/orchestration
+logic OUT of `packages/core` and INTO `packages/deploy`, `packages/delivery`,
+etc. — those packages are not yet Harness's callers, but they become its
+collaborators after the extract), plus the invariant clause — every method
+must keep emitting to the same append-only event log with the same monotonic
+`#seq`, and the file's own comments (`index.mjs:103-110`) document a prior
+real bug where a spread copy silently defeated a freeze invariant. That
+invariant is exactly the case a mechanical call-site count cannot see, which
+is why `rdc-refactoring-score` reports `invariantCheckRequired: true`
+whenever boundary-crossing or a >15-call-site result already pushes it to
+High, but leaves the actual invariant judgment to this step.
+
+### Steps (each leaves the tree working; each names its own proof)
+1. Define `DeployPort`/`DeliveryPort`/`TransactionPort`/`OrchestrationPort`
+   interfaces (method signatures only, in `packages/deploy`, `packages/delivery`,
+   `packages/transaction`, `packages/orchestration` respectively) — unused by
+   `Harness` yet.
+   Validation: `npx tsc --noEmit` (or the repo's JS-equivalent lint) passes
+   with the new files added; zero import changes in `index.mjs` yet, so the
+   existing test suite is still 100% green with zero deltas.
+2. Implement `DefaultDeployPort` in `packages/deploy`, moving `deploy()`'s
+   artifact-path + approval-check logic verbatim out of `Harness` into it.
+   Validation: a new unit test in `packages/deploy/test/` exercises
+   `DefaultDeployPort.deploy()` directly with a fixture snapshot/handle and
+   asserts the same receipt shape `Harness.deploy()` used to return.
+3. Wire `Harness`'s constructor to accept an injected `deployPort` (default:
+   `new DefaultDeployPort(...)`), and change `deploy()` to call
+   `this.#deployPort.deploy(...)` instead of inline logic.
+   Validation: `packages/core/test/site-html-lifecycle.test.mjs` (the
+   existing suite) passes unmodified — same assertions, same call signature,
+   only the internal implementation moved.
+4. Repeat steps 2-3 for `shipDev`→`DeliveryPort`, `requestProduction`/
+   `recordDecision`→`TransactionPort`, `createRun`/`createRepository`/
+   `createTarget`→`OrchestrationPort`, one method-group at a time.
+   Validation per group: same pattern as step 3 — the existing lifecycle
+   test suite passes unmodified after each group's swap, never after all
+   four at once.
+5. Once all four ports are wired, grep `index.mjs` for `node:fs` and
+   `node:crypto` imports used OUTSIDE the four new ports.
+   Validation: the grep returns zero matches outside `#emit`/`#load` (the
+   event-log read/write, which is intentionally NOT extracted — it's the
+   spine, not a layering violation per this skill's own header) — this is
+   the positive-control check that no inline I/O was missed.
+## Verdict: HIGH effort, 5 steps, each with a named proof; 8 call sites, all
+WITHIN `packages/core` (zero from any OTHER package today) means the
+migration is low-RISK to sequence but not low-EFFORT — the two are different
+axes and this plan's Effort line says so explicitly.
+```

package/skills/review/SKILL.md

@@ -106,6 +106,35 @@ description: "Usage `rdc:review [--unattended]` — Post-build quality gate: tsc
 
    Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and continue.
 
+8c. **Form/fit/function gate — solid-validator + architecture-reviewer:**
+
+   ⛔ **No CLEAN verdict without this pass either.** Step 8b catches logic,
+   security, and convention drift. This step catches a different failure
+   shape entirely: code that is logically correct and convention-clean but
+   architecturally wrong — the `Harness` case (a use-case orchestrator that
+   reimplements what sibling packages exist to do, scoring fine on every
+   generic metric while failing the one check that names the actual rule).
+
+   ```bash
+   rdc-solid-score <modified-package-path> --diff origin/main --config <repo>/.solid-score.yml --format json
+   ```
+   Read `regressions` (SOLID score dropped vs `origin/main`) and
+   `boundaryViolations` (the `satisfied: false` subset of `boundaryFindings`
+   — named Clean Architecture rule failures) from the
+   output. Either non-empty is a FORM/FIT failure — dispatch
+   `architecture-reviewer` (skill: "architecture-reviewer") for the judgment
+   half if a boundary finding needs a suggested fix, not just a named
+   violation.
+
+   **Severity gate:**
+   - Any regression, or any boundary violation → verdict cannot be CLEAN.
+   - No `.solid-score.yml` present in the target repo → note it and skip,
+     do not fabricate a config; a repo with no boundary rules configured has
+     nothing wrong to report, but say so explicitly rather than silently
+     passing.
+
+   Under `RDC_TEST=1`: echo `[RDC_TEST] skipping form/fit/function gate` and continue.
+
 9. **Verification gate — dispatch the verify agent:**
    After any fixes land, run the verify gate on every touched package. See `guides/agents/verify.md`.
    Apply `guides/engineering-behavior.md` while reviewing: flag unnecessary abstraction, drive-by refactors, missing assumptions, hidden uncertainty, out-of-scope edits, and prose-only verification.

package/skills/solid-validator/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: solid-validator
+description: >-
+  Usage `rdc:solid-validator <path> [--diff <ref>] [--config <file>]` — the
+  FORM corner of the form/fit/function model. Deterministic AST scoring of
+  all five SOLID letters (weighted sum, confidence-annotated) plus a separate
+  Clean Architecture boundary check. Real numbers, not LLM judgment — see
+  `scripts/solid-score.mjs` for the mechanism.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# solid-validator — Deterministic SOLID + Clean Architecture Scoring
+
+## Why this one is mechanical, not a dispatched agent
+
+Three other skills in this suite (`architecture-reviewer`,
+`clean-code-analyzer`, `package-design`) dispatch `pr-review-toolkit:code-reviewer`
+for judgment; `pattern-advisor` and `pattern-refactoring-guide` produce
+recommendations/plans without a dispatch, and `testing-strategy` recommends
+a level/shape rather than scoring anything. This one does not dispatch a
+judgment agent at all, on purpose: a ratchet gate that blocks a merge
+on regression needs a NUMBER two runs can be diffed against, and an LLM
+judgment call is not deterministic enough for that job. `git` is the baseline
+— `--diff <ref>` scores each unit twice (at `<ref>` and in the working tree)
+and gates on the delta, so nothing here persists a baseline file that can
+drift out of sync with reality.
+
+Dogfooded: `rdc-harness`'s `Harness` god-object scores 68.5/100 on the
+weighted SOLID sum (SRP=40, three disconnected components across 21 members
+— real cohesion signal) while the boundary check independently fails it on
+all 6 of its declared ports. Two checks, proven necessary together — DIP's
+generic concrete-instantiation-ratio metric alone did NOT catch the
+violation (a class with almost no dependencies of any kind scores fine on
+it), which is why the boundary rule exists as a separate, named check rather
+than folded into DIP's score.
+
+## Arguments
+
+- `rdc:solid-validator <path>` — full score, current working tree
+- `rdc:solid-validator <path> --diff <ref>` — regression gate against `<ref>`
+- `rdc:solid-validator <path> --config <file>` — weights/thresholds/boundaries
+
+## Procedure
+
+1. **Run the scorer:**
+   ```bash
+   rdc-solid-score <path> --diff <ref> --config <repo>/.solid-score.yml --format json
+   ```
+   (installed globally via `npm link`/publish from this package — see
+   `package.json`'s `bin.rdc-solid-score`; falls back to
+   `node <rdc-skills-install-path>/scripts/solid-score.mjs` if the bin isn't
+   on PATH.)
+
+2. **Read `results`** — per-unit SRP/OCP/LSP/ISP/DIP scores with confidence
+   (`high`/`low-medium`/`low` — OCP and LSP are heuristic by nature; report
+   the confidence, never hide it).
+
+3. **Read `regressions`** (only present with `--diff`) — any unit whose
+   score dropped more than `diff.maxDecrease` (default 0, i.e. no regression
+   tolerated) versus the base ref, or any NEW unit below `diff.newUnitMin`.
+
+4. **Read `boundaryFindings`** — named Clean Architecture dependency-rule
+   violations from the repo's configured `boundaries` list. Treat these as
+   equally load-bearing as a regression — they catch a different failure
+   shape (see the `Harness` case above).
+
+5. **Read `unresolvedLanguages`** — files no registered plugin could parse.
+   Report them explicitly; do not silently treat them as passing. (Day-1
+   plugin: TypeScript/JavaScript via `ts-morph`. A Python plugin implementing
+   the same `lib/language-plugin.mjs` contract extends coverage without
+   touching this skill or the scoring core.)
+
+6. **Report:**
+   ```
+   ## SOLID + Clean Architecture Score
+   | Unit | SRP | OCP | LSP | ISP | DIP | Total |
+   ### Regressions (vs <ref>)
+   ### Boundary violations
+   ### Unresolved languages (no plugin — not silently passed)
+   ## Verdict: CLEAN / HAS ISSUES
+   ```
+
+## Rules
+
+- Never treat an `unresolvedLanguages` entry as a pass — it is unmeasured,
+  not clean.
+- A boundary violation is a hard block regardless of the weighted score —
+  do not let a high SOLID total offset a missing required port import.
+- Confidence is reported data, never a reason to omit OCP/LSP scores.

package/skills/testing-strategy/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: testing-strategy
+description: >-
+  Usage `rdc:testing-strategy <path>` — recommends the right TEST LEVEL and
+  SHAPE for a surface (unit/integration/live tier, assertion vs golden-capture),
+  not a specific test to write. The FUNCTION corner of the form/fit/function
+  model — solid-validator covers FORM, architecture-reviewer covers FIT, this
+  covers whether a surface's behavior is actually provable, and how.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# testing-strategy — Test Level & Shape Recommendation
+
+## The distinction this exists to enforce
+
+A test can be green and prove nothing — this session's own history: a
+proof-ledger claimed 144/144 while grading each row against evidence weaker
+than the row demanded, because the tests were written to make a NAMED CLAIM
+go green rather than to capture real behavior. This skill's job is to say,
+BEFORE a test is written, what level and shape it needs to be honest —
+catching that failure at design time instead of at a review months later.
+
+## Level — pick the lowest that can still prove the claim
+
+| Level | Proves | Fixture allowed? |
+|---|---|---|
+| **Unit** | pure function, one input/output contract | yes — the function IS the boundary |
+| **Integration** | real adapters composed across a package boundary | disposable repo/worktree/registry fixture, never a stub standing in for the boundary itself |
+| **Live** | a real external outcome (real git, real process, real HTTP) through the authoritative source | no — a fixture at this level is a downgrade, not a shortcut |
+
+A claim that says "delivers," "deploys," "persists," or "ships" needs live
+tier. A claim about a pure calculation needs unit tier and nothing more —
+forcing live tier on a pure function is not rigor, it's noise that hides the
+real live-tier gaps under a pile of slow, brittle tests.
+
+## Shape — assertion vs golden-capture
+
+Ask: **can the author state, in one sentence, exactly what "correct" means
+before running the code?**
+
+- Yes → assertion-based test. Write the expectation, then the test.
+- No (the correct shape is "whatever the real system currently does, until a
+  human reviews a change") → golden-capture. Run the seam, record the FULL
+  observable result (return value, thrown error, side-effect journal), diff
+  future runs against it. A delta is a question for a human, never an
+  auto-pass or auto-fail.
+
+Golden-capture is not a lesser form of testing — it exists specifically
+because assertion-writing failed on complex orchestration surfaces this same
+session: the author cannot accidentally assert something weaker than the
+truth when they are not choosing what to assert.
+
+## Procedure
+
+1. **Identify the surface's SEAM** — its real, production-called entry point.
+   If nothing in production calls it, that is not a testing question, it's an
+   `architecture-reviewer` finding (dead code / no production caller) —
+   route it there first. A test cannot prove a surface has no reason to exist.
+
+2. **Classify the claim** the surface makes (calculation / composition /
+   external effect) and pick the LOWEST level from the table above that can
+   prove it. State the level explicitly in the checklist row — not "tested",
+   but "unit: pure function" / "integration: composed across guard+delivery
+   against a disposable worktree" / "live: real git commit against a
+   disposable repo".
+
+3. **Pick assertion vs golden-capture** using the one-sentence test above.
+
+4. **For a claim naming an outcome word** (delivers/deploys/persists/ships/
+   writes) — require a positive control: the SAME test run against a target
+   KNOWN to succeed, before trusting a negative result from it. A test that
+   never proves it CAN detect failure proves nothing when it passes.
+
+5. **Report:**
+   ```
+   ## Testing Strategy
+   | Surface | Claim | Level | Shape | Positive control needed? |
+   ```
+
+## Rules
+
+- Never recommend live tier for a pure function, or unit tier for an
+  external-effect claim — matching level to claim is the whole point.
+- A recommendation with no seam identified is incomplete — say so, don't
+  guess a seam that doesn't exist in production.
+- This skill recommends; it does not write the test. Pair with the actual
+  build task.
+
+## Mechanical test-smell scoring — a separate, lower layer
+
+Everything above answers "what SHAPE should this test be" before it's
+written. `scripts/lib/test-smell-scoring.mjs` answers a different question
+once a test exists: does its own construction show a known smell? Same
+distinction as `solid-validator`/`architecture-reviewer` — this is FORM
+applied to test code, not FIT or FUNCTION, and it runs mechanically over
+existing `.test.mjs`/`.test.ts`/`*.spec.*` files, not as a pre-write
+recommendation.
+
+Language-independent in shape (pure functions over text/AST facts, same
+discipline as `language-plugin.mjs` — no ts-morph import in the scoring file
+itself). Rule IDs and several thresholds are reused from
+[OnSightTeam/architecture-toolkit](https://github.com/OnSightTeam/architecture-toolkit)
+(MIT) — see the file header for exact file:line citations and what was
+adapted vs. reused verbatim.
+
+| Rule | Detects | Threshold |
+|---|---|---|
+| T1 Insufficient Tests | fewer test() blocks than exported functions/methods in the paired source file | `testCount < exportedUnitCount` (source count via the `NormalizedUnit` plugin contract, not a regex) |
+| T2 Ignored Tests | `test.skip`/`it.skip`/`xit`/`xdescribe` | any occurrence |
+| T5 Exhaustive Testing | too many assertions in one test() block | >10 per block |
+| T6 Long Tests | oversized test() block body | >30 lines |
+| T7 Slow Tests | literal `setTimeout`/`setInterval`/`sleep`/`delay` calls INSIDE a test's own body | any occurrence in-block |
+| T8 Fragile Tests | `Date.now()`, bare `new Date()`, `Math.random()`, `process.env.*` referenced directly inside a test body | any occurrence in-block |
+| T9 Duplicated Setup | near-identical `beforeEach`/`beforeAll` bodies ACROSS test files | ≥0.75 Jaccard similarity over normalized 3-token shingles (literals collapsed, identifiers not — see file header) |
+| FIRST-Independent | a `let` declared outside test() and mutated inside 2+ separate test() blocks | requires both the declaration site AND ≥2 distinct mutation sites, not presence alone |
+
+T3 (Test Per Class) and T4 (Untested Method) are deliberately not
+implemented — see the file header's "Skipped" section for why faking them
+would have been a weak check invented to fill a slot. Fast/Repeatable/
+SelfValidating/Timely are likewise skipped as either duplicating T7/T8 or
+not being smell checks at all.
+
+Dogfooded against `rdc-harness`'s 47 real `*.test.mjs` files (2026-08-20):
+71 findings (T5/T6/T8), plus T1 flagged `packages/core` (28 exported
+members, 16 tests — the same `Harness` god-object `solid-score.mjs` already
+flags on SOLID grounds) and three other packages. T2/T7(in-block)/T9/
+Independent had zero real hits in that corpus — confirmed as true negatives
+via grep positive-control before trusting the absence, and each rule was
+separately proven to fire against a synthetic fixture exercising it.