@wrongstack/core 0.308.0 → 0.308.2

package/skills/tech-stack/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when validating package versions, checking for outdated dependencies,
   or evaluating third-party libraries in WrongStack. Triggers: user says "dependency",
   "package version", "outdated", "npm audit", "deprecated package", "tech stack".
-version: 1.2.0
+version: 1.3.0
 required-capabilities: [dependencies.manage]
 required-tools: []
 optional-capabilities: [web.research]
@@ -112,6 +112,30 @@ When APPROVED:
 </nextsteps>
 ```
 
+## Out of scope
+
+- **Don't trust version numbers from the model.** Training data is stale. The registry is the truth; fetch the latest version from the registry, not from memory.
+- **Don't recursively analyze transitive dependencies.** This skill is single-shot. 1–2 iterations: detect → search registry → verify → report. Deep dependency analysis is a different workflow.
+- **Don't greenlight prehistoric technology.** Anything superseded ≥5 years ago is rejected by default. Use the per-ecosystem built-in preference map.
+- **Don't add a third-party package when the standard library covers it.** Prefer built-in. Every modern runtime ships an obsoleting API; check the built-in map before greenlighting any dependency.
+- **Don't accept a dead package.** A package with no release in >2 years and unresolved critical issues is dead; suggest a maintained replacement. "Deprecated" / "yanked" / "archived" are the dead signals, not opinions.
+- **Don't pick a random ecosystem.** Detect from project files first; ask when multiple markers exist; default to JavaScript only when `package.json` is present and nothing else is.
+- **Don't deep-dive CVEs.** Known-CVE work is `security-scanner`'s lane. This skill validates existence, version, and deprecation — not vulnerability surface.
+- **Don't approve without a registry URL.** The reader needs to verify; cite the registry endpoint that was actually fetched.
+
+## Before returning
+
+- [ ] Ecosystem detected (explicit or via project file scan)
+- [ ] Registry endpoint fetched; package existence verified
+- [ ] Latest version pulled from the registry, not from training memory
+- [ ] Dead-package signals checked (`deprecated`, yanked, archived)
+- [ ] Prehistoric-tech check ran against the per-ecosystem preference map
+- [ ] Built-in vs. third-party preference map consulted
+- [ ] Status is APPROVED / REJECTED / NEEDS_INVESTIGATION with one-sentence verdict
+- [ ] On REJECTED, modern alternative named with a migration step
+- [ ] Registry URL cited so the reader can verify
+- [ ] No transitive dependency recursion; single-shot budget honored
+
 ## Skills in scope
 
 - `node-modern` — for Node.js built-in vs. third-party decisions

package/skills/testing/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when writing, reviewing, or improving tests in WrongStack.
   Triggers: user says "test", "unit test", "integration test", "e2e", "mock",
   "vitest", "coverage", "assert", "expect", "test strategy", "write tests".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: [filesystem.read, verification.run]
 required-tools: []
 optional-capabilities: [execution.shell]
@@ -165,6 +165,30 @@ coverageThreshold: {
 - **pnpm workspaces**: Run `pnpm test` in the package root, or `pnpm -r test` for all packages.
 - **Vitest config**: Each package has its own `vitest.config.ts`.
 
+## Out of scope
+
+- **Don't test internal modules.** Test the public API surface. Mocking `../src/internal/helper` couples the test to implementation; the moment the helper moves, the test breaks for the wrong reason.
+- **Don't commit test-only deps to `dependencies`.** Devs install `devDependencies`. Test-only deps in `dependencies` bloat the production install and can leak into runtime code.
+- **Don't lower the coverage gate to make tests pass.** New code carries its own ≥70% coverage; existing coverage never decreases. A passing test suite with sinking coverage is regression, not progress.
+- **Don't write async tests without a timeout.** `test(..., { timeout: 5000 })` is mandatory. A hang in CI is a worse failure than a flapping test.
+- **Don't mock `node:fs` and forget cleanup.** `vi.restoreAllMocks()` and `vi.useRealTimers()` in `afterEach` are mandatory. Mocks leaking across tests are how unit tests go red in a clean checkout.
+- **`setTimeout` is the wrong timeout primitive in tests.** `AbortSignal.timeout()` is the WrongStack convention. A timer, not a signal, bypasses the abort plumbing.
+- **Don't import from `dist/`.** Subpath exports are the entry point. `dist/` is build output; tests against it depend on the build having been run.
+- **Don't report a coverage percentage from a partial run.** Coverage is the full suite, not a subset. A 90% on 60% of the files is not 90%.
+
+## Before returning
+
+- [ ] Tests co-located: `src/foo.ts` → `tests/foo.test.ts` in the same package
+- [ ] Public API only; no internal-module mocks
+- [ ] Async tests carry an explicit timeout (`{ timeout: 5000 }` or appropriate)
+- [ ] `vi.restoreAllMocks()` and `vi.useRealTimers()` in `afterEach`
+- [ ] `AbortSignal.timeout()` used for timeouts, not `setTimeout`
+- [ ] No new `dependencies` entries for test-only packages
+- [ ] Coverage gate met: new code ≥70%, existing coverage not reduced
+- [ ] Coverage from full suite, not partial run
+- [ ] Failing tests pair with the code under test, not staged in a separate commit
+- [ ] `<nextsteps>` mirrors the open test gaps in priority order
+
 ## Skills in scope
 
 - `bug-hunter` — for turning test failures into concrete bugs

package/skills/typescript-strict/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when writing or reviewing TypeScript code with strict mode
   in WrongStack. Triggers: user mentions "TypeScript", "strict", "type error",
   "type safety", "narrowing", "branded type", "discriminated union", "noUncheckedIndexedAccess".
-version: 1.1.0
+version: 1.2.0
 required-capabilities: [filesystem.read, filesystem.write]
 required-tools: []
 optional-capabilities: [verification.run]
@@ -235,6 +235,35 @@ const len: number = str?.length ?? 0;
 console.log(name!.toUpperCase());
 ```
 
+## Out of scope
+
+- **Don't use `as any` or double assertions to silence errors.** Validate or narrow values at trust boundaries. A cast that hides a real type error is a bug surfaced later in runtime.
+- **Don't use `!` non-null assertion.** `name!.toUpperCase()` silences the type checker without explanation. Use a narrow check or an assertion function.
+- **`Function` and `Object` types are too broad.** They're `any`-shaped in disguise. Be specific.
+- **Don't return `Promise<any>`.** `Promise<unknown>` or a generic. `Promise<any>` loses the type information the caller needs.
+- **Don't omit return types on exported functions.** Without an explicit return type, exported functions hide errors and let callers assume any shape. Annotate public APIs.
+- **Don't use optional chaining chains to dodge narrowing.** `a?.b?.c?.d` is "I don't know what `a` is" with a costume. Verify with `if (a)` first.
+- **Don't loosen `noUncheckedIndexedAccess` to make tests pass.** It is the safety net. Once it's off, array access silently returns `T` instead of `T | undefined` and `undefined` slips through.
+- **Don't mix `enum` and union types.** Pick one per project. `enum` is the legacy form; const-asserted string unions are the modern form.
+- **Don't write code that compiles under `strict: false`.** WrongStack runs with `strict`, `noUncheckedIndexedAccess`, `noImplicitReturns`, and `exactOptionalPropertyTypes`. Code that only compiles under relaxed flags is the kind of debt this skill exists to prevent.
+- **Don't accept `unknown` without narrowing at the use site.** `unknown` is the safe top type; leaving it un-narrowed is a typed-any escape hatch.
+
+## Before returning
+
+- [ ] No `as any` or double assertions; validation/narrowing at boundaries
+- [ ] No `!` non-null assertion; narrow checks or assertion functions instead
+- [ ] No `Function` or `Object`; specific function/object types used
+- [ ] No `Promise<any>`; `Promise<unknown>` or generic
+- [ ] Exported functions carry explicit return types
+- [ ] `noUncheckedIndexedAccess` honored; `T | undefined` handled at every index access
+- [ ] `exactOptionalPropertyTypes` honored; `prop?: T` and `prop: T | undefined` distinguished
+- [ ] Discriminated unions used over optional fields where state is finite
+- [ ] `assertNever` in `default:` of exhaustive switches
+- [ ] Branded types for invariant strings (`UserId`, `SessionId`)
+- [ ] `strict`, `noUncheckedIndexedAccess`, `noImplicitReturns`, `exactOptionalPropertyTypes` in `tsconfig.json`
+- [ ] `pnpm run typecheck` passes before merge
+- [ ] `<nextsteps>` mirrors open follow-ups (cast removals, narrowing gaps, tsconfig tightening)
+
 ## Skills in scope
 
 - `node-modern` — for TypeScript + ESM patterns

package/skills/wrongstack-kanban/SKILL.md

@@ -6,6 +6,7 @@ description: |
   managed Backlog→Todo→Running→Review→Done lifecycle, lease-fenced dispatch,
   and what "verified" means before a card reaches Done.
 trigger: working with the kanban tool, managing project work through boards, or advancing a managed card's lifecycle
+version: 1.0.0
 required-capabilities: [work.plan]
 required-tools: [kanban]
 ---
@@ -127,6 +128,29 @@ filled in as it becomes known.
 | Omitting unfinished Todo/task/plan rows | Requirement identity and coverage would be lost |
 | Inventing subtasks for a leaf card | Recursive decomposition to satisfy process, not the work |
 
+## Out of scope
+
+- **Don't create a card for trivial work.** A quick read, a one-line fix, or a question does not need a card. Resume the existing card for the same request instead of creating a duplicate.
+- **Don't claim a task is done in chat without a board mutation.** Chat-only completion is fake progress. Persist via `kanban` actions; the board is the shared record.
+- **Don't skip lifecycle stages on a managed board.** Managed cards move exactly one stage at a time. The guard rejects jumps; trying to bypass it is a bug.
+- **Don't work an unclaimed card.** Another agent may be working it. Take `claim_task` first (via `kanban`), or let the Director's queue claim for you.
+- **Don't lose the lease.** Heartbeat before the lease expires. An expired lease is recovered by the supervisor and the card returns to the queue.
+- **Don't fence-less write.** Pass `expectedLeaseId` on every `mark_assignment` and `heartbeat_assignment`. If your lease was recovered, an unfenced write corrupts the successor's state.
+- **Don't invent children for a leaf card.** Atomic work is one childless leaf. Recursive decomposition to satisfy process is process for process's sake.
+- **Don't try to influence dispatch order.** Selection is deterministic by priority, column, order, and creation time. Shuffling tasks or boards doesn't change it.
+- **Don't block on Kanban persistence.** If a board write fails, say so and keep working. The board follows the work; the work does not wait on the board.
+
+## Before returning
+
+- [ ] Substantial work has a card with `description`, `assignee`, and `successCriteria` set
+- [ ] Card claimed via `claim_task` (or Director queue) before any work started
+- [ ] Lease heartbeated within the lease window
+- [ ] Every material action produced a board mutation (no chat-only claims of progress)
+- [ ] `mark_assignment` and `heartbeat_assignment` carried `expectedLeaseId`
+- [ ] Completion went through the verifier; "Done" means the verifier actually ran
+- [ ] Todo/task/plan rows preserve `kanbanBoardId` / `kanbanTaskId` bindings in full-list updates
+- [ ] Card count scaled to the size of the work; no invented subtasks
+
 ## Related skills
 
 - `sdd` — spec-driven development creates boards from task graphs

package/skills/wrongstack-mailbox/SKILL.md

@@ -8,7 +8,7 @@ description: |
   mailbox", "send to WrongStack", "wrongstack mail", "broadcast to the
   fleet", "tell the wrongstack agents", "is anyone online in
   wrongstack", or "register me with wrongstack".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: []
 required-tools: [mailbox]
 optional-capabilities: [mcp.dynamic, web.research]
@@ -738,6 +738,34 @@ mailbox serve` standalone all work. The first one to come up for a
 given project starts the bridge; subsequent surfaces join it via the
 per-project lock.
 
+## Out of scope
+
+- **Don't open Mailbox files directly.** No `_mailbox.sqlite`, no legacy JSONL, no bridge locks, no token files. The bridge and `mb()` / `mbWithBootstrap()` are the only paths; bypassing them breaks trust and audit.
+- **Don't impersonate `hq@...` or another agent.** Use a stable, honest `agentId` for your own identity. The bridge does not enforce sender identity; impersonation is on you, and it's the kind of thing that gets the bridge shut down.
+- **Don't hardcode the token.** Read it from `.mailbox.token`, `.mailbox-bridge.lock`, or accept it from the user. Re-read after a 401. Tokens rotate on every fresh bridge start.
+- **Don't let requests hang.** `AbortSignal.timeout(10_000)` is mandatory. The mailbox is local; 10 s is generous, and a hung bridge will wedge the agent.
+- **Don't poll faster than 1 Hz.** The bridge enforces 120 req/min/token. Polling at sub-second rates hits the limit and looks like a flooding attempt.
+- **Don't use SSE events as authoritative.** `GET /mailbox/events` is a wake-up hint, not a snapshot. After every event, reconcile through `/mailbox/query` or `/mailbox/check`.
+- **Don't broadcast without thinking.** `to: "*"` reaches every online agent. One broadcast per task, with a clear subject. The WebUI marks broadcasts with a different color and humans notice noise.
+- **Don't ack in a loop when `ack-many` fits.** If you have more than one unread message, use `/mailbox/ack-many` — one request, one lock, one rewrite.
+- **Don't skip `register_self`.** Without registration, the WebUI can't show you as online, and heartbeats are unreconciled.
+- **Don't randomize your `agentId`.** Read receipts and history break if your id changes every poll. Pick a stable convention and reuse it.
+- **Don't promise features the bridge doesn't expose.** The bridge is mailbox only. For the full WrongStack tool surface, use `wstack mcp serve`; for SMTP/IMAP, push back — WrongStack's mailbox is internal.
+
+## Before returning
+
+- [ ] No Mailbox files opened or edited directly; bridge and `mb()` only
+- [ ] Stable, honest `agentId`; no impersonation of `hq@...` or other agents
+- [ ] Token read from `.mailbox.token` or `.mailbox-bridge.lock`, not hardcoded
+- [ ] `mbWithBootstrap()` used for discovery when env vars aren't set
+- [ ] All requests carry `AbortSignal.timeout(10_000)`
+- [ ] `register_self` called with stable name and role before any traffic
+- [ ] Heartbeat every 30 s; `deregister_self` on clean shutdown
+- [ ] SSE preferred for real-time; polling ≥ 1 Hz, ≤ 5–10 s
+- [ ] `ack-many` used when more than one message needs acknowledgement
+- [ ] Broadcast only with clear subject, at most once per task
+- [ ] Bridge health (`/healthz`) probed before relying on routes
+
 ## Skills in scope
 
 - `node-modern` — `AbortSignal.timeout`, ESM-only imports.

package/skills/wrongstack-mailbox-mcp/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wrongstack-mailbox-mcp
 description: Coordinate with WrongStack agents through the project-scoped Mailbox MCP server. Use when an external coding agent needs to inspect unread or incomplete messages, query conversation history, discover online agents, send direct/reply/broadcast/steer messages, acknowledge outcomes, maintain its presence, soft-delete or restore messages, watch for changes, or perform explicitly authorized Mailbox administration without reading Mailbox files or SQLite directly.
+version: 1.0.0
 required-capabilities: [mcp.dynamic]
 required-tools: [mcp_use]
 ---
@@ -69,6 +70,32 @@ contain identifiers and metadata, not the authoritative message snapshot.
 - `mailbox_admin` provides clear, purge, compaction, and credential issue/verify/revoke/rotate/list
   operations. It requires `--admin`, which implies writable mode.
 
-Before `clear_all`, purge, credential revocation/rotation, or another broad administrative action,
-confirm that it is explicitly requested and re-read relevant state. Never use an admin operation to
-work around a routing, identity, or authorization error.
+## Out of scope
+
+- **Don't read or edit Mailbox files directly.** No `_mailbox.sqlite`, no legacy JSONL, no bridge locks, no token files. MCP is the only boundary; bypassing it through any of those channels breaks trust and audit.
+- **Don't impersonate another actor.** The server fixes sender, receipt, deletion, registration, and heartbeat identity to `--actor`. Tool arguments cannot override that. Use the actor id you were given, honestly.
+- **Don't reach for `steer` on routine direction.** Steer is for changed direction mid-task. For normal coordination, `ask`, `assign`, or `result` are the right types.
+- **Don't broadcast when direct addressing is correct.** Broadcast reaches every relevant agent; most messages don't.
+- **Don't run admin operations to bypass routing, identity, or authorization errors.** If a call is denied for one of those reasons, the call is wrong. Re-read state, ask, or stop. Admin paths are for explicitly authorized administration, not workarounds.
+- **Don't skip `register_self`.** Without registration, the runtime can't reconcile heartbeats or surface the agent in the workbench.
+- **Don't treat `mailbox_watch` events as authoritative.** Watch is a wake-up hint, not a snapshot. After every event, reconcile through `mailbox_read`.
+
+## Before returning
+
+- [ ] MCP server reached via `mcp_use`; never opened Mailbox files directly
+- [ ] Actor id stable and honest; no impersonation of `hq@...` or other agents
+- [ ] `register_self` called with stable name and role before any other traffic
+- [ ] `mailbox_read` with `unreadBy` + `incompleteOnly` used to find actionable work
+- [ ] `online_agents` checked before time-sensitive direct sends
+- [ ] `send` carries an explicit recipient and the right message type
+- [ ] `replyTo` set on threaded replies; no orphan context
+- [ ] `ack` / `ack_many` called with truthful `outcome` after work
+- [ ] `heartbeat_self` running during long work; `deregister_self` on clean shutdown
+- [ ] Admin operations (`clear_all`, purge, credential issue/revoke) only when explicitly requested
+
+## Skills in scope
+
+- `mailbox-bridge` — for the WrongStack-internal HTTP façade this MCP server mirrors
+- `wrongstack-mailbox` — for the external-facing counterpart used by Claude Code / Aider / scripts
+- `security-scanner` — for confirming the MCP server's authn/authz surface matches project security conventions
+- `output-standards` — for the `<nextsteps>` shape when reporting mailbox activity to the user