@deslop/coding-standards 0.1.761 → 0.1.785

package/README.md

@@ -0,0 +1,72 @@
+# Coding standards
+
+Strict Oxlint preset and repository skill installer. Requires Node 26+; skill installation runs inside a Git repository, including linked worktrees.
+
+## Install skills
+
+```bash
+vpx @deslop/coding-standards@latest
+```
+
+| Result                                 | Scope                                                                                              |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Engineering, design and testing skills | Git root's existing `.agents`, `.claude` and `.codex` directories; creates `.agents` if none exist |
+| Refresh                                | Replaces only those three skill names; preserves other skills and global configuration             |
+| Boundary                               | Rejects destinations escaping the repository or overlapping global configuration                   |
+
+No repository dependency, manifest/lock change or lint configuration change. Treat installed skill copies as read-only; refresh through the CLI.
+
+## Use the lint preset
+
+```bash
+vp add -D @deslop/coding-standards @effect/tsgo
+vp exec effect-tsgo patch --no-typescript --oxlint
+```
+
+```ts
+import {defineConfig} from 'vite-plus'
+import {oxlint} from '@deslop/coding-standards'
+
+export default defineConfig({lint: {extends: [oxlint]}})
+```
+
+The preset uses Effect-tsgo's patched Oxlint and compatible tsgolint; keep the patch command in the project's prepare script. Match upstream supported tool versions. The skill installer neither configures lint nor upgrades/patches its toolchain.
+
+## Working here
+
+| Owner      | Decision                                                                                                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/`     | Flat package structure; rules in `src/rules`, no separate plugin or install-test harness                                                                                                    |
+| `skills/`  | Maintained engineering/design/testing 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/imprecise rules, not inconvenient valid diagnostics |
+| Rule proof | Existing public CLI regression cases, with accepted/rejected controls; no severity/exclusion workaround                                                                                     |
+
+## Rejected shortcuts
+
+| Candidate                                                | Reason                                                                                                       |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Blanket `unknown` type ban                               | Opaque SDK/framework contracts legitimately need it; narrow/decode before use instead of fabricating a shape |
+| Functional preset or dependency just to replace `no-let` | The preset conflicts; a selective plugin adds dependencies for a tiny rule                                   |
+| Syntax-only generator-failure rule                       | Factory-call syntax does not establish yieldability; the existing type-aware Effect rule owns that check     |
+
+With workspace dependencies installed, from the repository root:
+
+```bash
+vp test run tools/coding-standards/src/rules/rules.test.ts
+node tools/coding-standards/src/install.ts
+```
+
+## Skill inspiration
+
+| Source                                                                                                                                                                                                                       | Used / boundary                                                                                                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Matt Pocock's engineering skills](https://github.com/mattpocock/skills/tree/d81f3a183412e71a5b1e84ca21bc1a35eea03a60/skills/engineering)                                                                                    | Caller-first contracts, causal debugging and one uncertain behavior at a time; no universal TDD                                                                                                   |
+| [Cursor / pstack](https://github.com/cursor/plugins/tree/e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a/pstack)                                                                                                                    | Interface rationale, focused bug replay and defensible benchmarks; no playbook-stage machinery                                                                                                    |
+| [Kit Langton's Effect skill](https://github.com/kitlangton/skills/tree/71195e36024ebd2e66c5beac946e81eafd5abc43/skills/effect)                                                                                               | Schema construction/optionality, checked against actual [Effect 4 source](https://github.com/Effect-TS/effect/tree/67ba4e46a11ccda0b6761578bfd22c04ae00167d/packages/effect/src)                  |
+| [Vercel's agent skills](https://github.com/vercel-labs/agent-skills/tree/063bee94c3f4df8453406c830b0a7df0f2860278/skills)                                                                                                    | Independent I/O and narrow subscriptions, translated to Effect/atoms; no manual React memoization                                                                                                 |
+| [Anthropic frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design), [Taste Skill](https://github.com/Leonxlnx/taste-skill), [Vercel design guidelines](https://vercel.com/design/guidelines) | Task-led composition, typography and useful copy; no forced novelty, arbitrary aesthetic bans or plugin bundle                                                                                    |
+| [Emil Kowalski's skills](https://github.com/emilkowalski/skills/tree/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills)                                                                                                        | Realistic layout stress, interruptible motion and mobile checks; no fixed variant picker or audit fan-out. Performance caveats checked against [Motion docs](https://motion.dev/docs/performance) |
+| [Dillon Mulroy's skills](https://github.com/dmmulroy/skills/tree/8603380821fee6a77c82639f364ce8fe4f5a92be) and [anti-slop](https://github.com/dmmulroy/anti-slop/tree/c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b)              | Reviewed Effect/error and cleanup approaches; retain our own service layout and ownership                                                                                                         |
+| [Awesome DESIGN.md](https://github.com/VoltAgent/awesome-design-md) and [Impeccable](https://github.com/pbakaus/impeccable)                                                                                                  | Reviewed reference collections; community brand analyses are inspiration, not authoritative/current tokens                                                                                        |
+
+These are selectively adapted ideas, not imported frameworks. Concrete behavior, existing stack and settled user decisions govern the maintained skills.

package/dist/install.js

@@ -24685,7 +24685,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.1.761";
+var version = "0.1.785";
 //#endregion
 //#region src/install.ts
 const cli = pipe(make("deslop-coding-standards", {}, fnUntraced(function* () {

package/dist/oxlint.d.ts

@@ -4093,7 +4093,6 @@ export declare const oxlint: {
     '@deslop/coding-standards/no-double-nullish-check': "error";
     '@deslop/coding-standards/no-effect-property-arrow': "error";
     '@deslop/coding-standards/no-error-message-assertion': "error";
-    '@deslop/coding-standards/no-fail-in-generator': "error";
     '@deslop/coding-standards/no-fake-ref-state': "error";
     '@deslop/coding-standards/no-hand-written-guard': "error";
     '@deslop/coding-standards/no-let': "error";
@@ -4320,6 +4319,7 @@ export declare const oxlint: {
     'max-depth': ["error", number];
     'max-nested-callbacks': ["error", number];
     'no-cond-assign': "error";
+    'no-constant-binary-expression': "error";
     'no-continue': "error";
     'no-control-regex': "error";
     'no-debugger': "error";
@@ -4335,6 +4335,7 @@ export declare const oxlint: {
     'no-invalid-regexp': "error";
     'no-iterator': "error";
     'no-lonely-if': "error";
+    'no-loss-of-precision': "error";
     'no-misleading-character-class': "error";
     'no-multi-assign': "error";
     'no-negated-condition': "error";
@@ -4504,6 +4505,9 @@ export declare const oxlint: {
     'no-unneeded-ternary': "error";
     'no-unreachable-loop': "error";
     'no-unsafe-finally': "error";
+    'no-unsafe-optional-chaining': ["error", {
+      disallowArithmeticOperators: true;
+    }];
     'no-unused-expressions': "error";
     'no-useless-assignment': "error";
     'no-useless-backreference': "error";
@@ -4515,6 +4519,7 @@ export declare const oxlint: {
     'no-useless-escape': "error";
     'no-useless-rename': "error";
     'no-useless-return': "error";
+    'no-var': "error";
     'no-void': "error";
     'object-shorthand': "error";
     'oxc/branches-sharing-code': "error";
@@ -4528,6 +4533,7 @@ export declare const oxlint: {
     'prefer-template': "error";
     'require-unicode-regexp': "error";
     'react-doctor/no-call-component-as-function': "error";
+    'react-doctor/no-controlled-input-value-without-state-update': "error";
     'react-doctor/no-create-context-in-render': "error";
     'react-doctor/no-default-props': "error";
     'react-doctor/no-inline-exhaustive-style': "error";

package/dist/oxlint.js

@@ -612,7 +612,7 @@ Object.freeze({
 	}
 });
 //#endregion
-//#region ../../node_modules/.pnpm/oxlint@1.85.0_oxlint-tsgolint@7.0.2003_vite-plus@1.0.0_@opentelemetry+api@1.9.1_@types+_4709a04ba252a52ff927b8b254462122/node_modules/oxlint/dist/index.js
+//#region ../../node_modules/.pnpm/oxlint@1.85.0_oxlint-tsgolint@7.0.2003_vite-plus@1.0.0_@opentelemetry+api@1.9.1_@types+_bd1fc584f29238a6938d999624a6e509/node_modules/oxlint/dist/index.js
 /**
 * Define an Oxlint configuration with type inference.
 *
@@ -668,14 +668,6 @@ function importedMember(input) {
 		source: "effect"
 	}) && (input.propertyName === void 0 || contains(memberName(input.node), input.propertyName));
 }
-function effectBuilderName(input) {
-	const builder = input.node.type === "CallExpression" ? input.node.callee : input.node;
-	return builder.type === "MemberExpression" && importedMember({
-		context: input.context,
-		importedName: "Effect",
-		node: builder
-	}) ? memberName(builder) : none();
-}
 function isSchemaOperationName(name) {
 	return /^(?:(?:decode|encode)(?:Unknown)?(?:Effect|Exit|Option|Promise|Result|Sync)|asserts|is)$/u.test(name);
 }
@@ -892,33 +884,10 @@ const noArrayWrapTernary = defineRule({
 });
 //#endregion
 //#region src/rules/no-constant-function.ts
-function returnsConstant(node) {
-	const returned = returnedExpression(node);
-	return isNotNullish(returned) && (returned.type === "Literal" || returned.type === "Identifier" || returned.type === "MemberExpression" || returned.type === "TemplateLiteral" && isArrayEmpty(returned.expressions));
-}
-function functionScope(input) {
-	if (input.scope.block === input.node) return some(input.scope);
-	return findFirst(input.scope.childScopes, (child) => child.block === input.node);
-}
-function scopeReferences(scope) {
-	return appendAll(scope.references, flatMap$1(scope.childScopes, scopeReferences));
-}
-function isImportedVariable(variable) {
-	return isArrayNonEmpty(variable.defs) && every(variable.defs, (definition) => definition.type === "ImportBinding");
-}
-function resolvesToImport(reference) {
-	return pipe(variableFromScope({
-		name: reference.identifier.name,
-		scope: reference.from
-	}), exists(isImportedVariable));
-}
 function isConstantFunction(input) {
-	if (input.node.async || input.node.generator || isNotNullish(input.node.typeParameters)) return false;
-	if (some$1(input.spans, (span) => span.start >= input.node.start && span.end <= input.node.end)) return false;
-	return returnsConstant(input.node) && pipe(functionScope({
-		node: input.node,
-		scope: input.context.sourceCode.getScope(input.node)
-	}), exists((scope) => every(scopeReferences(scope), resolvesToImport))) && pipe(bindingName(input.node), flatMap((name) => variableFromScope({
+	if (input.node.async || input.node.generator || isArrayNonEmpty(input.node.params) || isNotNullish(input.node.typeParameters)) return false;
+	const returned = returnedExpression(input.node);
+	return isNotNullish(returned) && (returned.type === "Literal" && !hasProperty(returned, "regex") || returned.type === "TemplateLiteral" && isArrayEmpty(returned.expressions)) && pipe(bindingName(input.node), flatMap((name) => variableFromScope({
 		name,
 		scope: input.context.sourceCode.getScope(input.node)
 	})), exists((variable) => every(filter$1(variable.references, (reference) => reference.isRead()), (reference) => reference.identifier.parent.type === "CallExpression" && reference.identifier.parent.callee === reference.identifier)));
@@ -928,20 +897,15 @@ function isConstBound(node) {
 }
 const noConstantFunction = defineRule({
 	create: (context) => {
-		const spans = make$2(empty());
-		function mark(node) {
-			update(spans, append(node));
-		}
 		function report(node) {
 			if (isConstantFunction({
 				context,
-				node,
-				spans: get$3(spans)
+				node
 			}) && !singleUseThunk({
 				context,
 				node
 			})) context.report({
-				message: "This function reads nothing but imports, so it is a value: hold its result in a const.",
+				message: "Inline this argument-free literal return at its call sites.",
 				node
 			});
 		}
@@ -952,31 +916,33 @@ const noConstantFunction = defineRule({
 			"FunctionDeclaration:exit": report,
 			"FunctionExpression:exit": (node) => {
 				if (isConstBound(node)) report(node);
-			},
-			JSXElement: mark,
-			JSXFragment: mark,
-			ThisExpression: mark
+			}
 		};
 	},
 	meta: { type: "problem" }
 });
 //#endregion
 //#region src/rules/no-deep-pipe.ts
-function isPipeCall(node) {
-	return node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "pipe";
+function isPipeCall(context, node) {
+	return node.type === "CallExpression" && node.callee.type === "Identifier" && isImportBinding({
+		context,
+		importedName: "pipe",
+		node: node.callee,
+		source: "effect"
+	});
 }
-function enclosingPipes(node) {
+function enclosingPipes(context, node) {
 	if (node.type === "Program" || contains$1([
 		"ArrowFunctionExpression",
 		"FunctionDeclaration",
 		"FunctionExpression"
 	], node.type)) return 0;
-	const nested = isPipeCall(node.parent) && some$1(node.parent.arguments, (argument) => argument === node);
-	return enclosingPipes(node.parent) + (nested ? 1 : 0);
+	const nested = isPipeCall(context, node.parent) && some$1(node.parent.arguments, (argument) => argument === node);
+	return enclosingPipes(context, node.parent) + (nested ? 1 : 0);
 }
 const noDeepPipe = defineRule({
 	create: (context) => ({ CallExpression: (node) => {
-		if (isPipeCall(node) && enclosingPipes(node) >= 3) context.report({
+		if (isPipeCall(context, node) && enclosingPipes(context, node) >= 3) context.report({
 			message: "Flatten this pipeline; pipe calls nest at most three deep.",
 			node
 		});
@@ -985,23 +951,61 @@ const noDeepPipe = defineRule({
 });
 //#endregion
 //#region src/rules/no-destructured-parameter.ts
-function isPattern(node) {
-	const target = node.type === "AssignmentPattern" ? node.left : node;
-	if (target.type === "ArrayPattern") return true;
+function namedTuple(input) {
+	if (contains$1(input.seen, input.node)) return false;
+	if (input.node.type === "TSTupleType") return isArrayNonEmpty(input.node.elementTypes) && every(input.node.elementTypes, (element) => element.type === "TSNamedTupleMember");
+	if (input.node.type === "TSParenthesizedType" || input.node.type === "TSTypeOperator" && input.node.operator === "readonly") return namedTuple({
+		...input,
+		node: input.node.typeAnnotation,
+		seen: append(input.seen, input.node)
+	});
+	if (input.node.type !== "TSTypeReference" || input.node.typeName.type !== "Identifier") return false;
+	return pipe(variableFromScope({
+		name: input.node.typeName.name,
+		scope: input.context.sourceCode.getScope(input.node)
+	}), exists((variable) => some$1(variable.defs, (definition) => definition.node.type === "TSTypeAliasDeclaration" && namedTuple({
+		context: input.context,
+		node: definition.node.typeAnnotation,
+		seen: append(input.seen, input.node)
+	}))));
+}
+function component(node) {
+	const declared = node.type === "ArrowFunctionExpression" ? void 0 : node.id;
+	const assigned = node.parent.type === "VariableDeclarator" && node.parent.id.type === "Identifier" ? node.parent.id : void 0;
+	const name = declared ?? assigned;
+	if (name === void 0 || !/^[A-Z]/u.test(name.name) || node.params.length !== 1 || node.body === null) return false;
+	if (node.body.type === "JSXElement" || node.body.type === "JSXFragment") return true;
+	return node.body.type === "BlockStatement" && some$1(node.body.body, (statement) => statement.type === "ReturnStatement" && (statement.argument?.type === "JSXElement" || statement.argument?.type === "JSXFragment"));
+}
+function isPattern(input) {
+	const target = input.node.type === "AssignmentPattern" ? input.node.left : input.node;
+	if (target.type === "ArrayPattern") return !exists(fromNullishOr(target.typeAnnotation), (annotation) => namedTuple({
+		context: input.context,
+		node: annotation.typeAnnotation,
+		seen: []
+	}));
 	if (target.type !== "ObjectPattern") return false;
 	const named = filter$1(target.properties, (property) => property.type === "Property");
-	return !(named.length === 1 && named[0]?.key.type === "Identifier" && named[0].key.name === "ref" && some$1(target.properties, (property) => property.type === "RestElement"));
+	return !(input.component && named.length === 1 && named[0]?.key.type === "Identifier" && named[0].key.name === "ref" && some$1(target.properties, (property) => property.type === "RestElement"));
 }
 const noDestructuredParameter = defineRule({
 	create: (context) => {
 		function reportParameters(node) {
-			for (const parameter of filter$1(node.params, isPattern)) context.report({
+			for (const parameter of filter$1(node.params, (candidate) => isPattern({
+				component: component(node),
+				context,
+				node: candidate
+			}))) context.report({
 				message: "Take the value whole and read its fields instead of destructuring it.",
 				node: parameter
 			});
 		}
 		function reportLoopVariable(node) {
-			if (node.left.type === "VariableDeclaration" && some$1(node.left.declarations, (declarator) => isPattern(declarator.id))) context.report({
+			if (node.left.type === "VariableDeclaration" && some$1(node.left.declarations, (declarator) => isPattern({
+				component: false,
+				context,
+				node: declarator.id
+			}))) context.report({
 				message: "Take the value whole and read its fields instead of destructuring it.",
 				node: node.left
 			});
@@ -1125,50 +1129,26 @@ const noErrorMessageAssertion = defineRule({
 	meta: { type: "problem" }
 });
 //#endregion
-//#region src/rules/no-fail-in-generator.ts
-function insideEffectGenerator(input) {
-	if (input.node.type === "Program") return false;
-	if ((input.node.type === "ArrowFunctionExpression" || input.node.type === "FunctionDeclaration" || input.node.type === "FunctionExpression") && !input.node.generator) return false;
-	if (input.node.type === "FunctionExpression" && input.node.generator && input.node.parent.type === "CallExpression" && exists(effectBuilderName({
-		context: input.context,
-		node: input.node.parent.callee
-	}), (name) => contains$1([
-		"fn",
-		"fnUntraced",
-		"gen"
-	], name))) return true;
-	return insideEffectGenerator({
-		context: input.context,
-		node: input.node.parent
-	});
-}
-const noFailInGenerator = defineRule({
-	create: (context) => ({ CallExpression: (node) => {
-		if (node.callee.type === "MemberExpression" && importedMember({
-			context,
-			importedName: "Effect",
-			node: node.callee,
-			propertyName: "fail"
-		}) && node.parent.type === "YieldExpression" && node.parent.delegate && node.arguments[0]?.type !== "NewExpression" && insideEffectGenerator({
-			context,
-			node
-		})) context.report({
-			message: "Yield the error instead: return yield* E.make(...).",
-			node
-		});
-	} }),
-	meta: { type: "problem" }
-});
-//#endregion
 //#region src/rules/no-fake-ref-state.ts
 function propertyName(node) {
 	if (!node.computed && node.key.type === "Identifier") return some(node.key.name);
 	if (node.key.type === "Literal" && isString(node.key.value)) return some(node.key.value);
 	return none();
 }
+function hasUnusedSetter(input) {
+	const declaration = input.node.parent;
+	if (declaration.type !== "VariableDeclarator" || declaration.id.type !== "ArrayPattern") return false;
+	const setter = declaration.id.elements[1];
+	if (isNullish(setter)) return true;
+	if (setter.type !== "Identifier") return false;
+	return pipe(variableFromScope({
+		name: setter.name,
+		scope: input.context.sourceCode.getScope(setter)
+	}), exists((variable) => !some$1(variable.references, (reference) => reference.isRead())));
+}
 function isFakeRefState(input) {
-	if (!isReactUseState(input) || input.node.arguments[0]?.type !== "ArrowFunctionExpression" || input.node.arguments[0].body.type !== "ObjectExpression") return false;
-	return some$1(input.node.arguments[0].body.properties, (property) => property.type === "Property" && contains(propertyName(property), "current"));
+	if (!isReactUseState(input) || input.node.arguments[0]?.type !== "ArrowFunctionExpression" || input.node.arguments[0].body.type !== "ObjectExpression" || input.node.arguments[0].body.properties.length !== 1 || !hasUnusedSetter(input)) return false;
+	return some$1(input.node.arguments[0].body.properties, (property) => property.type === "Property" && contains(propertyName(property), "current") && property.value.type === "Literal" && property.value.value === null);
 }
 const noFakeRefState = defineRule({
 	create: (context) => ({ CallExpression: (node) => {
@@ -1492,18 +1472,43 @@ function insideCycleType(input) {
 		node: input.node.parent
 	});
 }
-function referencedName(node) {
-	if (node.type !== "TSTypeReference") return none();
-	if (node.typeName.type === "Identifier") return some(node.typeName.name);
-	return node.typeName.type === "TSQualifiedName" ? some(node.typeName.right.name) : none();
+function typeDeclarations(input) {
+	if (input.name.type === "Identifier") return pipe(variableFromScope({
+		name: input.name.name,
+		scope: input.context.sourceCode.getScope(input.name)
+	}), flatMap((variable) => variable.scope.block.type === "ClassDeclaration" && some$1(variable.defs, (definition) => definition.node === variable.scope.block) ? variableFromScope({
+		name: variable.name,
+		scope: variable.scope.upper
+	}) : some(variable)), map((variable) => map$1(variable.defs, (definition) => definition.node)), getOrElse(() => empty()));
+	if (input.name.type !== "TSQualifiedName") return [];
+	const name = input.name;
+	return pipe(typeDeclarations({
+		context: input.context,
+		name: name.left
+	}), flatMap$1((declaration) => {
+		if (declaration.type !== "TSModuleDeclaration" || declaration.body === null) return [];
+		return pipe(declaration.body.body, map$1(statementDeclaration), filter$1((node) => node !== null));
+	}), filter$1((declaration) => (declaration.type === "TSTypeAliasDeclaration" || declaration.type === "TSModuleDeclaration") && declaration.id.type === "Identifier" && declaration.id.name === name.right.name));
 }
 function shapeLiterals(input) {
 	if (input.type.type === "TSTypeLiteral") return [input.type];
-	return pipe(referencedName(input.type), filter((name) => !contains$1(input.seen, name)), map((name) => pipe(input.aliases, filter$1((alias) => alias.id.name === name), flatMap$1((alias) => shapeLiterals({
-		aliases: input.aliases,
-		seen: append(input.seen, name),
+	if (input.type.type === "TSUnionType" || input.type.type === "TSIntersectionType") return flatMap$1(input.type.types, (type) => shapeLiterals({
+		...input,
+		type
+	}));
+	if (input.type.type === "TSParenthesizedType") return shapeLiterals({
+		...input,
+		type: input.type.typeAnnotation
+	});
+	if (input.type.type !== "TSTypeReference") return [];
+	return pipe(typeDeclarations({
+		context: input.context,
+		name: input.type.typeName
+	}), filter$1((declaration) => declaration.type === "TSTypeAliasDeclaration"), filter$1((alias) => !contains$1(input.seen, alias)), flatMap$1((alias) => shapeLiterals({
+		...input,
+		seen: append(input.seen, alias),
 		type: alias.typeAnnotation
-	})))), getOrElse(() => empty()));
+	})));
 }
 const noReadonlyTypeSyntax = defineRule({
 	create: (context) => {
@@ -1512,7 +1517,6 @@ const noReadonlyTypeSyntax = defineRule({
 			program: context.sourceCode.ast
 		});
 		const shapes = make$2(empty());
-		const aliases = make$2(empty());
 		const properties = make$2(empty());
 		const methods = make$2(empty());
 		function exempt(node) {
@@ -1532,7 +1536,7 @@ const noReadonlyTypeSyntax = defineRule({
 			},
 			"Program:exit": () => {
 				const literals = pipe(get$3(shapes), flatMap$1((shape) => shapeLiterals({
-					aliases: get$3(aliases),
+					context,
 					seen: [],
 					type: shape
 				})));
@@ -1572,9 +1576,6 @@ const noReadonlyTypeSyntax = defineRule({
 			TSPropertySignature: (node) => {
 				update(properties, append(node));
 			},
-			TSTypeAliasDeclaration: (node) => {
-				update(aliases, append(node));
-			},
 			TSTypeOperator: (node) => {
 				if (node.operator === "readonly" && !exempt(node)) context.report({
 					message: "Use a mutable type shape.",
@@ -1597,7 +1598,7 @@ function isExported(node) {
 	if (node.parent.type === "ExportNamedDeclaration" || node.parent.type === "ExportDefaultDeclaration") return true;
 	return node.parent.type === "VariableDeclarator" && node.parent.parent.type === "VariableDeclaration" && node.parent.parent.parent.type === "ExportNamedDeclaration";
 }
-function inferredIdentically$1(input) {
+function inferredIdentically(input) {
 	const text = input.context.sourceCode.getText;
 	const body = input.node.body;
 	if (body === null) return false;
@@ -1620,7 +1621,7 @@ const noRedundantReturnType = defineRule({
 			const frame = last(get$3(frames));
 			update(frames, dropRight(1));
 			if (node.async || node.generator || isNullish(node.returnType)) return;
-			if (inferredIdentically$1({
+			if (inferredIdentically({
 				context,
 				node,
 				returns: match(frame, {
@@ -1710,14 +1711,6 @@ const noRedundantUseRefNullType = defineRule({
 });
 //#endregion
 //#region src/rules/no-redundant-variable-annotation.ts
-function isStringLiteral(node) {
-	return node.type === "Literal" && isString(node.value);
-}
-function inferredIdentically(input) {
-	const text = input.context.sourceCode.getText;
-	if (input.init.type === "TSAsExpression") return text(input.init.typeAnnotation) === text(input.type);
-	return input.init.type === "ConditionalExpression" && input.type.type === "TSStringKeyword" && isStringLiteral(input.init.consequent) && isStringLiteral(input.init.alternate);
-}
 const noRedundantVariableAnnotation = defineRule({
 	create: (context) => ({ VariableDeclarator: (node) => {
 		const annotation = node.id.typeAnnotation;
@@ -1729,11 +1722,7 @@ const noRedundantVariableAnnotation = defineRule({
 			});
 			return;
 		}
-		if (inferredIdentically({
-			context,
-			init: node.init,
-			type: annotation.typeAnnotation
-		})) context.report({
+		if (node.init.type === "TSAsExpression" && context.sourceCode.getText(node.init.typeAnnotation) === context.sourceCode.getText(annotation.typeAnnotation)) context.report({
 			message: "Drop this annotation; inference gives the same type.",
 			node: annotation
 		});
@@ -2153,7 +2142,7 @@ function schemaDefinitionMember(node) {
 	return none();
 }
 function isSchemaDefinitionName(name) {
-	return !isSchemaOperationName(name) && !/^to[A-Z]/u.test(name);
+	return !isSchemaOperationName(name) && !/^(?:is|to)[A-Z]/u.test(name) && !/^makeFilter(?:Group)?$/u.test(name);
 }
 function isSchemaDefinition(input) {
 	if (input.node.type === "CallExpression" && input.node.callee.type === "Identifier" && isImportBinding({
@@ -2361,7 +2350,6 @@ const oxlint = defineConfig({
 		"@deslop/coding-standards/no-double-nullish-check": "error",
 		"@deslop/coding-standards/no-effect-property-arrow": "error",
 		"@deslop/coding-standards/no-error-message-assertion": "error",
-		"@deslop/coding-standards/no-fail-in-generator": "error",
 		"@deslop/coding-standards/no-fake-ref-state": "error",
 		"@deslop/coding-standards/no-hand-written-guard": "error",
 		"@deslop/coding-standards/no-let": "error",
@@ -2638,6 +2626,7 @@ const oxlint = defineConfig({
 		"max-depth": ["error", 3],
 		"max-nested-callbacks": ["error", 6],
 		"no-cond-assign": "error",
+		"no-constant-binary-expression": "error",
 		"no-continue": "error",
 		"no-control-regex": "error",
 		"no-debugger": "error",
@@ -2651,6 +2640,7 @@ const oxlint = defineConfig({
 		"no-invalid-regexp": "error",
 		"no-iterator": "error",
 		"no-lonely-if": "error",
+		"no-loss-of-precision": "error",
 		"no-misleading-character-class": "error",
 		"no-multi-assign": "error",
 		"no-negated-condition": "error",
@@ -2888,6 +2878,7 @@ const oxlint = defineConfig({
 		"no-unneeded-ternary": "error",
 		"no-unreachable-loop": "error",
 		"no-unsafe-finally": "error",
+		"no-unsafe-optional-chaining": ["error", { disallowArithmeticOperators: true }],
 		"no-unused-expressions": "error",
 		"no-useless-assignment": "error",
 		"no-useless-backreference": "error",
@@ -2899,6 +2890,7 @@ const oxlint = defineConfig({
 		"no-useless-escape": "error",
 		"no-useless-rename": "error",
 		"no-useless-return": "error",
+		"no-var": "error",
 		"no-void": "error",
 		"object-shorthand": "error",
 		"oxc/branches-sharing-code": "error",
@@ -2910,6 +2902,7 @@ const oxlint = defineConfig({
 		"prefer-template": "error",
 		"require-unicode-regexp": "error",
 		"react-doctor/no-call-component-as-function": "error",
+		"react-doctor/no-controlled-input-value-without-state-update": "error",
 		"react-doctor/no-create-context-in-render": "error",
 		"react-doctor/no-default-props": "error",
 		"react-doctor/no-inline-exhaustive-style": "error",
@@ -3048,7 +3041,6 @@ var oxlint_default = definePlugin({
 		"no-double-nullish-check": noDoubleNullishCheck,
 		"no-effect-property-arrow": noEffectPropertyArrow,
 		"no-error-message-assertion": noErrorMessageAssertion,
-		"no-fail-in-generator": noFailInGenerator,
 		"no-fake-ref-state": noFakeRefState,
 		"no-hand-written-guard": noHandWrittenGuard,
 		"no-let": noLet,

package/package.json

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

package/skills/design/SKILL.md

@@ -5,103 +5,115 @@ description: 'UI and UX rules for screens and visual explanations. Use when buil
 
 # Design
 
-**Scope.** Follow repository-specific CODING_STANDARDS.md. CLI-installed skills are read-only; improve their package source and refresh via the CLI.
+**Scope.** Follow repository-specific CODING_STANDARDS.md and engineering.
 
-**Catalog.** List installed components and current shadcn registry capabilities before designing; group the available primitives by purpose. Inspect source/props rather than assuming training-era APIs. Reuse shared components; add missing registry components through the repository command, never hand-build or restyle them. Lint violations use existing tokens/variants.
+## Decide
 
-**Code.** Reuse one app host, compiler, theme, shared components and Tailwind tokens. No custom-CSS/dynamic-class escape or weaker scratch checks. Verify the first real slice before expanding.
+**Direction.** Start from the actual task, audience, content and settled preferences. Make the next user action and its relevant content dominant, not generic "premium" styling. When a reference is useful, inspect the relevant accepted one for transferable hierarchy, density and interaction choices; distinguish observed details from inferred ones. Community brand analyses are inspiration, not verified current tokens. Keep durable visual choices at their owner, not repeated briefs. Ask only about a consequential tradeoff the evidence cannot settle; another agent cannot establish user taste.
 
-```tsx
-// good
-<Badge variant="secondary">Draft</Badge>
-<Empty><EmptyTitle>No runs yet</EmptyTitle><Button onClick={() => startRun()}>Run</Button></Empty>
-// bad — "without hardcoding those values the desing/ui/ux need to be consistent with the rest of the app"
-<span className="rounded-full bg-[#eef] px-[7px] text-[11px]">Draft</span>
-<div className="flex flex-col items-center gap-2 p-6 text-muted-foreground">No runs yet</div>
-```
+**One meaning.** Each visible element must add information, enable a distinct action or clarify a relationship. Delete repeated headings, summaries, counts, status badges, decorative wrappers and controls that say or do the same thing. Remove explanations that merely restate the visible example/state. Keyboard shortcuts, screen-reader labels and responsive placement are not redundant visible controls; preserve their function.
+
+**Scan-first.** Put the task, relevant content and next action where they can be identified without reading a paragraph. Use stable visual roles, not another card/badge/icon for every fact. Expose needed detail on demand, never hide a consequential warning or essential action.
 
-**Consistency.** Match nearest screens: structure, spacing, type, icons, density, states, copy and behavior. Reuse their renderer; follow the majority where inconsistent. Without a sibling, use T3 Code's interface as reference.
+| Content                    | Preferred treatment                                                       |
+| -------------------------- | ------------------------------------------------------------------------- |
+| Comparable records/options | Aligned rows/columns; consistent order, units and metadata placement      |
+| Familiar action            | Conventional icon-only control with an accessible name; one visible owner |
+| Ambiguous action           | Clear text label, not an invented/guessed icon or redundant icon + text   |
+| Explanation                | Real state/example first; text only for missing context or consequences   |
 
 ```tsx
-// good — the picker every other model choice uses
-<ModelPicker value={model} onValueChange={setModel} />
-// bad — "make how the button behave consistent with the rest to not break the user expectations"
-<Select value={model} onValueChange={setModel}>{models.map(...)}</Select> // a second picker that behaves differently
+// one visible action, named for assistive technology
+<Button aria-label="Rename" size="icon"><PencilIcon aria-hidden /></Button>
+// redundant label for an already-obvious action
+<Button><PencilIcon />Rename</Button>
 ```
 
-**One way.** One representation/action, one consistent name and appearance. Remove redundant refresh, badges, icon-label pairs, decoration and wrappers.
+Do not remove necessary names, status, comfortable hit targets or instructions merely to make a screen smaller.
 
-```tsx
-// good
-<StarIcon aria-label="Default" />
-// bad — "i don't want refresh buttons or stuffs like that in the ui/app"
-<Button onClick={refetch}><RefreshIcon /></Button>
-<Badge><StarIcon /> Default</Badge> // "Don't have icons/emoji and text that say the same thing"
-```
+## Build
 
-**Compact.** Flat and dense: group by proximity before adding a card, cards only when elevation means something and never nested, and no empty vertical space.
+**Canonical components.** Reuse the existing renderer, states and interactions for the same role. Inspect its relevant source/API, not a full catalogue; add missing primitives through the repository registry command. Fix wrong shared patterns at their owner when delivering retained code, not before an exploratory preview. Without a sibling, use the supplied reference and component defaults within settled preferences.
 
 ```tsx
-// good
-<section className="flex flex-col gap-2">{rows}</section>
-// bad — "keep the UI flat/brutalist/minimal… don't have nested cards or visually heavy layouts"
-<Card><CardContent><Card className="p-8">{rows}</Card></CardContent></Card>
+// same model-selection control used elsewhere
+<ModelPicker value={model} onValueChange={setModel} />
+// another representation of the same job
+<Select value={model} onValueChange={setModel} />
 ```
 
-**Precision.** Exact on the design-system scale: icons sized by one shared box, one horizontal inset for search, pinned rows, dividers, and list rows; pinned rows outside the scroll area; borders that stay put while scrolling.
+**Tokens and structure.** Use the existing app host, compiler, theme, shared components and Tailwind tokens. No custom-CSS/dynamic-class escape, hardcoded color/size exception or weakened shared rules. Keep surfaces flat and dense; group by proximity before adding borders or elevation. No nested cards or wrappers that merely label content again. Whitespace must support hierarchy, separation or comfortable use, not fill the page.
 
 ```tsx
-// good
-<SearchIcon className="size-4" />
-// bad — "some icons have different sizes", "the spacing is kinda shitty"
-<SearchIcon width={15} height={15} />
+// existing primitives and semantic tokens
+<Empty><EmptyTitle>No runs yet</EmptyTitle><Button onClick={startRun}>Run</Button></Empty>
+// parallel hand-built appearance
+<div className="rounded-full bg-[#eef] px-[7px] text-[11px]">No runs yet</div>
 ```
 
-**Visible.** Controls are always visible, outlined or filled, never only on hover; state shows by background (the selected row, the active tab), never a check column; when rows share a name, the subtitle shows what tells them apart.
+**Typography.** Give headings, navigation, body text and data deliberate roles through the existing type scale, weights, line heights and readable line lengths. Use tabular numerals where values need comparison; let prose wrap without making controls inconsistent. Preserve established fonts and tokens rather than changing them for novelty. Do not substitute tiny labels, gratuitous capitals or isolated accent words for hierarchy.
 
-```tsx
-// good
-<TableRow data-state={selected ? 'selected' : undefined}>
-// bad — "i'm not a fan that things like the empty star comes out on hover"
-<Button className="opacity-0 group-hover:opacity-100" variant="ghost">
-```
+**Copy.** Name actions from the user's task, not implementation internals. Keep the same vocabulary across controls and confirmations. Use plain verbs and sentence case; labels describe outcomes, not decoration. Empty states offer a relevant next action; errors identify the failed action and available recovery. Reuse its existing control rather than repeating the action in text or adding another button; do not invent a recovery that cannot work.
 
-**Responsive.** Preserve the complete task on phones, not merely stacked desktop panes. Test narrow/wide screens, long/duplicate content, zoom, overflow, touch targets and reachable controls; no hidden essential action or deep nesting.
+| Weak                   | Useful                                                            |
+| ---------------------- | ----------------------------------------------------------------- |
+| `Submit`               | `Save changes` → `Changes saved`                                  |
+| `Something went wrong` | `Couldn't save.` beside the existing retry action; keep the draft |
+| `No data`              | `No notes yet` beside the existing create action                  |
 
-**Accessible.** Semantic landmarks, headings, labels and status/errors; keyboard navigation, visible focus, logical order and deliberate return, contrast, reduced motion and accessible names. Run axe and real keyboard/touch journeys; automated scans alone do not prove accessibility.
+**Alignment.** Give related headings, search, pinned rows, dividers and records one owning grid/inset. Headers and row contents share columns; action columns stay fixed when labels wrap or are absent. Use the same component/size variant for equivalent controls: icon box/stroke, hit target, control height, baseline and spacing. Pinned content stays outside the scroll area; borders do not jump while scrolling. Fix the owning layout/component, not per-instance offsets; matching boxes alone does not establish optical alignment or legibility. Trace the cause before applying these repairs:
 
-**Feedback.** Quiet local mutation feedback; pending/error state beside its action or field. Motion explains change, never delays input/navigation/reading. Use existing tokens and respect reduced motion; no animation dependency for a CSS state change.
+| Defect                             | Check                                         | Owning repair                                                                                      |
+| ---------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Squashed icon/avatar               | Fixed-size flex child shrinks                 | Preserve its canonical box with `shrink-0`                                                         |
+| Trailing action disappears         | Content track refuses to shrink               | `min-w-0` on content; `shrink-0` on the control, or a shrinkable grid track                        |
+| Wrapped rows look adrift           | Center alignment against variable-height text | Consistent, deliberate top/baseline alignment                                                      |
+| Identifiers look identical         | Truncation hides the distinguishing segment   | Preserve that segment; expose the full value through an existing keyboard/touch-accessible surface |
+| Counts shift during updates        | Proportional digits/inconsistent formatting   | `tabular-nums` + consistent locale/units                                                           |
+| Accents/tall scripts clip          | Tight line height or text-box clipping        | Fix the owning type-scale/overflow choice; don't shrink the font to fit                            |
+| Missing metadata leaves separators | Empty optional slots still render             | Omit orphaned separators/lines; reserve space only when the layout needs it                        |
 
-**Inspect.** Open actual desktop/phone captures: hierarchy, density, legibility, alignment, clipping, controls. Inspect meaningful video frames and sequence. Fix weak composition even when clicks/axe pass; a playable recording is not inspection.
+**Interaction and state.** Controls remain discoverable, never hover-only. Use the canonical selected-row/active-tab treatment; do not add a second badge or check column that echoes it. Keep pending/error feedback beside its owner and preserve recoverable input. No redundant refresh, copied state or polling shortcut around the existing reactive integration.
 
-## Prototypes
+**Motion.** Explain change without delaying input or moving content just for decoration. Reuse existing tokens/components; no new library for a fade or universal curve, duration, bounce or press scale.
 
-**Task.** Name the person, next action and uncertainty. Compare the same realistic task/data; hierarchy follows editing, scanning, comparison, graph exploration or review.
+| Interaction                            | Treatment                                                                                          |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Typing, shortcuts, frequent navigation | Immediate response; no decorative movement                                                         |
+| Trigger-anchored surface               | Enter/exit from its trigger; a centered unanchored modal keeps a centered origin                   |
+| Rapid toggle/reversal                  | Retarget from the visible state; no input lock, stale-target snap or wait for the prior transition |
+| Drag/gesture                           | Follow the pointer; preserve the existing primitive's capture, cancellation and release behavior   |
+| Reduced motion                         | Preserve feedback through a suitable static or gentle non-spatial equivalent                       |
 
-**Range.** Show at least five clearly different directions across information model, interaction, layout, density and visual language—not cosmetic variations. Include an ambitious/unexpected concept and a plain smaller direction; adapt useful real-product patterns. Label executable prototypes versus conceptual sketches and what each tests. Concepts may contribute only an interaction, hierarchy or visual idea; never imply they are working software.
+Use responsive entry easing and brief existing durations. Simple retargetable states suit transitions; gestures may need the existing spring. Prefer transform/opacity where appropriate, but CSS/WAAPI does not guarantee compositor execution. Profile observed performance problems, not every animation. Inspect rapid repetition/reversal and reduced motion, not only the final frame.
 
-**Behavior.** Executable candidates exercise the smallest complete journey plus choice-changing empty, long/duplicate, selection, pending, failure and permission states. Conceptual sketches state unimplemented behavior; judge their idea, not a fictional runtime pass.
+**Access and responsiveness.** Preserve the complete task on phones, not merely stacked desktop panes. Keep essential actions reachable with keyboard, touch and zoom. Use semantic structure, accessible names, visible focus, logical order and deliberate focus return. Inspect long/duplicate content, overflow, contrast and relevant failure/permission states. Do not remove an accessible affordance to satisfy visual minimalism.
 
-**Synthesis.** The user often chooses between directions. Compare transferable strengths/tradeoffs and propose a coherent blend; don't force a winner or concatenate incompatible mechanisms. Test the blend's weakest assumption before expansion.
+| Mobile defect                                 | Check                                                                                                |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Hover remains after tap                       | Capability-aware styles; inspect the framework's handling before adding another gate                 |
+| Input zoom/wrong keyboard                     | Readable input sizing + correct input type/mode; never disable browser zoom                          |
+| Bottom controls disappear                     | Real browser chrome, software keyboard and safe areas; appropriate supported viewport sizing/insets  |
+| Drag blocks scrolling/content can't be copied | Scope gesture/selection restrictions to their owner; preserve scrolling, zoom and selectable content |
 
-**Show.** Labeled, inspected desktop/phone views at consistent sizes; short video only for meaningful interaction. No manual variant-switcher journey. Reuse one host, discard losing source and expand the synthesis. Settled UI verification does not require five more directions.
+Touch and mouse can coexist; do not infer capabilities from user-agent strings or viewport width. No blanket suppression of overscroll, selection or native feedback without a demonstrated need and working replacement. Emulation verifies selected layout cases, not every phone behavior: affected device-specific keyboard/viewport/gesture contracts need target-device proof before completion.
 
-## Visual explanations
+## Prototype
 
-**Form.** Markdown for conclusions, comparisons and file maps; visuals for relationships/layout; interaction for exploration; video for change over time. Use the simplest useful form, not images of prose.
+**Try the question.** Build one rough representative screen/interaction in the existing host with realistic data. Inspect enough to make the trial trustworthy, then let the user try it before merge-readiness work. Label stubs and limits; a conceptual sketch is sufficient only when execution is unnecessary, never proof of working software. Set a short first-preview budget; show a partial result/blocker rather than expanding unseen. No production completeness or polished gallery first.
 
-**Hierarchy.** Outcome/decision, decisive evidence, limits. Group by reader question, not execution order; consistent labels and annotations beside their subject. Simplify/split for phones, never shrink unreadable canvases.
+**Use the findings.** For layout questions, compare hierarchy or interaction, not color-only variants. Add attempts only for unresolved uncertainty, feedback or an explicit request—no fixed count; a style question can compare style. Keep useful comparisons; discard/rebuild freely and combine compatible strengths, not incompatible mechanisms. Test the weakest assumption while it can change the choice. A settled direction needs no manufactured taste question or exploration round.
 
-**Review.** Map every semantic/config change to final packages/files; distinguish moves/generated copies and omit formatting noise. Use readable lists/tables, not compressed tree art. Explain behavior and consequential choices without requiring diff reading. Risks stay visible; supporting detail collapses. No host-status duplication or screenshot file browser.
+## Verify and show
 
-**Delivery.** Markdown carries the explanation. HTML complements it only where spatial relationships, layout or interaction communicate something Markdown cannot; never screenshot or record a replacement for readable prose, tables or file maps. Embed only the useful visual, beside its claim; keep secondary captures collapsed or linked rather than making a gallery the default reading path. Prove actual controls, keyboard access, desktop/phone layout and errors. Keep temporary hosts, source and media under the repository's ignored scratch path, never a root proof directory. Stop owned services and remove settled source. No duplicate chat, page and PR recap.
+**Inspect retained UI.** Open actual captures at the sizes needed for the task. Compare related edges, columns, baselines and equivalent controls across rows/screens—not just successful clicks. Use realistic long names/URLs, translated labels, Unicode, missing fields and relevant 0/1/many records at the actual container width. Respect schema/API limits; never add a validation limit to make layout pass. Mix cases across rows. Check selected/focus/error states and scrolling; a clean default row can hide misalignment. Inspect hierarchy, density, legibility and clipping. Exercise the relevant keyboard/touch, narrow/wide, zoom and focus-return journeys; run axe where applicable. A clean scan does not prove contrast or usability. Inspect meaningful video frames and sequence; a playable file is not proof of a good composition. Batch relevant inspection/repairs; recheck affected views rather than restart a whole audit after each micro-edit. Visible misalignment, inconsistent controls or redundant elements remain defects even when types/tests pass; fix them before claiming acceptance.
 
-**Theme and scale.** Agent-made visuals use the user's dark theme and existing design tokens. Verify browser color preference; a dark class alone does not activate a media-query theme. Align headings, controls and rows to shared insets; use consistent type/spacing and compact grouping, not empty space or tiny text. Show variants separately legible, not as a compressed strip. Inspect hierarchy, density and alignment at desktop/phone sizes; reject a weak composition even when overflow and clicks pass.
+**Show the design.** Use inspected screenshots for layout and short video for behavior. Compare at consistent sizes with states needed for the decision; no variant switcher just to see the options. Prefer the existing app-owned preview/element feedback. A visual must add spatial or interactive information, not reproduce prose, a file list or a fake runtime screenshot. Link useful existing evidence rather than render another explanation page. Use the user's theme and verify the actual browser color preference. Keep temporary source/services in ignored scratch, preserve useful media and retire settled attempts; persistent previews are opt-in.
 
-## Image assets
+**Review surfaces.** Open on the outcome the user needs to judge, with technical detail available on demand. Group by changed behavior, not files or agent stages. A selected example, diagram or diff must reveal its scope; never make curated evidence look like complete coverage. Do not build a custom review dashboard when existing captures and the PR can answer the question. A design-skill edit is not a product-screen change.
 
-Use image generation for an asset that benefits from synthesis—illustration, atmosphere, texture, an icon exploration—not for ordinary text, an exact diagram or a fake screenshot of functioning software. Use the native generation/editing tool exposed by the assigned harness (Codex image work uses its native image tool); never invent a tool call or substitute an API client when the capability is absent. Missing capability is a reported gap, not a successful generation.
+## Image assets
 
-Give the tool the asset's purpose, placement, composition, existing palette, intended dimensions/aspect ratio and output constraints. For edits, supply the real source image and name what must remain unchanged. Generate only assets the chosen direction needs; do not add speculative art or an image dependency to an otherwise complete UI. Use repository icons and CSS where they express the job more precisely.
+Use image generation only for a needed illustrative asset, atmosphere, texture or icon exploration—not ordinary text, exact diagrams or fake working UI. Use the native tool exposed by the harness; no invented invocation or replacement API client when unavailable. Report missing capability honestly.
 
-Inspect the actual returned file at its intended display size: composition, subject, crop, text/edge artifacts, contrast and fit with the surrounding screen. Correct visible defects before integrating. Preserve useful original output and identify it as generated; a generated visual is not runtime or browser evidence. Real UI proof still comes from the rendered app and actual interaction. Store only used assets in product source; remove discarded variants and temporary generation material.
+Describe purpose, placement, composition, palette and intended size/aspect ratio. For edits, supply the real source and state what remains unchanged. Generate only what the chosen direction needs; prefer existing icons/CSS when they express the job precisely. Inspect the returned asset at its intended size for crop, text/edge artifacts, contrast and fit. Preserve useful originals and identify generated assets as such; they are not runtime/browser proof. Keep only used assets in product source.

package/skills/engineering/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: engineering
-description: 'Engineering rules for product code, paired with the shared lint. Use before designing or editing code, writing tests, or reviewing a diff.'
+description: 'TypeScript and Effect code conventions paired with shared lint. Use when designing, implementing or reviewing product/test code, including prototypes.'
 ---
 
-**Scope.** Apply these rules and repository-specific CODING_STANDARDS.md. CLI-installed copies are read-only; improve their package source, then refresh through the CLI.
+**Scope.** Apply these rules and repository-specific CODING_STANDARDS.md.
 
-**Sources.** Match manifest/lock versions; inspect cloned upstream and nearest usage, never node_modules. Library APIs do not define coding policy.
+**Dependency APIs.** Match manifest/lock versions. Inspect the relevant cloned upstream implementation, types and nearest real usage before inventing an API wrapper or workaround; never node_modules. Follow only the paths needed to settle the question, with no dependency install/build just to read source. Library APIs do not define coding policy.
 
 **Diagnostics.** Use the shown idiom, not casts, weakened rules or a rewrite trading one diagnostic for another.
 
@@ -13,16 +13,18 @@ description: 'Engineering rules for product code, paired with the shared lint. U
 
 **Clarity.** Plain, explicit, idiomatic code, names and files; read top to bottom without commentary or cleverness.
 
-- **Requested only.** Build the smallest thing that does the requested job well and touch only what the request needs; an unrelated improvement is listed for the user. A refactor or cleanup request asks for depth instead: every rule applies to every line of the owned files.
+**Experiments.** Write with these idioms; reserve the full refactor/cleanup pass for retained delivery. Keep disposable source isolated and shared rules intact.
+
+- **Requested only.** Check whether existing code, an installed module or a platform capability already satisfies the contract before writing more. Implement only the missing behavior; shorter code never justifies dropping requested behavior, safety or accessibility. Touch only what the request needs; unrelated improvements are reported. A refactor or cleanup request asks for depth instead: every rule applies to every line of the owned files.
 - **Inward layers.** Domain and service code never import HTTP, RPC, or other transport types.
-- **Building blocks.** Offer services, Layers, and functions the caller composes like any Effect module, never a wrapper that bundles them behind one call such as `serve(app)`.
+- **Building blocks.** For a consequential new interface, start with a realistic caller operation and its ordering, failure and lifetime obligations; hide useful complexity, not forwarded names. Offer services, Layers and functions the caller composes like any Effect module, never a bundle such as `serve(app)`. No mandatory architecture document or alternatives round.
 - **No machinery.** Behave correctly instead of building hooks, guards, or generators to enforce behavior.
 - **Behavior kept.** A refactor keeps behavior at every usage point. Two differences are accepted and reported with the change: one no usage point observes that makes the code simpler, and one a rule here causes, such as an error keeping its cause or sorted keys, unless a usage point parses it; printed diagnostics are not a contract. Any other behavior change is the user's decision, except a reachable bug's fix.
-- **Reachable bugs.** A bug a real input from a usage point triggers is fixed and reported, with every consumer of the changed output checked. Handling for input no caller produces is deleted; anything that looks intentional or that other code relies on is kept and reported as possibly intentional.
-- **Performance.** Improve performance in the touched code where you know how; measure on a realistic input only when a change claims speed or keeps a slower-looking form. Diagnose at the layer that owns the symptom: distributed spans for RPC/backend dependencies, React commits for rerenders, a browser performance profile for main-thread work. Correlate one real action before changing code, then repeat it on the fix; neither a screenshot nor a service name proves latency or trace coverage. Use the repository's instrumentation and the tool's help; profiling is not a ritual on every change.
+- **Reachable bugs.** A bug a real input from a usage point triggers is fixed and reported, with every consumer of the changed output checked. For hard bugs, use one symptom-specific replay and a prediction per probe; compare known-good/broken states when useful. Remove edits motivated by disproven hypotheses and check the original scenario after reducing a reproduction. Handling for input no caller produces is deleted; anything that looks intentional or that other code relies on is kept and reported as possibly intentional.
+- **Performance.** Improve performance in the touched code where you know how; measure on a realistic input only when a change claims speed or keeps a slower-looking form. Diagnose at the layer that owns the symptom: distributed spans for RPC/backend dependencies, React commits for rerenders, a browser performance profile for main-thread work. Correlate one real action before changing code, then repeat it on the fix; neither a screenshot nor a service name proves latency or trace coverage. Time correct completed work under equivalent workloads/configuration; distinguish setup/cache/profiling cost and report run count/variation. Differences within noise are unproved, not speedups. Use existing instrumentation; profiling is not a ritual on every change.
 - **Type safety.** A fix never weakens types to make a symptom go away: no widened or erased type, cast, dropped generic, or loosened exported type.
 - **Domain.** Implement the definition the domain uses, such as a cycle for recursion, never the nearest syntactic proxy.
-- **Reread.** Before finishing, reread the diff and delete every line the outcome does not require.
+- **Reread.** Before delivering retained code, reread the diff and delete every line the outcome does not require.
 
 **Happy path.** Failures flow through the error channel: no catch, retry, fallback, backup, or defensive check unless the request or an existing contract needs it.
 
@@ -52,7 +54,7 @@ Math.floor(Duration.toDays(DateTime.distance(oldest.timestamp, newest.timestamp)
 import {glob} from 'glob' // a dependency Effect's FileSystem replaces
 ```
 
-**Whole values.** Pass whole values or spread them. No parameter/callback/loop destructuring except useState and component ref; project fields only to exclude data the recipient must not receive.
+**Whole values.** Pass whole values or spread them. No parameter/callback/loop destructuring except labeled tuple parameters, useState and component ref; project fields only to exclude data the recipient must not receive.
 
 ```ts
 // good
@@ -176,7 +178,7 @@ const parsed = Option.getOrUndefined(Number.parse(event.target.value))
 
 **Handlers.** A handler used once is an arrow in place; a handler used twice is a `function`.
 
-**Pairs.** A tuple stays whole, read by index.
+**Pairs.** Positional tuples stay whole, read by index. Meaningful named bindings such as React state/setter pairs and explicitly labeled tuple parameters are useful exceptions.
 
 **Accumulators.** No `let`: a fold or an Effect collection operation that says what it selects.
 
@@ -223,7 +225,7 @@ process.env.HOST ?? '0.0.0.0'
 
 **Pipe.** A standalone `pipe`, nested at most three deep; never the `.pipe` method.
 
-**Failures.** In a generator a failure is `return yield* E.make(...)`; outside one, `Effect.fail`.
+**Failures.** Yield a yieldable domain error directly in a generator: `return yield* E.make(...)`. Keep `Effect.fail(error)` when the error is not yieldable; outside a generator, use `Effect.fail`. Do not infer yieldability from factory-call syntax.
 
 ```ts
 // good
@@ -240,7 +242,7 @@ const text = Effect.fn('Ai.text')(function* (response: AiResponse) {
 })
 ```
 
-**Casts.** No `as`, `any`, or `unknown` annotation: decode unknown data once with a schema at the boundary; `satisfies` and `as const` are the only assertions.
+**Casts.** No `as`, `any` or erasing a known shape into `unknown`; `satisfies` and `as const` are the only assertions. Genuinely opaque SDK/framework inputs remain `unknown` until narrowed or decoded at their boundary—do not fabricate a shape to avoid that type. Decode incoming protocol data once with Schema before use.
 
 ```ts
 // good
@@ -248,7 +250,7 @@ const params = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Un
 return Effect.succeed([{text: part.text, type: 'text'} satisfies TextContent])
 // bad — a cast satisfies one rule and the next flags it
 const params = part.params as Record<string, unknown>
-create: Effect.fnUntraced(function* (input: unknown) {
+const params: unknown = part.params // erases an already-known shape
 ```
 
 **Decoders.** `Schema.decodeUnknownEffect` only for `unknown` input; typed input uses `Schema.decodeEffect`, and JSON text goes through `Schema.fromJsonString`.
@@ -279,7 +281,7 @@ import {type Plugin, createServer} from 'vite'
 export const EntryKind = Schema.Literals(['income', 'expense']) // no importer
 ```
 
-**Readonly.** Every property of a service shape is readonly, as in Effect's services, and so may class members be; readonly appears nowhere else, except on a `Schema.suspend` cycle's hand-written types.
+**Readonly.** Required on service-shape properties. Allowed on class members and handwritten `Schema.suspend` cycle types; otherwise forbidden.
 
 **Disables.** Fix the idiom or reproduce a rule defect. Inline disables require an unavoidable conflict and -- reason; never disable ordering or weaken file configuration. Report dependency-only diagnostics; rename filename violations.
 
@@ -377,7 +379,7 @@ static readonly layer = Layer.effect(Ledger, makeLedger) // a make with one call
 query(sql: string): Effect.Effect<Rows> // a method signature instead of a readonly property
 ```
 
-**Primitives.** Use Effect's primitives directly; rpcs and services already trace, and one scope owns each lifetime.
+**Primitives.** Use Effect's primitives directly; rpcs and services already trace, and one scope owns each lifetime. Compose established independent I/O with Effect.all and explicit appropriate concurrency; keep order-dependent, transactional or resource-conflicting work sequential.
 
 ```ts
 // good
@@ -442,7 +444,7 @@ const label = MutableRef.make<string>('') // repeats the inferred type
 export type SandboxLike = {id: string; renew: (seconds: number) => Promise<unknown>} // a copy of an inferred shape
 ```
 
-**Schema pairs.** Type pair immediately before every schema. Structs use Schema.Struct, never Schema.Class; reuse fields by spreading. Call schema.make directly for validation/defaults.
+**Schema pairs.** Type pair immediately before every schema. Structs use Schema.Struct, never Schema.Class; reuse fields by spreading. Use Schema.optionalKey for absent fields; Schema.optional allows explicit undefined too, so reserve it for that contract.
 
 ```ts
 // good
@@ -460,6 +462,18 @@ function cursorFromBigInt(value: bigint) {
 payload: Schema.Struct(pipe(PortfolioVisitor.fields, Struct.pick(['color', 'id', 'name', 'x', 'y']))) // the schema itself fits
 ```
 
+**Construction.** `schema.make` applies defaults and validates synchronously, throwing on failure; use it for trusted construction. For reachable fallible construction with defaults, use `schema.makeEffect` and map its `SchemaIssue.Issue` to the owning domain error. Effect decoders report `SchemaError`; use the correct error contract and do not revalidate already-narrowed data.
+
+```ts
+// good — reachable constructor failure stays in the error channel
+pipe(
+	Name.makeEffect(input),
+	Effect.mapError(cause => NameError.make({cause, message: 'Invalid name'}))
+)
+// bad — input can fail a refinement even though its TypeScript type is string
+Name.make(input)
+```
+
 **Cycles.** Handwrite each recursive-cycle type; annotate only Schema.suspend thunks. Noncycle types stay inferred; unions follow members.
 
 ```ts
@@ -557,6 +571,6 @@ const state = useState(false)
 ```
 
 - **Pure render.** Derive display values from props and subscribed state during render; never mutate them or perform an RPC, write or subscription there. Event handlers own user-triggered actions; Effects synchronize external systems, not copied state or calculations. Reuse the existing router/atom integration rather than fetching in a new Effect.
-- **State identity.** Keep one owner for each value, stable domain keys for list items and deliberate reset boundaries. Compiler memoization is a performance optimization, never a correctness or lifetime guarantee. Do not add manual memoization, compiler escape directives or weakened hook rules to hide an ownership problem.
+- **State identity.** Keep one owner for each value, stable domain keys for list items and deliberate reset boundaries. For an observed rerender problem, derive the needed value in the existing atom graph instead of subscribing to frequently changing unrelated state. Compiler memoization is a performance optimization, never a correctness or lifetime guarantee. Do not add manual memoization, compiler escape directives or weakened hook rules to hide an ownership problem.
 
 Testing judgment, fixtures, assertions and verification belong to the testing skill; these engineering rules still apply to test code.

package/skills/testing/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: testing
-description: 'Curated black-box tests and trustworthy verification for Effect applications and tools. Read before writing, reviewing or running tests; apply engineering to the test code.'
+description: 'Select and run black-box behavior proof for Effect apps/tools. Use when choosing, writing, reviewing or running tests; apply engineering to test code and keep exploratory proof question-sized.'
 ---
 
 # Testing
 
-**Scope.** Guard owned behavior, not coverage. CLI-installed skills are read-only; change their source and refresh via CLI.
+**Scope.** Guard owned behavior, not coverage.
+
+**Timing.** An experiment needs trustworthy proof of its question, not comprehensive release coverage. Final acceptance applies to retained delivery; label stubbed/unproved behavior.
 
 - **Worth it.** Test owned branching, computation, parsing/state transitions a plausible regression breaks; add missing valuable coverage before refactoring.
 - **Seam.** Test the exported layer, service, or function of a package or an app's service as a black box, so rewriting the implementation leaves every test green; the browser proves UI components.
@@ -38,7 +40,7 @@ assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).l
 
 ## Choose cases
 
-- **Contract.** Reachable input → observable output; a plausible wrong implementation must fail. Use the nearest public seam, not private helpers/new harnesses.
+- **Contract.** Reachable input → observable output; a plausible wrong implementation must fail. Use the nearest public seam, not private helpers/new harnesses. When behavior is uncertain, settle one reachable case with a focused check and minimal implementation, then choose the next case from the findings; do not batch tests for an imagined implementation or require universal TDD.
 - **Branches.** Exercise reachable empty/duplicate/concurrent/dependency-failure distinctions; no Cartesian product or random/repeated happy paths without a hypothesis.
 - **Failure.** Effect.flip for expected failure; Effect.exit for both outcomes. Assert domain identity and preserved state/resources: no partial write, lost value, extra retry or leak. Wording/rejection alone is insufficient; no incidental order assertions.
 - **Control.** Run against the unfixed implementation: the intended assertion fails, not setup/import/compilation. For refactoring, add missing coverage on old behavior first. Keep durable regressions, remove settled probes.
@@ -60,4 +62,4 @@ assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).l
 - **Inventory.** Collect independent failures once instead of cancelling the suite at the first failure. Distinguish separate cases from repeated observations. A timeout receives one isolated rerun of that same test; after a genuine pass, stop investigating it. Do not call a bypassed selector or a skipped operation flaky.
 - **Evidence.** Preserve 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 overall green command never substitutes for a missing behavior check.
 - **Stable inputs.** No writer changes a running check's source, dependencies, configuration or build inputs. A relevant edit invalidates its prior result; rerun affected criteria and reuse unaffected evidence. Independent research or browser journeys may continue without mutating those inputs.
-- **Final proof.** Reconcile every required behavior on the final code. Screenshots/video prove visible outcomes; public-seam execution proves nonvisual behavior; fresh agents prove changed agent instructions. Keep the result and useful evidence, not disposable drivers, fixture installs, reports or preview services.
+- **Final proof.** Reconcile every required behavior on the final code. Screenshots/video prove visible outcomes; public-seam execution proves nonvisual behavior; use fresh agents for changed instructions only when they can settle a consequential unresolved uncertainty, not routine wording edits. Keep the result and useful evidence, not disposable drivers, fixture installs, reports or preview services.