@leing2021/super-pi 0.31.0 → 0.32.0

package/README.md

@@ -190,9 +190,9 @@ Commit everything to git — these files are the project's traceable memory.
 | Tools | 12 CE + 10 Pi built-in |
 | Rules | 78 |
 | TypeScript lines | ~4,100 |
-| Tests | 180 (727 assertions) |
+| Tests | 219 (882 assertions) |
 
-Rules in `rules/` cover 11 common topics + language-specific sets (TypeScript, Rust, Go, Python, Java, Kotlin, C++, C#, Dart, Swift, Perl, PHP). Project-level overrides take priority.
+Rules in `rules/` cover 12 common topics + language-specific sets (TypeScript, Rust, Go, Python, Java, Kotlin, C++, C#, Dart, Swift, Perl, PHP). Project-level overrides take priority; projects can also add new languages via a project-level `rules/language-detection.md` marker map (append + same-marker wins).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",

package/rules/README.md

@@ -17,34 +17,24 @@ rules/
 ├── typescript/      # TypeScript/JavaScript specific
 ├── python/          # Python specific
 ├── golang/          # Go specific
-├── web/             # Web and frontend specific
+├── rust/            # Rust specific
+├── java/            # Java specific
+├── kotlin/          # Kotlin specific
 ├── swift/           # Swift specific
-└── php/             # PHP specific
+├── csharp/          # C# specific
+├── cpp/             # C++ specific
+├── dart/            # Dart specific
+├── php/             # PHP specific
+├── perl/            # Perl specific
+└── web/             # Web and frontend specific
 ```
 
 - **common/** contains universal principles — no language-specific code examples.
 - **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart.
-- **`review-checklist.md`** (optional, per language) holds precise, actionable defect patterns for code review — distinct from `patterns.md` which holds reusable design patterns. Currently used by `golang/` and `python/`.
+- **`review-checklist.md`** (optional, per language) holds precise, actionable defect patterns for code review — distinct from `patterns.md` which holds reusable design patterns. Currently used by `golang/`, `python/`, and `typescript/`.
 
 ## Installation
 
-### Option 1: Install Script (Recommended)
-
-```bash
-# Install common + one or more language-specific rule sets
-./install.sh typescript
-./install.sh python
-./install.sh golang
-./install.sh web
-./install.sh swift
-./install.sh php
-
-# Install multiple languages at once
-./install.sh typescript python
-```
-
-### Option 2: Manual Installation
-
 > **Important:** Copy entire directories — do NOT flatten with `/*`.
 > Common and language-specific directories contain files with the same names.
 > Flattening them into one directory causes language-specific files to overwrite
@@ -75,7 +65,7 @@ Language-specific rule files reference relevant skills where appropriate. Rules
 
 ## Adding a New Language
 
-To add support for a new language (e.g., `rust/`):
+To add support for a new language (e.g., `zig/`):
 
 1. Create a `rules/rust/` directory
 2. Add files that extend the common rules:
@@ -93,6 +83,8 @@ To add support for a new language (e.g., `rust/`):
 
 For non-language domains like `web/`, follow the same layered pattern when there is enough reusable domain-specific guidance to justify a standalone ruleset.
 
+End users of this package do not need to modify it to support a new language: create a project-level `{repo-root}/rules/<lang>/` directory and a marker row in `{repo-root}/rules/language-detection.md` — see "Project-level extensions" in `skills/references/language-detection.md`.
+
 ## Rule Priority
 
 When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).

package/rules/typescript/review-checklist.md

@@ -0,0 +1,80 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+---
+# TypeScript Review Checklist
+
+> TypeScript/JavaScript-specific defect patterns for code review. Used together with [common/code-review.md](../common/code-review.md).
+> **Precision over recall:** only raise an issue when confident it is a real defect. Stay silent when surrounding context is unclear. Treat security/correctness as blocking; style/idiom as non-blocking.
+
+## Null and Undefined Handling
+
+- Optional chaining missing where a value can legitimately be `null`/`undefined`: `obj.prop.deep` crashing when `obj.prop` is optional. Use `obj?.prop` or an explicit guard.
+- Non-null assertion (`!`) used to silence the compiler without evidence the value exists — every `!` must rest on a proven invariant (checked above, or constructed non-null).
+- Array access `arr[i]` assumed defined when the index can be out of bounds or the array empty (`noUncheckedIndexedAccess` reveals these; without it, check length first).
+- `value ?? fallback` vs `value || fallback` confusion: `||` also swallows `0`, `""`, `false`. Do not report when the falsy values are intended to fall through.
+
+## Type Safety
+
+- `any` leaking through a public API boundary (parameter, return type, or generic default) instead of `unknown` + narrowing.
+- Unsafe assertions (`as Foo`) on data crossing a trust boundary (`JSON.parse`, `fetch`, user input) without a runtime validation step.
+- Type assertions that claim more than they prove: `x as Foo` followed by unconditional `x.bar` access.
+- Object spread of optional sources (`{...defaults, ...partial}`) when `partial` may contain explicit `undefined` values that override defaults; merge field-by-field when the distinction matters.
+- Do not report `any` in test fixtures, or in third-party type shims the project has accepted.
+
+## Async and Promise Handling
+
+- Floating promises: promise created without `await`, `.then`, `.catch`, or `void` — rejections vanish silently. Especially fire-and-forget `async` calls in event handlers.
+- `async` functions without any `await` — callers may not expect a promise; drop `async` or await inside.
+- Sequential `await` in a loop over independent operations where `Promise.all` (or `allSettled` when partial failure is acceptable) is correct — confirm independence before flagging.
+- `Promise.all` on operations where one rejection should not cancel the rest; `Promise.allSettled` is the right tool.
+- `forEach` with an `async` callback — it does not wait; use `for...of` + `await`, or `Promise.all(map(...))`.
+- Missing `try/catch` (or `.catch`) around awaited calls whose rejection is a realistic user-visible failure mode.
+- Do not report when an upstream caller demonstrably handles the rejection, or the runtime treats unhandled rejections as fatal.
+
+## Error Handling
+
+- Empty `catch {}` that swallows errors without logging or re-raising.
+- `catch` blocks that lose the original error; wrap with `new Error(msg, { cause: e })` or a typed error class instead.
+- Broad `try` wrapping many statements where only one line can throw, hiding the real failure point.
+- Errors converted to sentinel values (`return null` / `-1`) without the caller checking; prefer throwing or a result type.
+- Do not report re-throws at top-level CLI handlers or framework-managed boundaries (Express error middleware, React error boundaries).
+
+## Equality and Value Semantics
+
+- `NaN` compared with `===`/`==` (always false); use `Number.isNaN`.
+- Loose `==` against non-null literals (except the idiomatic `x == null` covering both null and undefined).
+- Object/array compared with `===` where value equality was intended.
+- `Object.is` semantics surprising at `0`/`-0` and `NaN` — flag only when those values are realistic.
+
+## Resource Management
+
+- Event listeners, timers (`setInterval`/`setTimeout`), subscriptions, or observers added without removal on teardown/dispose paths.
+- Missing `AbortController` on long-lived fetches that can be cancelled (unmount, navigation, shutdown).
+- DB connections / file handles opened without `finally` cleanup or an owning pool.
+- Do not report short-lived scripts, or teardown already managed by a framework lifecycle.
+
+## Concurrency and Shared State
+
+Only flag with evidence of concurrent access (confirm via `code_search`):
+- Module-level mutable state (singletons, caches, module-scoped arrays) mutated across requests or sessions.
+- Check-then-act on shared state without synchronization; React stale-closure writes (`setX(x + 1)` in async callbacks) where `setX(v => v + 1)` is required.
+- `await` gaps between read and write of shared in-memory state.
+- Do not report single-threaded local variables or immutable data.
+
+## Performance
+
+Confirm hot path and data scale before flagging:
+- Spread-in-loop `O(n²)` accumulation (`arr = [...arr, item]`); accumulate into a local array instead.
+- Repeated expensive computation without memoization when inputs are stable and the call is hot.
+- `.filter().map()` double pass where a single loop or `.reduce` is clearer and faster.
+- Synchronous heavy work (`JSON.parse` of large payloads, `fs.readFileSync`) on request paths; move async.
+- Do not report micro-optimizations in cold paths, or code the project has profiled and accepted.
+
+## Not for this rule
+
+- Do not report style issues the formatter/linter (`prettier`, `eslint`, `tsc --strict`) already catches, unless the diff shows a concrete user-visible consequence those tools miss.
+- Do not report missing types in `.d.ts` shims, or `// @ts-expect-error` sites that are deliberate and localized.
+- Do not report dead code intentionally kept for future use.

package/skills/03-work/SKILL.md

@@ -11,11 +11,7 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-1. Load project rules (4 steps):
-   - Load `rules/common/development-workflow.md` and `rules/common/testing.md`
-   - Detect project language via [language detection](../references/language-detection.md)
-   - Load matching language-specific rules
-   - If frontend/browser concerns, also load `rules/web/` files
+1. Load project rules before writing any code: detect language via repo markers (map in Workflow step 2), then load `rules/common/development-workflow.md`, `rules/common/testing.md`, matching `rules/{lang}/` files, plus `rules/web/` for frontend/browser concerns. Emit a `Rules loaded:` manifest — **no manifest, no implementation**
 2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
 3. **Distinguish input:** plan path vs bare prompt
 4. Derive tasks from plan **implementation units**
@@ -79,19 +75,24 @@ If the same tool, command, or implementation unit fails 3 consecutive times, sto
 
 ## Workflow
 
-1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point. If not found, proceed normally. Read `CONTEXT.md` if it exists at root — see `../references/domain-language.md`.
-2. Detect input type (plan path vs bare prompt)
-3. Read implementation units if plan path
-4. Load `session_checkpoint` to skip completed units
-5. Use `task_splitter` for dependency analysis
-6. Execute: **inline mode** — all units run in the current session
-7. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
-8. **Source-driven gate:** Before implementing framework/library-specific code, verify the API or pattern against official documentation. Flag unverified patterns as UNVERIFIED in output.
-9. Record progress via `references/progress-update-format.md`
-9. Save `session_checkpoint` after each unit
-10. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
-11. Provide completion report (see `references/completion-report.md`)
-12. **Save handoff**: `context_handoff save` with current stage, next stage, activeFiles, blocker, verification, activeRules
-13. Handoff to `04-review` using `references/handoff.md`
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point; `activeRules` may already list loaded rules — verify against the repo, do not blindly trust. If not found, proceed normally. Read `CONTEXT.md` if it exists at root — see `../references/domain-language.md`.
+2. **Load project rules** (blocking — no implementation before this completes):
+   - Detect language: merge `{repo-root}/rules/language-detection.md` (project-level map, same marker wins) with the built-in table: `tsconfig.json`/`package.json`→typescript, `Cargo.toml`→rust, `go.mod`→golang, `pyproject.toml`/`requirements.txt`→python, `pom.xml`/`build.gradle(.kts)`→java/kotlin; others in [language detection](../references/language-detection.md)
+   - Check `{repo-root}/rules/` first (overrides package defaults); then load `rules/common/development-workflow.md`, `rules/common/testing.md`, matching `rules/{lang}/` files, `rules/web/` only for frontend/browser concerns
+   - Emit manifest before any code: `Rules loaded: language=<lang> (via <marker>[, project-level map]), common=<files>, lang=<files>, web=<files or N/A>`
+   - **Same-session re-entry:** if the transcript already contains a `Rules loaded:` manifest for the same language, do not re-read the rule files — reuse them, cite the earlier manifest, and note the skip
+3. Detect input type (plan path vs bare prompt)
+4. Read implementation units if plan path
+5. Load `session_checkpoint` to skip completed units
+6. Use `task_splitter` for dependency analysis
+7. Execute: **inline mode** — all units run in the current session
+8. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
+9. **Source-driven gate:** Before implementing framework/library-specific code, verify the API or pattern against official documentation. Flag unverified patterns as UNVERIFIED in output.
+10. Record progress via `references/progress-update-format.md`
+11. Save `session_checkpoint` after each unit
+12. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
+13. Provide completion report (see `references/completion-report.md`) — include the `Rules applied` section
+14. **Save handoff**: `context_handoff save` with current stage, next stage, activeFiles, blocker, verification, activeRules (carry loaded rules in `activeRules`)
+15. Handoff to `04-review` using `references/handoff.md`
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/03-work/references/completion-report.md

@@ -18,6 +18,12 @@ Brief description of what was completed.
 - Created: `path/to/file`
 - Modified: `path/to/file`
 
+## Rules applied
+
+| Language | Rule files | Detected via |
+|---|---|---|
+| typescript | `rules/typescript/coding-style.md`, `rules/typescript/testing.md` | `tsconfig.json` |
+
 ## Commands run
 
 | Command | Result |
@@ -44,6 +50,7 @@ All tests pass. Build succeeds. No regressions.
 
 **Completed:** list of unit names
 **Files changed:** all created/modified files
+**Rules applied:** language + rule files loaded
 **Commands run:** all verification commands
 **Verification:** pass/fail status for each
 

package/skills/04-review/SKILL.md

@@ -11,11 +11,7 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 
 ## Core rules
 
-1. Load project rules (4 steps):
-   - Load `../../rules/common/code-review.md` and `../../rules/common/code-smells.md`
-   - Detect language from changed files via [language detection](../references/language-detection.md)
-   - Load matching language-specific rules (e.g., `rules/typescript/`)
-   - If frontend/browser changes, also load `rules/web/` files
+1. Load project rules before producing findings (detailed in Workflow step 3): load `../../rules/common/code-review.md` + `code-smells.md`, detect language from changed files, load matching `rules/{lang}/` files including `review-checklist.md` (mark `missing (fell back to common)` when absent), plus `rules/web/` for frontend/browser changes. Emit a `Rules loaded:` manifest — **no manifest, no findings**
 2. **Priority:** project-level `{repo-root}/rules/` overrides package defaults
 3. **Standards axis baseline:** apply [`../../rules/common/code-smells.md`](../../rules/common/code-smells.md) (Fowler smell baseline). Two binding rules: a documented repo standard overrides the baseline; every smell is a judgement call (report as "possible Feature Envy"), never a hard violation. Map severity via P0/P1/P2 — default P2, escalate when a repo doc endorses it or it harms data flow/testability.
 4. Determine **diff scope** before selecting reviewers
@@ -60,13 +56,18 @@ Code review is **technical evaluation**, not social performance:
 
 1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `artifacts.plan` as starting point. If not found, proceed normally. Read `CONTEXT.md` if it exists at root — see `../references/domain-language.md`.
 2. Determine diff scope — prefer `branch`/`base` from latest handoff if present; else from explicit target; else ask user
-3. Collect stats (files, insertions, deletions) → call `review_router`
-4. Read matching plan artifact; if absent, follow [`references/spec-source-detection.md`](references/spec-source-detection.md) to probe brainstorm and commit issue refs
-5. Run solution search
-6. Apply each reviewer persona from `review_router`
-7. Merge into structured findings
-8. Verify each finding against codebase
-9. Apply autofixes, re-run tests, re-review if needed
+3. **Load project rules** (blocking — no findings before this completes):
+   - Detect language from changed files (`.ts`/`.tsx`→typescript, `.py`→python, `.go`→golang, `.rs`→rust, `.java`→java) or repo markers, merging `{repo-root}/rules/language-detection.md` (project-level map, same marker wins); full map in [language detection](../references/language-detection.md). Mixed-language diffs: load per language
+   - Check `{repo-root}/rules/` first (overrides package defaults); load `rules/common/code-review.md`, `code-smells.md`, matching `rules/{lang}/` files including `review-checklist.md`, `rules/web/` for frontend/browser changes
+   - Emit manifest before any finding: `Rules loaded: language=<lang> (via <files/markers>[, project-level map]), common=<files>, lang=<files>, web=<files or N/A>`
+   - **Same-session re-entry:** if the transcript already contains a `Rules loaded:` manifest for the same language, do not re-read the rule files — reuse them, cite the earlier manifest, and note the skip
+4. Collect stats (files, insertions, deletions) → call `review_router`
+5. Read matching plan artifact; if absent, follow [`references/spec-source-detection.md`](references/spec-source-detection.md) to probe brainstorm and commit issue refs
+6. Run solution search
+7. Apply each reviewer persona from `review_router`
+8. Merge into structured findings — include `rules applied` in the review summary (see `references/findings-schema.md`)
+9. Verify each finding against codebase
+10. Apply autofixes, re-run tests, re-review if needed
 
 ## Optional: QA Test Mode
 

package/skills/04-review/references/findings-schema.md

@@ -15,3 +15,11 @@ Optional fields:
 - `autofixable` — whether this finding can be automatically fixed
 - `autofix applied` — whether the autofix was applied
 - `autofix summary` — description of what was changed
+
+## Review summary block
+
+End every review with a summary that includes:
+
+- `rules applied` — language + rule files actually loaded for this review (mirror of the `Rules loaded:` manifest)
+- findings count by severity: `high / moderate / low`
+- verification status of confirmed findings (fixed / pushed back / deferred)

package/skills/references/language-detection.md

@@ -26,6 +26,18 @@ Rules are loaded from two locations with priority:
 
 Check project-level first. If a file exists there for the topic, use it. Otherwise fall back to package-level.
 
+## Project-level extensions
+
+A repo can extend the built-in marker table at the top of this file by creating `{repo-root}/rules/language-detection.md` with additional rows in the same table format (`File(s)` | `Language` | `Rules directory`). Use it when your project uses a language that is not in the built-in table.
+
+Merge semantics (applied before detection):
+
+- **Append:** project-level rows add new languages on top of the built-in table.
+- **Same marker → project-level wins:** if a marker file appears in both tables, the project-level row replaces the built-in one.
+- **Fall back:** if the project-level file is missing, empty, or a row is malformed, the built-in table applies — behavior never changes silently. A row pointing at a rules directory that does not exist is detected as the language but surfaces as `lang: missing` in the `Rules loaded:` manifest.
+
+The `Rules loaded:` manifest must state the mapping source, e.g. `language=zig (via build.zig, project-level map)` so a broken project-level row is visible in output.
+
 ## Rule precedence
 
 ```

package/skills/references/pipeline-config.md

@@ -85,6 +85,16 @@ Next step mapping:
 - `04-review` → `/skill:05-learn`
 - `05-learn` → `Completed`
 
+## End of skill: completion checklist
+
+Before declaring a stage complete, verify every item. A failed item means not done — fix it or stop and report:
+
+1. **Rules loaded and listed** — for stages whose workflow includes a rules-loading step (02-plan, 03-work, 04-review), session output contains a `Rules loaded:` manifest (language + rule files). If missing, load the rules now before finishing.
+2. **All workflow steps executed** — every numbered step in the stage's SKILL.md ran, or was explicitly skipped with a stated reason.
+3. **Artifacts saved** — plan / checkpoint / findings / handoff written to their artifact paths.
+4. **Verification evidence recorded** — exact command plus result in output, not a claim of success.
+5. **Pipeline Status + Context Status blocks output** — both present, real values, no placeholders.
+
 ### Handoff-lite template
 
 When a stage produces or updates handoff-lite, use this evidence-first structure and keep it concise (target <= 1500 tokens):