@techninja/clearstack 0.3.11 → 0.3.12

package/docs/CONVENTIONS.md

@@ -267,6 +267,25 @@ This prevents premature extraction while keeping the eventual split obvious.
 function moveObj(o, dx, dy) { ... }
 ```
 
+### When a File Exceeds 150 Lines
+
+The **only correct response** is to split the file into two or more files.
+Never do any of the following to reduce line count:
+
+- Remove or shorten JSDoc comments
+- Collapse multi-line expressions onto one line
+- Remove blank lines between logical sections
+- Combine unrelated functions into one
+- Delete code that is still needed
+
+These make the code harder to read, which defeats the purpose of the limit.
+The limit exists to force decomposition, not compression.
+
+The spec checker runs formatters (Prettier, ESLint `--fix`) **before**
+counting lines, so the line count always reflects the formatted result.
+Write code in its natural readable form, run `npm run spec all`, and if
+a file is over the limit, split it.
+
 ---
 
 ## npm Scripts: One Entry Point Per Domain
@@ -328,6 +347,53 @@ multiple keys.
 Spec is the inner dev loop — run it constantly. Tests are the commit gate —
 run them before pushing. CI runs both, in parallel.
 
+### Spec Output Contract
+
+The spec checker is designed for **minimal, complete output**. Every check
+prints exactly one line: ✅ on pass, ❌ on fail with the violating file and
+reason. The final summary is 2 lines (`N/N checks passed`).
+
+Total output for a passing run is ~12 lines. A failing run adds one line
+per violation with the exact file path and what to fix.
+
+**Do not pipe, grep, tail, or filter spec output.** It is already the
+minimal actionable result. Filtering it discards the violation details
+that tell you which file to fix, forcing redundant re-runs.
+
+To narrow scope, run a targeted check instead of filtering `all`:
+
+```bash
+# Run everything
+npm run spec all
+
+# Run one check by key
+npm run spec code          # line counts (code files ≤150)
+npm run spec docs          # line counts (doc files ≤500)
+npm run spec imports       # import map aliases (no ../)
+npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec audit         # security audit
+
+# Parent keys run all children
+npm run spec lint           # ESLint + Stylelint + Markdown lint
+npm run spec format         # Prettier (all formatters)
+
+# Child keys run one
+npm run spec lint es        # ESLint only
+npm run spec lint css       # Stylelint only
+npm run spec lint md        # Markdown lint only
+npm run spec format prettier
+```
+
+```bash
+# ❌ Wrong — discards violation file paths
+npm run spec all 2>&1 | tail -3
+npm run spec all 2>&1 | grep -E "pass|fail"
+```
+
+This matters especially for LLM-assisted development: the spec output is
+structured so an LLM can read it in one pass, identify the failing file,
+and fix it without re-running the check. Filtering breaks that loop.
+
 ---
 
 ## Session Retrospective

package/lib/check.js

@@ -69,12 +69,6 @@ export function buildChecks(dir, cfg, cmds) {
   const css = () => countFiles(dir, ['.css'], cfg.ignore);
   const md = () => countFiles(dir, ['.md'], cfg.ignore);
   return [
-    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`) },
-    { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
-      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`) },
-    { key: 'imports', name: 'Import map aliases (no ../ imports)',
-      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)') },
     { key: 'es', name: 'ESLint', parent: 'lint',
       run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`) },
     { key: 'css', name: 'Stylelint', parent: 'lint',
@@ -83,6 +77,12 @@ export function buildChecks(dir, cfg, cmds) {
       run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`) },
     { key: 'prettier', name: 'Prettier', parent: 'format',
       run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`) },
+    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
+      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`) },
+    { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
+      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`) },
+    { key: 'imports', name: 'Import map aliases (no ../ imports)',
+      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)') },
     { key: 'types', name: 'JSDoc types (tsc --checkJs)',
       run: () => runCmd('JSDoc types', cmds.types, dir, `${js()} files`) },
     { key: 'audit', name: 'Security audit',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/docs/clearstack/CONVENTIONS.md

@@ -267,6 +267,25 @@ This prevents premature extraction while keeping the eventual split obvious.
 function moveObj(o, dx, dy) { ... }
 ```
 
+### When a File Exceeds 150 Lines
+
+The **only correct response** is to split the file into two or more files.
+Never do any of the following to reduce line count:
+
+- Remove or shorten JSDoc comments
+- Collapse multi-line expressions onto one line
+- Remove blank lines between logical sections
+- Combine unrelated functions into one
+- Delete code that is still needed
+
+These make the code harder to read, which defeats the purpose of the limit.
+The limit exists to force decomposition, not compression.
+
+The spec checker runs formatters (Prettier, ESLint `--fix`) **before**
+counting lines, so the line count always reflects the formatted result.
+Write code in its natural readable form, run `npm run spec all`, and if
+a file is over the limit, split it.
+
 ---
 
 ## npm Scripts: One Entry Point Per Domain
@@ -328,6 +347,53 @@ multiple keys.
 Spec is the inner dev loop — run it constantly. Tests are the commit gate —
 run them before pushing. CI runs both, in parallel.
 
+### Spec Output Contract
+
+The spec checker is designed for **minimal, complete output**. Every check
+prints exactly one line: ✅ on pass, ❌ on fail with the violating file and
+reason. The final summary is 2 lines (`N/N checks passed`).
+
+Total output for a passing run is ~12 lines. A failing run adds one line
+per violation with the exact file path and what to fix.
+
+**Do not pipe, grep, tail, or filter spec output.** It is already the
+minimal actionable result. Filtering it discards the violation details
+that tell you which file to fix, forcing redundant re-runs.
+
+To narrow scope, run a targeted check instead of filtering `all`:
+
+```bash
+# Run everything
+npm run spec all
+
+# Run one check by key
+npm run spec code          # line counts (code files ≤150)
+npm run spec docs          # line counts (doc files ≤500)
+npm run spec imports       # import map aliases (no ../)
+npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec audit         # security audit
+
+# Parent keys run all children
+npm run spec lint           # ESLint + Stylelint + Markdown lint
+npm run spec format         # Prettier (all formatters)
+
+# Child keys run one
+npm run spec lint es        # ESLint only
+npm run spec lint css       # Stylelint only
+npm run spec lint md        # Markdown lint only
+npm run spec format prettier
+```
+
+```bash
+# ❌ Wrong — discards violation file paths
+npm run spec all 2>&1 | tail -3
+npm run spec all 2>&1 | grep -E "pass|fail"
+```
+
+This matters especially for LLM-assisted development: the spec output is
+structured so an LLM can read it in one pass, identify the failing file,
+and fix it without re-running the check. Filtering breaks that loop.
+
 ---
 
 ## Session Retrospective