Enforce typed linting, declaration documentation, and shared style review

[jdeurt]

Change

Replace Engineering's automatic edit hooks with a reusable formatting/linting skill and a standalone style guide. Restore the requested lint policy, refactor owned source to satisfy it, and add tests for authored lint behavior. Extend code review to cover style, writing, duplication, and added dead code.

Lint policy and type information

• Core complexity uses its default maximum 20 at warning severity. The exact installed try rule is unicorn/try-complexity, enabled at warning severity with its default maximum 1. Lint rejects warnings.
• Restore recommended error severities/default options for unicorn/no-array-sort, unicorn/max-nested-calls (3), unicorn/consistent-boolean-name, unicorn/no-top-level-side-effects, unicorn/no-unreadable-for-of-expression, unicorn/prefer-simple-condition-first, unicorn/prefer-top-level-await, unicorn/no-nested-ternary, unicorn/prefer-logical-operator-over-ternary, unicorn/no-useless-undefined, and unicorn/prefer-string-replace-all. Restore nested-ternary enforcement after Prettier's compatibility preset.
• Preserve JavaScript no-use-before-define, no-magic-numbers, and no-shadow overrides and the corresponding enabled @typescript-eslint replacements on TypeScript.
• Apply 54 of 65 Stylistic recommended rules. Document the 11 actual Prettier conflicts in source and maintenance docs. Preserve unrelated rule settings.
• Enforce blank lines after final imports, after same-kind const/let groups, between function declarations and class members, and around class declarations. Cover exported forms. Function, method, and constructor overload signatures may stack with their implementation.
• Add jdeurt/const-on-top for both const and let. Require a declaration prefix before executable statements in program/block/static-block scopes. Preserve leading imports/types/functions/variables and loop-header declarations. var stays banned. No automatic initializer hoisting.
• Enable typed strict/stylistic linting and project service across owned JavaScript and TypeScript. Use allowJs, strict null checks, complete source coverage, and explicit generated/dependency exclusions. Preserve JavaScript core correctness checks. Remove declaration stubs that hid actual JavaScript source from the program.
• Keep the AGENTS authorization comment in source and bundled configuration. The configuration and local-rule implementation lint themselves under the same policy.

Remove the custom magic-string lint rule and its tests. Keep pragmatic naming guidance for paths, messages, and shared domain strings in the standalone guide. Remove the mechanical length threshold. Inline artificial one-use strings and remove naming-only helpers while preserving meaningful reused constants.

Declaration documentation

Add pinned eslint-plugin-jsdoc@65.3.15 because ESLint no longer includes documentation rules. Require useful documentation for top-level functions, all classes, and class methods. Include parameter descriptions and descriptions of actual returned values. Cover exported/default declarations, arrow/function-expression bindings, constructors, accessors, class fields containing functions, abstract methods, CommonJS assignment exports, and TypeScript export = functions. Preserve native CommonJS scope for .cjs and .cts.

Keep nested local functions and callbacks outside the mandatory declaration scope. Preserve stacked overload groups with shared documentation.

Use jsdoc/require-jsdoc, jsdoc/require-description, jsdoc/require-param, jsdoc/check-param-names, jsdoc/require-param-description, jsdoc/require-returns, and jsdoc/require-returns-description. Preserve inherited documentation-comment formatting. Document the repository's affected declarations and extract native packaging into a cohesive module to keep files below 350 lines. The guide separates caller contracts from inline rationale and avoids redundant signature narration. Its comment guidance draws from PEP 257, Google's review guidance, and Oracle's documentation guidance.

Skills, review, and packaging

Remove Engineering's edit hooks, private hook dependencies, wrappers, asset registration, workflow smoke step, and obsolete hook-only tests. Preserve native/import hook support. Build both client packages with the root ESLint config, Prettier config, and local rules under the new skill's references/javascript/.

The style reference contains 48 language-neutral concepts across nine numbered sections, each with one good and one bad example. Rules have identifiers such as 1A and 2B. It defines complexity and direct limits. It specifies consistent list layout at each nesting depth. It contains no ESLint rule names, source inventories, tooling/enforcement commentary, or rule-implementation details.

Independent file-only reviewers, including Astra, review all 48 rules from the beginning. Each rule includes a Why section that explains its requirements. Example-specific assumptions and outcomes appear inside code comments. Astra re-read all 48 revised rules sequentially and returned CLEAR, with no remaining actionable findings. The separate full-guide rationale reviewer and final packaging/cross-skill reviewer also re-reviewed the corrected source and returned CLEAR.

All 48 positive examples match their verified typed contexts. Strings receive names when they clarify meaning or support reuse. Simple local separators remain inline.

Import ASD-STE100 under Writing through an import declaration and marker. Preserve its original description/triggers, body, references, examples, MIT license, and standard-library Python checker. Normalize only an imported top-level string version into metadata.version. Reject conflicting/nonstring versions without loosening schemas. Imported content stays in temporary/generated output. Existing import fixtures use a local upstream for repeatable checks.

Code Review uses the style guide first. Each style finding reports the file and line, offending code/text, exact rule ID and title, and the reason. A sample review response demonstrates split imports (2H) and incomplete callable documentation (9B). Coherent Editing covers all changed text, including product copy. ASD-STE100 covers technical/agent-facing text and excludes user-facing product copy. Coherent Editing applies during initial authoring and final turn review, with no intermediate coherence polishing.

Register jscpd's stdio MCP server using npx -y jscpd@5 --mcp .. The skill checks the active project root and refreshes the scan. It handles truncated/unsupported results and compares changed code with other project source for Type 1, 2, and 3 clones. CLI fallback preserves project configuration. Dead-code analysis uses the project context, then filters findings to added code and checks dynamic/public entry points. Remove extra explanatory references outside the review skill. Preserve the imports and required MCP registration.

Shorten AGENTS.md while retaining its operational requirements. Add a concise requirement for tests of authored whitespace, casting, and custom lint behavior. Parameter-only changes to existing rules do not require new tests.

Tests and validation

Add 8 authored lint suites, using the actual configuration and a shared assertion helper. Cover JS/TS whitespace, overload behavior, chained assertions, type-aware unsafe narrowing, and declaration scope. Cover authored documentation contexts for TypeScript wrappers, overloads, CommonJS exports, and bodyless return contracts. Keep inherited parameter-only settings outside these tests.

Passed locally:

• bun run lint: zero errors/warnings, including explicit checks of eslint.config.ts and eslint-rules.ts
• bun run check-types
• bun run format:check, plus authored skill/reference Markdown checks
• bun run imports:check: 8 imports
• bun run build and bun run check: 5 plugins, 608 files
• bun test: 14 pass, zero failures
• bun run publish:marketplace -- --dry-run: no refs changed
• git diff --check

Additional evidence:

• All 35 owned code files have project service, real TypeScript programs, and source inclusion, including the lint config/rules.
• Effective JS/TS/CommonJS configs preserve the requested defaults, severities, replacements, native source types, and Stylistic coverage.
• Style reference, AGENTS, and review instructions pass the imported STE structural checker without disabled checks or a baseline allowance. The check covers structure, without lexical dictionary certification.
• Both client packages contain the final guide and byte-identical policy files. Imported ASD description and resources match upstream.
• jscpd 5.4.1 MCP initialization, tool discovery, and Type-1/2/3 refresh succeed.
• Full-source review finds 0 exact clones, no remaining actionable normalized/near-miss matches, and no substantiated added dead code. Reviewers checked static candidates against callers, test use, and entry points. Consolidate one introduced Git-fixture duplicate.

Generated output remains ignored. Marketplace publication uses the normal workflow on main. Distribution snapshots stay outside the source branch.

Final source commit: f42459496c940893860e382b0ff79277d1e88658. Exact-commit CI passed, including native Codex installation. Independent policy, whole-guide, rationale, and packaging reviews are CLEAR. Astra re-read every rule sequentially after the corrections and found no remaining actionable issue.

Merged into main as 6317f47. Post-merge CI and publication passed. All five plugins installed in Codex. Published snapshot dafcf37 is parentless. Both published client packages contain byte-identical copies of the three policy files and the guide.