@softspark/ai-toolkit 2.11.0 → 2.12.0

package/app/skills/swift-patterns/SKILL.md

@@ -280,113 +280,7 @@ func testLoginFlow() {
 
 ## Common Frameworks
 
-### SwiftUI + @Observable (iOS 17+)
-
-```swift
-@Observable
-final class UserViewModel {
-    var users: [User] = []
-    var isLoading = false
-    private let service: UserService
-
-    init(service: UserService) { self.service = service }
-
-    func load() async {
-        isLoading = true
-        defer { isLoading = false }
-        users = (try? await service.fetchAll()) ?? []
-    }
-}
-
-struct UserListView: View {
-    @State private var vm: UserViewModel
-
-    init(service: UserService) {
-        _vm = State(initialValue: UserViewModel(service: service))
-    }
-
-    var body: some View {
-        NavigationStack {
-            List(vm.users) { user in
-                NavigationLink(value: user) { Text(user.name) }
-            }
-            .navigationTitle("Users")
-            .navigationDestination(for: User.self) { UserDetailView(user: $0) }
-            .task { await vm.load() }
-        }
-    }
-}
-```
-
-### Combine
-
-```swift
-class SearchVM: ObservableObject {
-    @Published var query = ""
-    @Published var results: [Item] = []
-    private var cancellables = Set<AnyCancellable>()
-
-    init(service: SearchService) {
-        $query
-            .debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
-            .removeDuplicates()
-            .filter { !$0.isEmpty }
-            .flatMap { service.search(query: $0) }
-            .receive(on: DispatchQueue.main)
-            .sink(receiveCompletion: { _ in },
-                  receiveValue: { [weak self] in self?.results = $0 })
-            .store(in: &cancellables)
-    }
-}
-```
-
-### Structured Concurrency
-
-```swift
-func fetchAllProfiles(ids: [String]) async throws -> [Profile] {
-    try await withThrowingTaskGroup(of: Profile.self) { group in
-        for id in ids { group.addTask { try await fetchProfile(id: id) } }
-        return try await group.reduce(into: []) { $0.append($1) }
-    }
-}
-
-// AsyncStream for bridging callbacks
-let locations = AsyncStream<Location> { continuation in
-    manager.onUpdate = { continuation.yield($0) }
-    continuation.onTermination = { _ in manager.stop() }
-}
-```
-
-### SwiftData
-
-```swift
-@Model
-final class Item {
-    var title: String
-    var timestamp: Date
-    @Relationship(deleteRule: .cascade) var tags: [Tag]
-    init(title: String) { self.title = title; self.timestamp = .now; self.tags = [] }
-}
-
-struct ItemListView: View {
-    @Query(sort: \Item.timestamp, order: .reverse) private var items: [Item]
-    @Environment(\.modelContext) private var context
-
-    var body: some View {
-        List(items) { Text($0.title) }
-    }
-}
-```
-
-### Vapor (Server-Side)
-
-```swift
-app.get("users", ":id") { req async throws -> User in
-    guard let id = req.parameters.get("id", as: UUID.self) else { throw Abort(.badRequest) }
-    guard let user = try await User.find(id, on: req.db) else { throw Abort(.notFound) }
-    return user
-}
-```
+For SwiftUI + `@Observable`, Combine, Structured Concurrency, SwiftData, and Vapor framework patterns with complete code examples, see [reference/frameworks.md](reference/frameworks.md).
 
 ---
 
@@ -498,3 +392,29 @@ Schemes: separate Debug/Release/Testing. Enable ASan + TSan in test schemes.
 | Blocking main thread | UI freezes | `async/await`, `Task { }` |
 | `UserDefaults` for secrets | Insecure | Keychain (`SecItemAdd`) |
 | `@ObservedObject` for owned state | Object recreated | `@StateObject` or `@State` + `@Observable` |
+
+## Rules
+
+- **MUST** use Swift concurrency primitives (`async/await`, actors, `Task`) for new code — GCD is legacy and mixes poorly with the new model
+- **MUST** annotate view models with `@MainActor` when they touch UI state — off-main mutations cause runtime warnings and flaky UI
+- **NEVER** force-unwrap (`!`) without a documented invariant in a comment; runtime crashes from unwrap are the top iOS crash category
+- **NEVER** store secrets in `UserDefaults` or plist — use Keychain APIs (`SecItemAdd`, `SecItemCopyMatching`)
+- **CRITICAL**: SwiftUI state flows downward; mutations flow through `@State`, `@Binding`, or `@Observable`. Never mutate a parent's state from a child via a captured reference — it breaks dependency tracking.
+- **MANDATORY**: every closure that captures `self` inside a reference type uses `[weak self]` or `[unowned self]` — retain cycles are the top memory-leak cause
+
+## Gotchas
+
+- `@StateObject` and `@ObservedObject` look similar but behave oppositely on parent re-render: `@StateObject` persists, `@ObservedObject` may re-initialize. Using `@ObservedObject` for view-owned state recreates the object on every render — state loss without error.
+- `Task { @MainActor in ... }` inside a non-`@MainActor` context does **not** synchronously return to main; it schedules. Code between the `await` and `Task` boundary runs on whatever actor you came from, which can race with UI updates.
+- `AsyncStream` continuations without `onTermination` leak: if the consumer cancels, the producer keeps yielding forever. Always install a termination handler.
+- SwiftData `@Query` with `@Environment(\.modelContext)` invalidates on every write; heavy reads in a watched view cause perf drops. Use `@FetchRequest`-style fetch descriptors with explicit refresh, not ambient `@Query`, for large datasets.
+- Combine's `.receive(on: DispatchQueue.main)` schedules asynchronously — if the next operator expects sync execution, order matters. Prefer moving `.receive(on:)` to just before the sink, not mid-pipeline.
+- Swift Concurrency does not compose cleanly with Objective-C completion handlers; `withCheckedContinuation` bridges but a continuation that is never resumed hangs the Task forever. Always pair resumes with all control-flow paths, including errors.
+
+## When NOT to Load
+
+- For **Flutter or React Native** cross-platform code — use `/flutter-patterns` or JS patterns; this skill is Swift-only
+- For generic iOS architecture decisions (MVC vs MVVM vs VIPER) — use `/architecture-decision`
+- For Kotlin-based cross-platform mobile (KMP) — use `/kotlin-patterns`
+- For mobile CI/CD specifics (TestFlight, Fastlane) — use `/ci-cd-patterns`
+- For Objective-C interop deep dives — outside scope; this skill focuses on modern Swift

package/app/skills/swift-patterns/reference/frameworks.md

@@ -0,0 +1,111 @@
+# Swift Framework Patterns
+
+Detailed patterns for SwiftUI, Combine, Structured Concurrency, SwiftData, and Vapor. Loaded on demand from `swift-patterns/SKILL.md`.
+
+## SwiftUI + @Observable (iOS 17+)
+
+```swift
+@Observable
+final class UserViewModel {
+    var users: [User] = []
+    var isLoading = false
+    private let service: UserService
+
+    init(service: UserService) { self.service = service }
+
+    func load() async {
+        isLoading = true
+        defer { isLoading = false }
+        users = (try? await service.fetchAll()) ?? []
+    }
+}
+
+struct UserListView: View {
+    @State private var vm: UserViewModel
+
+    init(service: UserService) {
+        _vm = State(initialValue: UserViewModel(service: service))
+    }
+
+    var body: some View {
+        NavigationStack {
+            List(vm.users) { user in
+                NavigationLink(value: user) { Text(user.name) }
+            }
+            .navigationTitle("Users")
+            .navigationDestination(for: User.self) { UserDetailView(user: $0) }
+            .task { await vm.load() }
+        }
+    }
+}
+```
+
+## Combine
+
+```swift
+class SearchVM: ObservableObject {
+    @Published var query = ""
+    @Published var results: [Item] = []
+    private var cancellables = Set<AnyCancellable>()
+
+    init(service: SearchService) {
+        $query
+            .debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
+            .removeDuplicates()
+            .filter { !$0.isEmpty }
+            .flatMap { service.search(query: $0) }
+            .receive(on: DispatchQueue.main)
+            .sink(receiveCompletion: { _ in },
+                  receiveValue: { [weak self] in self?.results = $0 })
+            .store(in: &cancellables)
+    }
+}
+```
+
+## Structured Concurrency
+
+```swift
+func fetchAllProfiles(ids: [String]) async throws -> [Profile] {
+    try await withThrowingTaskGroup(of: Profile.self) { group in
+        for id in ids { group.addTask { try await fetchProfile(id: id) } }
+        return try await group.reduce(into: []) { $0.append($1) }
+    }
+}
+
+// AsyncStream for bridging callbacks
+let locations = AsyncStream<Location> { continuation in
+    manager.onUpdate = { continuation.yield($0) }
+    continuation.onTermination = { _ in manager.stop() }
+}
+```
+
+## SwiftData
+
+```swift
+@Model
+final class Item {
+    var title: String
+    var timestamp: Date
+    @Relationship(deleteRule: .cascade) var tags: [Tag]
+    init(title: String) { self.title = title; self.timestamp = .now; self.tags = [] }
+}
+
+struct ItemListView: View {
+    @Query(sort: \Item.timestamp, order: .reverse) private var items: [Item]
+    @Environment(\.modelContext) private var context
+
+    var body: some View {
+        List(items) { Text($0.title) }
+    }
+}
+```
+
+## Vapor (Server-Side)
+
+```swift
+app.get("users", ":id") { req async throws -> User in
+    guard let id = req.parameters.get("id", as: UUID.self) else { throw Abort(.badRequest) }
+    guard let user = try await User.find(id, on: req.db) else { throw Abort(.notFound) }
+    return user
+}
+```

package/app/skills/test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test
-description: "Run tests with coverage analysis and reporting"
+description: "Run the project's test suite with coverage reporting, auto-detecting the framework (pytest, vitest, jest, flutter test, go test, cargo test, phpunit). Use when the user asks to run existing tests — not to author new ones test-first."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[file or pattern]"
@@ -105,3 +105,25 @@ tests/               # or test/, spec/, __tests__/
 ├── integration/     # Tests with external dependencies
 └── e2e/             # End-to-end tests
 ```
+
+## Rules
+
+- **MUST** detect the framework automatically via `detect-runner.py` — do not assume
+- **NEVER** modify tests to make them pass
+- **CRITICAL**: coverage reporting must use the project's configured tool (`--cov=src`, `--coverage`, etc.) — do not invent flags
+- **MANDATORY**: when a test fails, report the failure exactly; do not paraphrase
+
+## Gotchas
+
+- `pytest --cov=src` inflates coverage when `tests/` lives under `src/` — test files count toward covered lines. Either move `tests/` out, or use `--cov=src --cov-branch --cov-report=term-missing` with an explicit `[tool.coverage.run] omit = ["tests/*"]` in `pyproject.toml`.
+- `go test ./...` runs packages in parallel by default; a test depending on shared global state may pass alone and fail in the suite. If flakiness appears only under `./...`, suspect shared state, not a bug in the test.
+- `flutter test` without an emulator falls back to the headless "null platform" — widget tests that require a render surface are **silently skipped**. CI without a display must add `flutter test --platform vm` or a virtual framebuffer.
+- `vitest run` and `jest` interpret glob patterns differently: `*.test.ts` in vitest matches filenames, in jest matches paths. Passing the same CLI arg to both produces different test sets — use the framework-native config file when possible.
+- `pytest --lf` (last-failed) silently runs **all** tests if there is no cache from a prior run. First-time runs in CI therefore ignore `--lf` and re-run everything, which can hide "only failed tests" bugs in local runs.
+
+## When NOT to Use
+
+- To write new tests test-first — use `/tdd`
+- To author test design patterns — use `/testing-patterns` (knowledge skill)
+- To debug a failing test — use `/debug` after `/test` surfaces the failure
+- For performance/load testing — use dedicated tooling, not `/test`

package/app/skills/testing-patterns/SKILL.md

@@ -82,3 +82,29 @@ For Flutter/Dart testing patterns, see [reference/flutter-testing.md](reference/
 | "We'll add tests later" | Untested code accumulates — later means never, and coverage gaps compound |
 | "Mocking everything is fine" | Over-mocking tests the mocks, not the code — mock at boundaries only |
 | "100% coverage means no bugs" | Coverage measures execution, not correctness — focus on behavior assertions |
+
+## Rules
+
+- **MUST** follow Arrange-Act-Assert (AAA) structure in every test — unstructured tests degrade into procedural smoke tests
+- **MUST** test behavior through the public interface, not internal implementation — tests coupled to internals break on every refactor
+- **NEVER** test implementation details (private method return values, internal state flags) — they are not the contract
+- **NEVER** hit real external services in unit tests — use fakes/stubs for boundaries; save real integration for integration tests
+- **CRITICAL**: integration tests must hit real dependencies (database, message queue, external API) when mock-vs-prod divergence is a real risk. Mocked integration tests create false confidence.
+- **MANDATORY**: flaky tests are bugs, not noise. Quarantine or delete them — a tolerated flaky test erodes the suite's credibility.
+
+## Gotchas
+
+- Coverage numbers are easy to game: include generated code, test files that import but do not assert, or wide `# pragma: no cover` usage. A 95% reported coverage with 60% real behavior assertion is common.
+- Snapshot tests (Jest `.toMatchSnapshot()`, pytest-regressions) accept any output as "correct" on first run. An incorrect initial snapshot becomes the accepted baseline — review snapshots as carefully as code.
+- Mocks configured with `any` matchers (e.g., `.mock.calls[0][0]` without a schema) pass even when the production call shape changes. Assert on specific arguments, not just "was called".
+- Test isolation fails when globals leak (module-level mutable state, module-scoped fixtures, env vars set in one test). Flakiness that appears only under `pytest -n auto` or `jest --parallel` is usually shared state.
+- Property-based tests (Hypothesis, fast-check) shrink failing examples to minimal reproducers, but shrinking time can dominate the run. For complex generators, cap shrink deadlines or seed the failing example for next-run reproducibility.
+- Test pyramid vs trophy: the "right" ratio depends on stack. Frontend apps with rendering concerns benefit from more integration tests (trophy); pure backend services align better with pyramid. Don't cargo-cult one model.
+
+## When NOT to Load
+
+- For **running** the test suite — use `/test`
+- For test-first development workflow — use `/tdd`
+- For debugging a specific test failure — use `/debug` on the failure output
+- For test framework choice in a new project — use `/app-builder`
+- For performance/load testing — this skill covers correctness tests, not load

package/app/skills/triage-issue/SKILL.md

@@ -114,7 +114,25 @@ Do NOT include file paths, line numbers, or implementation details. Describe mod
 
 ## Rules
 
-- Minimal user interaction — investigate autonomously
-- No file paths or line numbers in the issue (durability)
-- TDD plan uses vertical slices, not horizontal
-- File immediately — don't ask for review
+- **MUST** explore the codebase for root cause before filing — symptoms masquerade as causes often
+- **MUST** propose a TDD fix plan with ordered RED→GREEN cycles, each a vertical slice
+- **NEVER** ask follow-up clarifying questions; one initial question maximum, then investigate autonomously
+- **NEVER** include file paths, function names, or line numbers in the issue body — they go stale before the issue is picked up
+- **CRITICAL**: the issue must be reproducible. If reproduction steps cannot be determined from the investigation, say so explicitly in the Problem section — do not fabricate them.
+- **MANDATORY**: file the issue immediately via `gh issue create` and share the URL — do not ask the user to review a draft first
+
+## Gotchas
+
+- `gh issue create` without `--body` opens `$EDITOR`. In automated flows the skill hangs — always pass the body file or inline text.
+- "Root cause" often turns out to be two concurrent issues. If the investigation keeps branching, file the most-probable primary cause and note the secondary as a follow-up in the same issue.
+- TDD plans with more than ~5 RED→GREEN cycles usually conceal a deeper design issue. Short plans (2-3 cycles) reflect confident root-cause identification; long plans reflect fishing.
+- The `debugger` agent explored autonomously but returns a narrative. Parse it for: confirmed hypothesis, code paths, and recent changes. Discard speculation.
+- Bugs in framework-adjacent code (middleware, ORM hooks) require test setup that mirrors the framework's call context. A TDD plan that writes the test "like a unit test" may not actually reproduce the framework bug.
+
+## When NOT to Use
+
+- For a conversational bug report from a non-engineer — use `/qa-session` first, which returns refined reports this skill can then process
+- For a specific reproducible error with known root cause — use `/fix` directly
+- For architectural-scale problems — use `/architecture-audit`
+- For creating issues from a PRD — use `/prd-to-issues`
+- For debugging without filing an issue — use `/debug`

package/app/skills/ubiquitous-language/SKILL.md

@@ -64,11 +64,26 @@ Extract and formalize domain terminology into a consistent glossary.
 
 ## Rules
 
-- **Be opinionated** — pick the best term, list others as aliases to avoid
-- **Flag conflicts explicitly** — call out ambiguous usage with clear recommendations
-- **Domain terms only** — skip generic programming concepts (array, function, endpoint)
-- **Tight definitions** — one sentence max, define what it IS not what it does
-- **Show relationships** — bold term names, express cardinality
-- **Group naturally** — multiple tables when clusters emerge, one table if cohesive
-- **Example dialogue** — 3-5 exchanges showing terms used precisely
-- **Keep existing** — when re-running, read existing file and update incrementally
+- **MUST** be opinionated — pick the best term and list alternatives as aliases to avoid
+- **MUST** flag every ambiguity (one word → two concepts) and every synonym (two words → one concept) with an explicit recommendation
+- **MUST** write tight definitions (one sentence) that define what the term **is**, not what it does
+- **NEVER** include generic programming concepts (array, function, endpoint, class) — this glossary is for the **domain**, not the toolchain
+- **NEVER** silently overwrite an existing `UBIQUITOUS_LANGUAGE.md` — read the current file first, then update incrementally preserving prior decisions
+- **CRITICAL**: show relationships with cardinality ("an Order belongs to exactly one Customer"). Vocabulary without relationships is a word list, not a language.
+- **MANDATORY**: include 3-5 example dialogue exchanges showing correct usage. Abstract glossaries without dialogue rarely get adopted.
+
+## Gotchas
+
+- Domain terms often **overlap** with framework jargon (e.g., "Service" in DDD vs "Service" in Angular). If the framework already claims a term, prefer a domain-specific alternative to avoid collision.
+- Stakeholders resist terminology change even when their current terms are ambiguous. "Account" replacing "User" triggers more discussion than expected — plan for negotiation in the example dialogue section.
+- Glossaries rot when features ship without updating them. A `UBIQUITOUS_LANGUAGE.md` last updated 6 months ago is a snapshot, not a source of truth. Flag staleness in the header and re-run this skill periodically.
+- Relationships between terms are easy to hand-wave with "related to". Pin down the cardinality (`0..1`, `1..*`, `1..1`) — vague relationships produce schema ambiguity later.
+- The opinionated canonical choice may contradict marketing or legal language. Note conflicts explicitly rather than hiding them; the domain model and the marketing site can legitimately diverge.
+
+## When NOT to Use
+
+- For writing a **PRD** (full requirements) — use `/write-a-prd`
+- For generating user-facing documentation — use `/docs`
+- For implementation planning — use `/plan` or `/prd-to-plan`
+- For enforcing language in commit messages or code reviews — use `/brand-voice` (distinct concern: writing style, not domain terms)
+- When the project is a single-developer throwaway — glossary overhead is not justified

package/kb/procedures/release-preparation-sop.md

@@ -3,10 +3,10 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif]
-version: "1.7.0"
+version: "1.8.0"
 created: "2026-04-10"
-last_updated: "2026-04-18"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0."
+last_updated: "2026-04-21"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, and the single-run npm test discipline added in v1.8.0."
 ---
 
 # SOP: Release Preparation
@@ -207,7 +207,13 @@ python3 scripts/validate.py --strict
 python3 scripts/audit_skills.py --ci
 python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS ingest
 python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
-npm test
+
+# Run npm test ONCE, cache output, parse from file. The suite is 669+ bats
+# cases — rerunning it per check wastes minutes. Do not pipe npm test into
+# tail/grep multiple times in the same session.
+npm test > /tmp/npm-test.log 2>&1
+tail -3 /tmp/npm-test.log
+echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
 ```
 
 **Expected results:**
@@ -215,7 +221,7 @@ npm test
 - `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
 - `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
 - `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
-- `npm test`: `1..N` with zero `not ok`
+- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
 
 **One-liner:**
 ```bash

package/kb/procedures/release-verification-sop.md

@@ -3,10 +3,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.2.0"
+version: "1.3.0"
 created: "2026-04-08"
-last_updated: "2026-04-18"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard."
+last_updated: "2026-04-21"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 adds the single-run npm test discipline (cache to file, parse ok/not-ok once)."
 ---
 
 # SOP: Release Verification
@@ -39,7 +39,7 @@ python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGEN
 python3 scripts/generate_codex_rules.py .                   # 2. Refresh standard Codex rules
 python3 scripts/generate_llms_txt.py > llms.txt             # 3. Regenerate llms.txt
 python3 scripts/validate.py --strict                        # 4. Validation passed?
-npm test                                                    # 5. All tests passed?
+npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 5. All tests passed? (single run, cached)
 
 # Post-install verification (Phases 1-7)
 ai-toolkit --version                                        # 6. Version OK?
@@ -204,15 +204,33 @@ python3 scripts/audit_skills.py --ci
 ## Phase 6: Tests (3-5 min)
 
 ```bash
-npm test
+# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
+# re-running it per check (tail / grep ok / grep not ok piped separately)
+# wastes minutes every release. Always cache the output.
+npm test > /tmp/npm-test.log 2>&1
+exit=$?
+tail -3 /tmp/npm-test.log
+echo "ok:     $(grep -c '^ok '    /tmp/npm-test.log)"
+echo "not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
+echo "exit:   $exit"
 ```
 
 **Verify:**
+- [ ] `exit == 0`
+- [ ] `ok == expected test count` (e.g., 669)
+- [ ] `not ok == 0`
 - [ ] Bats runs tests in parallel (4 jobs)
-- [ ] All `ok` — zero `not ok`
 - [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
       install, kb, mcp, readme, profiles, uninstall, validate
 
+**Anti-pattern — do NOT do this:**
+```bash
+# Runs the full suite THREE times. Adds 1-3 min and pressures CI capacity.
+npm test 2>&1 | tail -3
+npm test 2>&1 | grep -c '^ok '
+npm test 2>&1 | grep -c '^not ok'
+```
+
 **Key test areas:**
 - Guards: rm -rf, DROP TABLE, git push --force blocked
 - Install: idempotent, profiles, --only/--skip, orphan cleanup