@deslop/coding-standards 0.1.1065 → 0.1.1067

package/README.md

@@ -1,6 +1,6 @@
 # Coding standards
 
-A strict Oxlint preset and an installer for the engineering, design and testing agent skills. Requires Node 26+.
+A strict Oxlint preset and an installer for the architecture, engineering, design, testing and review skills. Requires Node 26+.
 
 ## Install the skills
 
@@ -10,7 +10,9 @@ Run inside a Git repository, including a linked worktree:
 vpx @deslop/coding-standards@latest
 ```
 
-It copies the three skills into the repository's existing `.agents`, `.claude` and `.codex` directories, including their `EVALS.md`. It always writes `.claude`, which Claude Code reads, and writes `.agents` when no `.codex` exists. A refresh replaces only those three skills, and destinations outside the repository or inside global agent configuration are rejected. Nothing is added to the manifest, lockfile or lint configuration. Edit package sources; refresh installed copies with the CLI.
+It copies all package-owned skills into the repository's existing `.agents`, `.claude` and `.codex` directories, including their `EVALS.md`. It always writes `.claude`, which Claude Code reads, and writes `.agents` when no `.codex` exists. A refresh replaces only those names; destinations outside the repository or inside global agent configuration are rejected. Other skills, sign-ins, manifests, lockfiles and lint configuration stay unchanged. Edit package sources, then refresh installed copies with the CLI.
+
+Use architecture for mechanisms and ownership, engineering for code, design for visible behavior, testing for useful proof and review for independent critique and cleanup. Refer to another skill by name, not its installation path. Personal orchestration, delivery, machine commands and reply preferences stay outside this package.
 
 ## Use the lint preset
 
@@ -37,7 +39,7 @@ The preset needs Effect-tsgo's patched Oxlint, so keep the patch command in the
 | Owner      | Decision                                                                                                                                                                                                                                                                                                                                                                      |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `src/`     | Flat package structure; rules in `src/rules`, no separate plugin or install-test harness                                                                                                                                                                                                                                                                                      |
-| `skills/`  | Maintained engineering, design and testing sources; refresh repository copies from the TypeScript CLI, no build needed                                                                                                                                                                                                                                                        |
+| `skills/`  | Maintained architecture, engineering, design, testing and review sources; refresh repository copies from the TypeScript CLI, no build needed                                                                                                                                                                                                                                  |
 | Lint rules | Prefer an equivalent maintained rule before custom enforcement; consumer code conforms to strict standards, not the reverse. Fix broken or imprecise rules, not inconvenient valid diagnostics. A rule targets code the engineering skill and the other rules allow; an edge case that only unusual code reaches takes an inline disable with its reason, never a looser rule |
 | Rule proof | Existing public CLI regression cases, with accepted and rejected controls; no severity or exclusion workaround                                                                                                                                                                                                                                                                |
 
@@ -70,6 +72,16 @@ node tools/coding-standards/src/install.ts
 | [Interface Craft](https://www.interfacecraft.dev/library), the user's licensed library                                                                                                                                                                                                                                                                                                               | Before-the-first-draft steps, range and depth, agent-run tuning, the four-pass critique, optical, color, type and motion values; ideas adapted in our words, no files copied                      |
 | [Apple HIG](https://developer.apple.com/design/human-interface-guidelines), [Linear](https://linear.app/now/how-we-redesigned-the-linear-ui), [Rauno Freiberg](https://rauno.me/craft/interaction-design), [Geist](https://vercel.com/geist), [Radix](https://www.radix-ui.com/primitives/docs/overview/accessibility) and [WCAG](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) | The quality bar, platform conventions, semantic type and glass, gesture behavior, border and shadow roles, dialog contracts and contrast ratios                                                   |
 
-These are selectively adapted ideas, not imported frameworks. Concrete behavior, existing stack and settled user decisions govern the maintained skills.
+Additional sources for this refinement:
+
+- [OpenClaw test audit](https://github.com/openclaw/openclaw/blob/main/.agents/skills/test-audit/SKILL.md): distinct regression protection and deletion of tautological tests; retain independent boundary contracts.
+- [Trail of Bits](https://github.com/trailofbits/skills): reproduce the strongest reachable counterexample and inspect variants of a known root cause; no routine security-audit machinery.
+- [Bret Victor](https://worrydream.com/ExplorableExplanations/) and [Nicky Case](https://blog.ncase.me/how-i-make-an-explorable-explanation/): concrete cause and consequence, with optional exploration rather than mandatory navigation.
+- [Taste skill](https://github.com/Leonxlnx/taste-skill/tree/a60a36dc2bb3bb77ccf17f2f62041f5ca8a458b9): real subject inventory and screenshot critique; no mandatory image, motion or component quotas.
+- [Anatomy](https://github.com/wheresryan22/anatomy): physical and isometric explanations when their relationships are the concept; no mandatory dense machine or separate card frame.
+- [Antfu design](https://github.com/antfu/design): native token hierarchy, density and affordance; no Vue or UnoCSS dependency added.
+- [Animated sprites](https://github.com/elithrar/dotfiles/tree/main/.agents/skills/animated-sprites): separate structural validity from perceptual motion and actual timing; no character assets required.
+
+These are selectively adapted ideas, not imported frameworks. Concrete behavior, existing stack and settled user decisions govern the maintained skills. Source inspection and drafted evaluation criteria do not establish a model-quality improvement.
 
 </details>

package/dist/install.js

@@ -25233,13 +25233,14 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.1.1065";
+var version = "0.1.1067";
 //#endregion
 //#region src/install.ts
 const cli = pipe(make("deslop-coding-standards", {}, fnUntraced(function* () {
 	const fs = yield* FileSystem;
 	const path = yield* Path$1;
 	const source = path.join(import.meta.dirname, "../skills");
+	const names = yield* fs.readDirectory(source);
 	const handle = yield* make$4("git", ["rev-parse", "--show-toplevel"], { stdout: "pipe" });
 	const result = yield* all({
 		exitCode: handle.exitCode,
@@ -25287,22 +25288,14 @@ const cli = pipe(make("deslop-coding-standards", {}, fnUntraced(function* () {
 			if (contains(yield* fs.readDirectory(target), "skills")) yield* validate(path.join(target, "skills"));
 		}
 		const skills = yield* canonical(path.join(target, "skills"));
-		for (const name of [
-			"engineering",
-			"design",
-			"testing"
-		]) {
+		for (const name of names) {
 			const owned = path.join(skills, name);
 			if (isGlobal(owned) || some$1(globals, (global) => pipe(global, startsWith(`${owned}${path.sep}`)))) return yield* UserError.make({ cause: `${owned} overlaps global agent configuration.` });
 		}
 	}
 	for (const directory of targets) {
 		yield* fs.makeDirectory(path.join(root, directory, "skills"), { recursive: true });
-		for (const name of [
-			"engineering",
-			"design",
-			"testing"
-		]) {
+		for (const name of names) {
 			const target = path.join(root, directory, "skills", name);
 			yield* fs.remove(target, {
 				force: true,
@@ -25311,10 +25304,10 @@ const cli = pipe(make("deslop-coding-standards", {}, fnUntraced(function* () {
 			yield* fs.copy(path.join(source, name), target);
 		}
 	}
-	yield* log(`Installed engineering, design and testing in ${pipe(targets, map$9((directory) => path.join(root, directory, "skills")), join$1(", "))}.`);
-})), withDescription("Run anywhere inside a Git repository to install engineering, design and testing at its root, including linked worktrees. Copies into skills/ under each existing .agents, .claude and .codex directory, always under .claude, and under .agents when no .codex exists. Replaces these three names, preserving other skills and global configuration. Destinations resolving outside the Git root are rejected before copying. Read engineering before coding, design before rendered output and testing before test work. Run the latest CLI transiently, independently of package preset versions; no repository dependency is needed. Claude uses .claude/skills; Codex documents .agents/skills for repository discovery. These skills belong in repositories, not global configuration."), withExamples([{
+	yield* log(`Installed ${join$1(names, ", ")} in ${pipe(targets, map$9((directory) => path.join(root, directory, "skills")), join$1(", "))}.`);
+})), withDescription("Install the package’s architecture, engineering, design, testing and review skills at the Git repository root, including linked worktrees. Copy into each existing .agents, .claude and .codex skills directory, always .claude, and .agents when no .codex exists. Replace only package-owned names; preserve other skills and global configuration. Reject destinations outside the repository before copying. Refer to skills by name. Run the latest CLI transiently without adding a dependency. These skills belong in repositories, not global configuration."), withExamples([{
 	command: "vpx @deslop/coding-standards@latest",
-	description: "Install or refresh this repository’s three skills without adding a dependency."
+	description: "Install or refresh this repository’s shared skills without adding a dependency."
 }]));
 runMain(pipe(cli, run({ version }), scoped, provide(layer)));
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deslop/coding-standards",
-  "version": "0.1.1065",
+  "version": "0.1.1067",
   "repository": {
     "type": "git",
     "url": "https://github.com/MP281X/deslop",

package/skills/architecture/EVALS.md

@@ -0,0 +1,21 @@
+# Architecture evaluations
+
+## architecture
+
+### Task
+
+Let me import a folder of data files, see progress and stop without losing completed records. Choose the architecture before writing product code. Explain only the decisions I need to make.
+
+### Criteria
+
+Judge the mechanism and caller obligations, not the number of modules or diagrams.
+
+- Trace existing CLI, HTTP and browser consumers and preserve single-file behavior.
+- Keep persistence and cancellation in the existing service and its operation scope.
+- Reject an unnecessary job registry, detached writer, mirrored progress store and generic importer factory.
+- Give completion one observable meaning: the emitted record is durable.
+- Handle reachable read, decode and write failures without blanket retries or empty-success defaults.
+- Use a disposable experiment for an uncertain technical contract; ask only about an unresolved user outcome.
+- Name a concrete contract before adding a boundary, dependency or background lifetime.
+
+Grade simplicity and preserved behavior separately. A written design does not prove its implementation. Keep integrated planning and steering evaluations separate from this selected-skill case.

package/skills/architecture/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: architecture
+description: 'Choose the smallest production mechanism, module boundaries, state owners and failure contracts. Use for new features, consequential refactors and reviews of architectural complexity; engineering owns syntax and implementation conventions.'
+---
+
+# Architecture
+
+Start from a real caller and the required outcome, not a pattern or framework. Apply engineering to the implementation. A new abstraction must remove a concrete obligation from its callers.
+
+## Trace the operation
+
+Read the nearest working feature and every affected consumer. Trace one successful operation and its strongest reachable failure through the existing modules. Identify the authoritative state, write boundary, resource lifetime and observable completion signal. Preserve the existing contracts that the change reaches.
+
+Before code, settle these facts in the current plan, without creating another document:
+
+- The caller's input, output and ordering obligations.
+- One owner for each value, resource, side effect and failure.
+- The existing module that can own the operation.
+- The boundary where untrusted input becomes trusted data.
+- What remains durable after interruption, and how the caller knows.
+
+For a user-visible direction that remains open, decide it with the user before implementation; use orchestrator when available. Settle technical mechanisms with source, a disposable inline probe or a small executable prototype. Do not ask the user to choose between implementation details that evidence can rank.
+
+## Choose the smallest mechanism
+
+- **Existing shape.** Extend the closest working feature before creating a service, module or dependency. Keep domain code independent of transport and UI types.
+- **Direct operation.** Prefer a function or existing service method. Add a service for a distinct capability or lifetime, not to rename a forwarded call. Add another backend only when a real consumer needs it.
+- **Authoritative state.** Derive values from their owner. Do not mirror server state, request state, caches or pending results in another store. A persisted value has one write boundary.
+- **Lifetime.** Keep finite request work in its request scope. A stream serves progressive results; it does not require a job system. Add background ownership only when work must survive the caller, with a real owner for stopping, recovery and completion.
+- **Failure.** Handle failures the caller can reach. Validate at the boundary; retain domain identity, causes and completed work. Never turn failure into empty success or add blanket retries, fallbacks and catch-all defaults.
+- **Retries.** For a contract that permits retry after an unknown write outcome, keep the request identity stable for one intent. Add no retry policy or idempotency machinery to operations that do not need that contract.
+- **Boundaries.** Split code when dependencies, invariants or lifetimes differ. Prefer a substantive module to a chain of forwarding files. A small component or helper with one consumer stays beside that consumer.
+- **Variations.** Use explicit variants for genuinely different behaviors. Do not add boolean combinations, a plugin registry, a generic configuration object or a universal factory for hypothetical callers.
+
+Compare a new mechanism with the direct existing-module version. Count new state owners, boundaries, dependencies and failure paths, not just lines. Keep the simpler version unless a concrete contract rules it out. Prove that contract with a question-sized experiment; use a council only for a consequential unresolved tradeoff.
+
+## Challenge the design
+
+Try the strongest reachable counterexample: an interrupted write, repeated intent, stale response, overlapping caller or dependency failure. Check which owner preserves the invariant. Use testing to select evidence, not to turn every doubt into a permanent test.
+
+Remove each mechanism whose deletion preserves the required outcomes, existing reachable contracts, security, accessibility and useful regression protection. Do not defend an abstraction because it is already implemented. State what breaks without it; if nothing breaks, remove it.

package/skills/design/EVALS.md

@@ -14,6 +14,33 @@ Judge the browser experience, not the amount of UI produced.
 - Make idle, active, cancelled, completed and empty states understandable.
 - Keep completed records visible when the import stops; distinguish stop from undo.
 - Establish readable light and dark views at 390-point width, touch targets and keyboard access.
-- Show an interactive design before backend changes; remove redundant controls and status text.
+- Settle the representative journey with the user before backend changes; expand only its approved direction.
+- Remove redundant controls and status text; use interaction to explore a real consequence, not to navigate an explanation.
 
 Inspect every visible state and transition. Grade hierarchy, behavior and readability independently of engineering and proof-capture quality. The user judges the final variants.
+
+## overview-format
+
+### Task
+
+Give me a quick overview of these changes: Review moved into coding-standards; Architecture was added; open choices need a prototype and approval; routine fixes do not; proof uses inline probes before permanent tests. These instruction changes are local, not installed. There are no UI captures, measurements or interactive choices to show.
+
+### Criteria
+
+- Use a short Markdown table or list. Do not produce HTML, an image of the same rows, controls or a separate presentation app.
+- Keep every supplied distinction, including routine fixes and installation state, with the fewest words that remain clear.
+- Do not add an introduction or duplicate the overview in a summary.
+- Judge the delivered artifact, not an explanation of format selection. Leave native-run behavior unproved until the case runs.
+
+## animated-mechanism
+
+### Task
+
+Show why an importer must write a record before reporting progress. Show the record becoming durable, then the progress event, as a short automatic animation. Do not make me click. This is an illustrative explanation, not evidence from a real application.
+
+### Criteria
+
+- Use the animation to show the named record, durable storage and progress event in the correct causal order.
+- Keep the message understandable without controls, extra introductions or duplicated prose.
+- Distinguish illustration from application proof; inspect actual timing rather than inferring motion from a still.
+- HTML adds the requested animated mechanism; a styled list of phases alone does not meet the task.

package/skills/design/SKILL.md

@@ -13,11 +13,11 @@ Follow the engineering skill and the repository's `CODING_STANDARDS.md` when pre
 
 ## Before the first draft
 
-The first draft the user sees is already the refined one. Work through these steps privately, then show the result.
+For an open direction, show a question-sized prototype before polishing it. Use orchestrator when available to settle consequential user choices. Approval is provisional: let the user try a small real journey before expensive expansion. Own routine refinement, but expect the real experience to change the user's direction.
 
 1. **Task and feeling.** Name the person, their task, their context and the feeling the product gives, such as calm, fast or trustworthy. Name three qualities the person notices, each with what "excellent" looks like.
 2. **Baseline.** Name the category and platform, and the reference screen for each screen you build: one of Apple's apps on iOS, the product's existing screen, or a reference the user named. Capture the reference in the states you need. Start from the system or established component defaults.
-3. **Range.** When the structure is open, compare structurally different solutions on the same data, including one that removes the interface by automating the task. Keep the strongest and combine compatible strengths.
+3. **Range.** Compare structurally different solutions only when the structure has a real unresolved fork, on the same data. Include a simpler solution that removes unnecessary controls. Show the smallest comparison that decides the fork, then develop the chosen direction.
 4. **States.** List every screen, its reachable states (empty, loading, partial, error, success, long content) and the events between them, before any code. Group states by concern instead of multiplying every combination.
 5. **Settled choices.** Carry forward what the user approved and what he removed. Never re-add a removed element or change an approved detail without a request.
 
@@ -98,9 +98,9 @@ The first draft the user sees is already the refined one. Work through these ste
 
 ## Prototype and tune
 
-**Variants.** When layout or interaction has real alternatives, build an interactive render before product code: two or three variants on the same data, each clickable through every state from the States step. Give the page a variant switch and a grouped state selector that the phone can use. Fill it with realistic mock data, and draw it as close as possible to the code you will write: the app's tokens, components, copy and behavior. For a native app the render settles structure, flow and states; settle the final look in simulator captures. Label each variant with its one difference and mark your recommendation.
+**Variants.** For a real unresolved choice, show one representative journey or a small comparison on the same realistic data before product code. Use the app's tokens, components, copy and behavior. Add interaction only when manipulating the subject exposes a consequential difference; never add tabs or a state dashboard merely to navigate the explanation. Get the direction approved before expanding its states and polish. For a native app the render settles structure and flow; settle its native appearance in simulator captures.
 
-**Real host.** Build one representative screen with realistic data in the real host: the browser preview for the web, the simulator for a native app. An HTML imitation of a native screen misleads.
+**Real host.** For a consequential behavior or taste choice, build one complete representative journey with realistic data in the real host: the browser preview for the web, the simulator for a native app. Let the user try it before broader implementation and polish. Complete specified fixes and approved-pattern work with focused proof, without a user checkpoint. Carry unaffected choices forward when feedback changes the journey; revise the affected design instead of defending prototype approval. An HTML imitation of a native screen misleads.
 
 **Tune.** Settle values yourself. For values you cannot settle by reasoning, such as spacing, timing, springs or blur, capture candidates side by side, including both extremes, and judge them against the reference. Write the chosen values into the source and recapture.
 
@@ -132,28 +132,31 @@ Ground the page in its subject: name the audience and the page's one job, and ta
 
 ## Visual explanations
 
-These rules cover diagrams, review pages and rendered agent answers; the reply decides when it needs a render. A render adds spatial or interactive information and replaces the text it shows; it never redraws prose, a file list, a check table or a fake runtime screenshot.
-
-| The reader asks                      | Exhibit                                                       |
-| ------------------------------------ | ------------------------------------------------------------- |
-| What does it look like now?          | State map of the changed system, changed parts marked         |
-| What changed on screen?              | Before and after pair with the same data, the old state left  |
-| Which transitions are allowed?       | State machine with forbidden edges marked                     |
-| What happens in order, and who acts? | Sequence in swimlanes, one lane per actor                     |
-| Where did the time go?               | Timeline with bars on one time axis                           |
-| How much faster, bigger or cheaper?  | Bars on a shared axis, values printed on the bars             |
-| Where exactly is the defect?         | Annotated capture with numbered markers and short notes       |
-| Which requirement has which proof?   | Coverage grid of requirements against proof, colored by state |
-| How do the parts relate?             | Node and link map with few, labeled links                     |
-| Which option is better?              | Options side by side at the same size and with the same data  |
-| What will a video show?              | Storyboard of chapter frames, the outcome frame marked        |
+These rules cover diagrams, review pages and agent answers. Transmit a specific message with the fewest words and least effort. Write that message privately before choosing the form. Markdown lists, tables and embedded captures are visual representations. Use them directly when they carry the message; do not rebuild them in HTML. HTML complements Markdown only when a necessary spatial relationship, motion or direct manipulation exceeds Markdown's capabilities. Name that added capability privately before rendering; decoration is not one. Use a sentence when it is clearer. Never turn a source list, process recap or checklist into a dashboard.
+
+| The reader asks                      | Exhibit                                                        |
+| ------------------------------------ | -------------------------------------------------------------- |
+| What does it look like now?          | Real capture, or a named system view with changed parts marked |
+| What changed on screen?              | Before and after pair with the same data, the old state left   |
+| Which transitions are allowed?       | State machine with forbidden edges marked                      |
+| What happens in order, and who acts? | Sequence in swimlanes, one lane per actor                      |
+| Where did the time go?               | Timeline with bars on one time axis                            |
+| How much faster, bigger or cheaper?  | Bars on a shared axis, values printed on the bars              |
+| Where exactly is the defect?         | Annotated capture with numbered markers and short notes        |
+| Which requirement has which proof?   | Coverage grid of requirements against proof, colored by state  |
+| How do the parts relate?             | Named actors and explicit relationships; no unlabeled blocks   |
+| Which option is better?              | Options side by side at the same size and with the same data   |
+| What will a video show?              | Storyboard of chapter frames, the outcome frame marked         |
 
 When none fits, choose the form that matches the data's shape; draw a list as a list.
 
-- **One message.** Each page answers one question, and its first line states the conclusion, such as "The catalog loads 26 times faster".
-- **One dominant element.** Size, weight and position show importance; mute the context. Show at most six labeled elements; never a text table, a collapsed card or a filter chip.
+- **One message.** The first visible state must state the actual change, comparison or consequence. Put the relevant names, direction, units and state on the subject. Use a sentence only when the graphic otherwise requires guessing. A decorative title or recap is not a substitute for that meaning.
+- **One dominant element.** Size, weight and position show importance; mute context. Use the available width without stretching an empty stage. Add each shape, label and surface only for a relationship or action it communicates. Isometric depth belongs to a meaningful layer or ownership boundary, not arbitrary slabs.
 - **Honest scale.** Bars start at zero on one linear scale; draw a range as a range.
 - **Labels.** Put names, values and units on the data, with one scale per comparison. Labels and captions stay under twelve words, and a visual holds no paragraphs.
-- **Real content.** Use real names, numbers and captures, and show the scope.
-- **Interaction.** When side-by-side options or captures turn unreadable at phone width, show them at one position behind labeled tabs. The conclusion stays visible without a tap.
+- **Real content.** Use actual names, operations and relationships. Keep a proposal distinct from an applied change, and a simulated explanation distinct from application evidence. A physical model is useful only when its operation explains the concept without another metaphor to decode.
+- **Interaction.** Keep the message understandable without a click. Add a control only to explore a real alternative or change an assumption. A predetermined change uses an automatic sequence, not a required click. On a phone, keep essential comparisons visible; do not hide the answer in tabs or menus.
+- **Motion.** Animate the subject from its real source to its destination. Keep identity, scale, alignment and unchanged context stable. Use transform and opacity, not per-frame layout. Make transitions brief and uninterrupted; pause only to let the reader see a state. If a demonstration needs replay, make its reset distinct from an undo. Do not use an invisible one-shot movement as the only explanation.
+- **Host.** Match the enclosing UI's typography, density, controls, surfaces and semantic tokens, not only its colors. Keep the outer background transparent and remove unnecessary card wrappers. Prefer native CSS for simple automatic diagrams; use relative geometry instead of JavaScript sizing when it gives the same result.
+- **Proof.** Inspect the artifact in its actual host, including an intermediate frame and the final state. A valid file, a correct model or a headless screenshot alone does not prove readable, smooth, correctly triggered motion. Compare before and after at the same scale and actual playback speed. Fix a repeated failure in its representation or source, not with more prompt prohibitions.
 - **Check.** Use the host's theme variables, check light, dark and a 390-point width, and fix clipping, overlap and contrast before you show it. At that width the page stays under about 400 points tall.

package/skills/engineering/SKILL.md

@@ -3,10 +3,14 @@ name: engineering
 description: 'TypeScript and Effect code conventions paired with shared lint. Use when designing, implementing or reviewing product and test code, including prototypes.'
 ---
 
-**Scope.** Apply these rules and the repository's `CODING_STANDARDS.md` when present, and write each line right the first time; lint is only the fallback. A refactor or cleanup request applies every rule to every line of the owned files. Scratch code outside the repository follows no style rule. Do not create a standards file just to satisfy this reference.
+**Scope.** Apply these rules and the repository's `CODING_STANDARDS.md` when present. Aim for a structurally correct first pass with few lint errors, not a promise of zero diagnostics. Oxlint remains the authoritative check; instructions do not replace it. Oxfmt owns whitespace, indentation and other mechanical formatting. Use automatic formatting and available fixes instead of spending reasoning on those details; fix remaining structural diagnostics at their source without a full rewrite or weakened rules. A refactor or cleanup request applies every rule to every line of the owned files. Scratch code outside the repository follows no style rule. Do not create a standards file just to satisfy this reference.
+
+**Before checking.** Run Oxfmt and the repository's deterministic lint autofix before manual code analysis, independent review or a check-only lint pass. Use the owned scope and preserve unrelated changes. Run both even when generated code looks correct; automatic fixes need no model iteration. Analyze the remaining diagnostics and behavior only after normalization. For a read-only review, the author prepares the normalized diff; the reviewer never writes the reviewed checkout.
 
 ## Simplicity
 
+**Architecture.** Use architecture for a new boundary, state owner, background lifetime, dependency or storage contract. Reuse the existing shape for routine changes; do not turn a small feature into a framework.
+
 **MVP.** Write the most direct code that meets the request today. Apply YAGNI to every file, function, branch, parameter, option, export, Layer, check, config value, library and abstraction; configure only what callers vary. Write functional, explicit code: pure functions over immutable data, effects only inside Effect, and Effect modules instead of hand-written helpers.
 
 **Plan the shape.** Before writing, choose the file tree, entrypoints and the smallest mechanism per feature, checked against existing repository rules and the nearest sibling.

package/skills/review/EVALS.md

@@ -0,0 +1,24 @@
+# Review evaluations
+
+These cases and criteria are drafts for discussion with the user, not approved acceptance thresholds.
+
+## review
+
+### Task
+
+Is this folder-import change ready for me to accept? Review the current diff without changing application code.
+
+### Criteria
+
+The starting repository contains the existing single-file importer and an uncommitted folder-import change. Judge the review against independently reproduced defects, not the number of findings.
+
+- Detect omitted nested files and progress emitted before durable writes.
+- Show the reaching input, observable consequence and smallest fix for each defect.
+- Keep findings limited to the changed behavior and its real consumers.
+- Do not flag preserved schema decoding, cause mapping or sequential stream consumption as defects.
+- Do not rewrite code, invent requirements or reverse settled decisions.
+- Keep the report readable and actionable; omit praise and process narration.
+- Reproduce suspicions with inline probes rather than adding permanent tests or private test seams.
+- Preserve independent validation, failure causes and existing caller contracts during cleanup.
+
+Record missed defects, false positives, unnecessary reads, tokens, elapsed time and corrective requests separately. The user judges whether the report supports acceptance. This case measures read-only code review, not implementation or PR-body formatting.

package/skills/review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: review
+description: 'Read-only, evidence-backed review of code, architecture, cleanup, designs, instructions and published artifacts. Use for reviews, audits and critiques; the author owns implementation, services and browser interaction.'
+---
+
+# Review
+
+Challenge the work independently. Trace the contract, try its strongest reachable counterexample and establish the consequence before reporting a defect. The author's rationale is a hypothesis, not authority. Apply the available engineering, architecture, design and testing skills by name; when one is unavailable, use the repository's explicit contracts without inventing its rules.
+
+## Code review
+
+Review the normalized diff: the author must run Oxfmt and deterministic lint autofix first. Do not spend review reasoning on formatting or already-fixable diagnostics. If normalization is unavailable, name that gap and have the author prepare it; never mutate a read-only target.
+
+- **Depth.** Read every hand-written changed line. For generated output, review the generator change and a sample, such as one package per source format. Trace each contract through its real consumers, failure paths, concurrency and resource ownership against the merge base. Try the inputs, orderings and failures that the tests miss. When the change refactors a whole file, list each behavior the file had at the merge base and prove that each one still holds, apart from the planned change.
+- **Findings.** Report broken behavior or contracts that a real caller's input reaches. Report violations of engineering, design or `CODING_STANDARDS.md` in changed lines, and in every line of a file that the task adds or rewrites. Skip what lint enforces outside legacy lists, and restyling that the change does not need.
+- **Beyond the diff.** A contradiction with an unchanged file, a stale reference that the change leaves, and a false assumption that the change rests on are findings.
+- **Not findings.** Taste without a rule, wording, hypothetical inputs, and defects that the branch neither made nor relies on.
+- **Later rounds.** Retain the covered commit, contracts and scope. Review only uncovered hunks, the fixes since that commit, and their affected consumers. Reuse prior source reads while those sources are unchanged. A confirmed local fix needs no new independent round unless it introduces an uncovered contract, mechanism or failure path. A new notice or a changed PR body is not a code-review trigger.
+- **Probes.** Settle a suspicion with disposable inline code against the public interface, real data or installed artifact. Use the repository's runtime command, such as `vp node -e '<script>'` or `vp env exec bun -e '<script>'`; verify that it loads the source and dependencies. Do not create a test file, worktree or test-only seam to answer one question. Never start a service or test suite during read-only review.
+- **Browser evidence.** Inspect the existing preview, captures, console and relevant requests without changing page state. Give the owner the smallest missing browser action and observable result to check; the owner drives the browser and records it. A screenshot proves a visible state, not unobserved timing, persistence or release behavior.
+- **Test value.** Use testing to decide whether a permanent test protects a distinct plausible regression. Do not demand a new test for every finding when an inline probe or existing browser proof settles it.
+- **Variants.** After reproducing a defect, look for the same root cause in its other real callers. Broaden one dimension at a time and stop when unrelated hypotheses replace concrete evidence.
+
+Return the findings, or "Clean" with the covered scope. Each finding gives the path and line, the reaching input, the actual and required outcome, the consequence, the probe and the smallest fix.
+
+## Cleanup audit
+
+Classify every changed file and hunk against the user's outcome and the reachable existing contracts. The author's plan does not authorize added scope. Default to removal, but preserve security, accessibility, required dependencies and useful regression protection:
+
+- **Revert:** unrelated formatting, lint-only rewrites, renames, reordered keys and files. Retain a required root fix and the repository's explicit cleanup scope. Do not weaken valid rules to retain obsolete code.
+- **Supersede:** features and versions that the final direction replaced, compatibility for unreleased versions, and capabilities that only a test or demo needed.
+- **Simplify:** the same behavior with less code or a clearer layout: files, folders and names that break the repository's layout, dead code, unused exports, duplicate logic, layered overrides, no-ops and workarounds.
+- **Cut:** anything the request does not need: features, function branches, files, libraries, settings, config values, UI elements, and machinery such as budgets, retries, caches, fallbacks, queues, daemons and dependency patches. Name what the user loses without each one; when he loses nothing, it goes.
+- **Keep:** a required outcome, dependency, reachable existing contract or useful regression proof. Quote the requirement or show the caller and the input that break without it.
+
+Read every hand-written hunk; a sample is not an audit. Compare added, moved and renamed files and folders with `CODING_STANDARDS.md` and the closest sibling app or package. Near-empty files and helper files that mix roles are Simplify rows. Judge generated output through its generator and a sample. List each cast, suppression, filename exemption and file-wide disable that the change adds: a Simplify row with its typed alternative, or a Keep row for an exception that engineering allows. Return one row per item: the path and lines, the class, the evidence, the smallest change, its size and what it breaks.
+
+## Critique
+
+Challenge the outcome, the taste and the attempts so far, and do not defer to the author. Compare different mechanisms, including a smaller one. Test the strongest counterexample and the weakest assumption. Prefer a reversible combination of compatible strengths. Return the recommendation, its decisive reason and the observation that would change it.
+
+## Instruction review
+
+Review the affected instructions as one system: prompts, skills, references, settings, repository rules and installed copies in the requested scope. Read every relevant file whole. Check each rule against the runtime and tool behavior it assumes, in source or a real session. Installation belongs to the configuration owner, not the reviewer.
+
+Report contradictions, duplicate rules, rules that only one harness gets, rules that no agent can act on, stale names, paths and models, breaks of applicable repository language rules, text that does not change an agent's action, and eval claims without evidence. Return the findings ranked, each with the path and line, the probe and the smallest change.
+
+## Body reader
+
+Read the published pull request as a reviewer who knows nothing else. Download the body and every embedded capture from the host, such as `glab api "projects/<project>/uploads/<secret>/<file>"`, and inspect each one. Compare them with the branch head and the source tickets. Report:
+
+- A risk that a tired reviewer misses: a migration, contract change or removed behavior the published body does not name.
+- A claim that a capture or the code contradicts.
+- A ticket requirement without proof.
+- A capture that is unreadable, ends before its outcome, or shows loading that is not the claim.
+- Each departure from the repository's publishing contract or the available delivery skill.
+
+Return each finding with the section, the evidence and the smallest fix.

package/skills/testing/EVALS.md

@@ -16,5 +16,7 @@ This case supplies the folder-import implementation. Judge the agent's tests sep
 - Prove the tests fail when progress is emitted before the write and when a detached writer continues after cancellation; mutation trials run outside the candidate checkout.
 - Cancel during an active file read through a controlled filesystem adapter and verify release. Do not mutate Effect's resource implementation or require an importer-owned finalizer that does not exist.
 - Reject tests of private implementation details, fabricated successes and redundant assertions.
+- Keep only distinct regression protection with a named wrong implementation and observable failure; do not reward new files or case count.
+- Use inline probes and real browser evidence for one-off questions without turning each observation into a permanent test.
 
 Report which defects each test detects and which remain uncovered. Do not reward test count or coverage percentage. Record merge readiness and effort separately.

package/skills/testing/SKILL.md

@@ -7,12 +7,12 @@ description: 'Select and run black-box behavior proof for Effect apps and tools.
 
 **Scope.** Test behavior the changed code owns; a coverage count proves nothing.
 
-- **Worth it.** Test owned branching, computation, parsing and state transitions that a plausible regression breaks.
+- **Worth it.** Retain a test only when it names owned behavior, a plausible wrong implementation, an independently known observable result and distinct protection. State what breaks without it. A green suite, coverage increase or extra case is not a reason to keep a test.
 - **Public interface.** Test exported Layers, services and functions through observable behavior, so a rewrite that keeps the contract keeps the tests green. The browser proves web UI components; the simulator proves native ones.
 - **Redundant.** Delete touched cases that only repeat dependency guarantees, constants, wording, removed behavior or a covered input. Keep boundary tests of the application's own validation, encoding or integration.
 - **Independent.** Take expected values from the contract or a worked example, never from the implementation. Use the smallest reachable fixture that tells the cases apart.
-- **Bugs.** Reproduce a bug before you fix it. Keep the failing case when it protects owned behavior, in the existing test of the fixed code, or in a new case when none fits.
-- **Throwaway.** Settle a question with a spike, and delete it once answered unless it becomes a regression test.
+- **Bugs.** Reproduce a bug before you fix it. Keep a regression case when future changes can plausibly break its contractual behavior, in the existing test of the fixed code or a new case when none fits. An independently reproduced defect does not require a new test file.
+- **Throwaway.** Start with question-sized inline code, an existing test or a focused real-browser check. Delete the spike after it answers the question. Promote it only when its distinct regression protection meets Worth it; never add a private export or configurable production seam just for proof.
 - **Honest.** No wrong expectations or rule workarounds. Change assertions only for recorded behavior changes, and keep every still-relevant value.
 
 **Assertions.** Use one representative input per behavior, in its existing case. Share a helper only between cases that use it. Use @effect/vitest assertions for outputs and structured error identity. Replace dependencies through Layers or public parameters, never global or module mocks. Keep mutable state in its owning fixture.
@@ -42,6 +42,7 @@ assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).l
 - **Branches.** Exercise the reachable distinctions: empty, duplicate, concurrent and dependency failure. Write no Cartesian product, and no random or repeated happy paths without a hypothesis.
 - **Failure.** Use `Effect.flip` for an expected failure and `Effect.exit` for both outcomes. Assert domain identity and preserved state and resources: no partial write, lost value, extra retry or leak. Wording or rejection alone is not enough, and incidental order is no assertion.
 - **Control.** Run the regression test against the unfixed implementation, and confirm that the intended assertion fails, not setup, imports or compilation. Before a refactor, cover the old behavior.
+- **Audit.** Remove duplicate and tautological cases in the touched scope, but retain independent protocol, package, validation, authorization and persistence contracts. Mock call counts do not prove an external boundary. Do not replace a useful test with a disposable script just to reduce the count.
 
 ## Effect and fixtures
 
@@ -49,7 +50,7 @@ assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).l
 - **Lifetime.** `it.effect` and `it.live` supply a Scope per case; `it.layer` acquisition belongs to its block. Use scoped platform resources and no redundant whole-case `Effect.scoped`. To assert cleanup, close the smaller operation scope before you inspect.
 - **Isolation.** Shared layers share mutable services, `TestClock` and `TestConsole`, and `Layer.fresh` does not reset cached context. Use distinct keys, a public reset or case-local fixtures. Cases pass alone and together.
 - **Clock.** Take `TestClock` and `TestConsole` from `effect/testing`. Fork, await a `Deferred` at the dependency boundary that carries the actual key or path, adjust time, then join; forking alone is not readiness. JavaScript timers, sockets and processes need live services.
-- **Concurrency.** Give the dependency an entered and release pair: await entry, start the competing action, release, then assert the contract. Set `Effect.all` concurrency for overlap. For cancellation, await acquisition, interrupt and await completion, and assert that an unrelated outer Scope stays open. Never test primitives or incidental ordering.
+- **Concurrency.** Give the dependency an entered and release pair: await entry, start the competing action, release, then assert the contract. Set `Effect.all` concurrency for overlap. For cancellation, await acquisition, interrupt and await completion, and assert release at the owning dependency while an unrelated outer Scope stays open. Joining an interrupted fiber alone does not prove resource release. Never test primitives or incidental ordering.
 - **Boundary.** Double only dependencies outside the tested logic, through a Layer or a public parameter. A claim about an SDK, process, filesystem, HTTP, browser or package integration needs the real boundary, not mocks or spies.
 - **Artifacts.** Prove a public tool with real packing and declared dependencies, not source imports or stubs. Generate fixtures with the real generator after one representative input settles; never alter expected output to fit a bug.
 - **Platform.** `FileSystem.layerNoop` is not memory storage, and `HttpServer.layerServices` supplies no filesystem: use a platform Layer and scoped paths. `RpcTest` bypasses serialization, and `HttpApiTest` bypasses sockets but proves routing, encoding, middleware and decoding; neither proves deployment or an external integration.
@@ -59,5 +60,5 @@ assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).l
 - **Run.** Use the documented test selectors, and confirm that they collect and run the intended cases. Zero collected tests, setup alone or exit code 0 alone prove nothing.
 - **Inventory.** Collect independent failures in one run instead of stopping at the first, and tell separate cases from repeated observations. Rerun a timed-out test once in isolation; a pass proves that run, not the cause. Never call a bypassed selector or a skipped operation flaky.
 - **Evidence.** Keep the first failure, exact command, execution count and exit status. Separate cause from hypothesis, product defect from setup failure, and a skipped criterion from a passing one. A source read or a green command never replaces a missing behavior check.
-- **Final proof.** A check proves only the source, dependencies and configuration it ran on, so reconcile every required behavior on the final code. Release proof uses the production build, not the development server. Screenshots and video prove visible outcomes; execution through the public interface proves the rest.
+- **Final proof.** Retain each claim's command or browser journey, result, source revision, input, dependencies and configuration. Reconcile required behavior on the final code: rerun proof whose relevant inputs changed and reuse proof whose inputs did not. A steer invalidates dependent claims, not every check or capture. Required final repository gates still run. Use the actual built preview for final browser proof when the repository provides one. A command named preview that runs development watchers does not prove the production build. Screenshots and video prove visible outcomes; execution through the public interface proves the rest.
 - **Visual proof.** Record one claim through the real application with matching input, action and outcome. Keep every meaningful step. A capture is stale once a component it shows changes. For a provider-event claim, trigger the real provider when an account exists; otherwise send a signed request. When only the user can do the provider-side step, prepare a guide.