codebyplan 1.12.0 → 1.13.0

package/templates/skills/cbp-setup-eslint/reference/tailwind.md

@@ -0,0 +1,64 @@
+# tailwind — Tailwind CSS class linting
+
+For apps using Tailwind CSS (the CBP `tarkur` repo uses Tailwind + shadcn/ui). **Gap stack —
+no CBP DB preset.** Adds class-sorting / validation rules on top of the app's base config.
+
+> **Verified 2026-05-31.** Use **`eslint-plugin-better-tailwindcss`** — it is the only plugin
+> with first-class **Tailwind v4** + ESLint 9/10 flat-config support. The original
+> `eslint-plugin-tailwindcss` only handles v4 on an unstable alpha — **avoid it for v4.**
+
+## Packages
+
+| Package | Latest | Tailwind v4? | Verdict |
+| ------- | ------ | ------------ | ------- |
+| `eslint-plugin-better-tailwindcss` | `4.5.0` | **yes (stable)** | **use this** |
+| `eslint-plugin-tailwindcss` | `3.18.3` (v4 only on `4.0.0-alpha`) | beta/as-is | avoid for v4 |
+
+```bash
+pnpm add -D eslint-plugin-better-tailwindcss
+```
+
+Peer deps: `eslint ^7 || ^8 || ^9 || ^10`, `tailwindcss ^3.3.0 || ^4.1.17`. Node ≥ 20.19.
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import betterTailwind from "eslint-plugin-better-tailwindcss";
+
+export default defineConfig([
+  {
+    extends: [betterTailwind.configs["recommended"]],
+    settings: {
+      "better-tailwindcss": {
+        // Tailwind v4: path to the CSS file with `@import "tailwindcss"`
+        entryPoint: "src/app/globals.css",
+        // Tailwind v3 ONLY (omit for v4):
+        // tailwindConfig: "tailwind.config.js",
+      },
+    },
+  },
+]);
+```
+
+## Gotchas
+
+- **`settings.entryPoint` is REQUIRED for Tailwind v4** — it points at the global CSS file
+  containing `@import "tailwindcss"` (v4 has no JS config file). For v3, use `tailwindConfig`
+  instead.
+- **Monorepo**: set `settings["better-tailwindcss"].cwd` per file-group so the plugin resolves
+  `tailwindcss` + the config from the correct project dir when ESLint runs from the repo root.
+- Config presets: `recommended`, `correctness` (errors), `stylistic` (warnings); severity
+  suffixes `-error` / `-warn`.
+- Non-JSX file types (Svelte/Vue/Astro/HTML) need the matching `languageOptions.parser`.
+
+## CBP preset divergence
+
+There is **no** CBP `tailwind` DB preset — Tailwind linting is entirely manual. `tarkur`
+currently has no Tailwind ESLint rules; add the block above to lint class order/validity.
+
+## Official docs
+
+- eslint-plugin-better-tailwindcss: https://github.com/schoero/eslint-plugin-better-tailwindcss
+- Settings: https://github.com/schoero/eslint-plugin-better-tailwindcss/blob/main/docs/settings/settings.md

package/templates/skills/cbp-setup-eslint/reference/testing-react.md

@@ -0,0 +1,57 @@
+# testing-react — Testing Library + jest-dom rules
+
+For React component tests (Testing Library assertions). Layers a **test-scoped** override on
+top of [base](base.md) + the test-runner doc ([vitest](vitest.md) or [jest](jest.md)). Maps to
+the CBP **`testing-react`** DB preset
+(`tech_match.requires: ["React", "Vitest"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** Both plugins use bracketed `configs['flat/...']` keys and each
+> spreads its own plugin registration — keep them as **separate array entries**.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-testing-library` | `7.16.2` | Testing Library best-practices |
+| `eslint-plugin-jest-dom` | `5.5.0` | `@testing-library/jest-dom` matchers |
+
+```bash
+pnpm add -D eslint-plugin-testing-library eslint-plugin-jest-dom
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import testingLibrary from "eslint-plugin-testing-library";
+import jestDom from "eslint-plugin-jest-dom";
+
+const TEST_GLOBS = ["**/*.{test,spec}.{ts,tsx,js,jsx}", "**/__tests__/**/*.{ts,tsx,js,jsx}"];
+
+export default [
+  { files: TEST_GLOBS, ...testingLibrary.configs["flat/react"] }, // 'flat/dom' for non-React
+  { files: TEST_GLOBS, ...jestDom.configs["flat/recommended"] },
+];
+```
+
+## Gotchas
+
+- Keep the two as **separate array entries** — each `...config` spread re-declares its own
+  `plugins`. Merging them into one object means you must hand-combine `plugins` + `rules`.
+- `eslint-plugin-testing-library` framework presets: `flat/react`, `flat/dom` (agnostic),
+  `flat/vue`, `flat/angular`, `flat/svelte`, `flat/marko` — pick **one**.
+- Scope to the **same test globs** as your runner override so the rules don't bleed onto
+  production code.
+- Don't let Playwright e2e specs hit `testing-library/*` rules (e.g.
+  `prefer-screen-queries` mis-fires on Playwright's `page.getByRole`) — scope to `src/**`
+  unit tests, not the e2e dir (see [e2e.md](e2e.md)).
+
+## CBP preset divergence
+
+The CBP `testing-react` preset matches this (`eslint-plugin-testing-library: ^7.0.0`,
+`eslint-plugin-jest-dom: ^5.0.0`, `flat/react` + `flat/recommended`). No divergence.
+
+## Official docs
+
+- testing-library: https://github.com/testing-library/eslint-plugin-testing-library
+- jest-dom: https://github.com/testing-library/eslint-plugin-jest-dom

package/templates/skills/cbp-setup-eslint/reference/vitest.md

@@ -0,0 +1,62 @@
+# vitest — Vitest test-file rules
+
+For apps that test with Vitest (CBP web + CLI + most repos). Layers a **test-scoped** override
+on top of [base](base.md). Maps to the CBP **`testing`** DB preset
+(`tech_match.requires: ["Vitest"]`).
+
+> **Verified 2026-05-31.** The package was **renamed** to the scoped
+> **`@vitest/eslint-plugin`** (the old `eslint-plugin-vitest` is the deprecated name). Its
+> flat-config key is plain **`configs.recommended`** — there is **no `flat/` prefix**.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `@vitest/eslint-plugin` | `1.6.18` | Vitest rules (scoped pkg) |
+
+```bash
+pnpm add -D @vitest/eslint-plugin
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import vitest from "@vitest/eslint-plugin";
+
+export default [
+  {
+    files: ["**/*.{test,spec}.{ts,tsx,js,jsx}"],
+    plugins: { vitest },
+    rules: {
+      ...vitest.configs.recommended.rules,
+      // tests are I/O-heavy + mock-heavy — relax type-safety on test files:
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+    },
+    settings: { vitest: { typecheck: true } }, // only if using Vitest type-testing
+  },
+];
+```
+
+## Gotchas
+
+- The key is **`vitest.configs.recommended`** (plain) — NOT `configs['flat/recommended']`.
+  Other plugins use the bracketed `flat/` form; Vitest does not.
+- When you spread only `.rules`, register `plugins: { vitest }` yourself. Alternatively spread
+  the whole `...vitest.configs.recommended` (carries the plugin registration).
+- The `no-unsafe-*` / `no-explicit-any` opt-outs are CBP convention — production code keeps
+  them at `error`; test surfaces relax them because mocks produce `any`-typed values.
+
+## CBP preset divergence
+
+The CBP `testing` preset matches this (the six `no-unsafe-*`/`no-explicit-any` opt-outs,
+`@vitest/eslint-plugin: ^1.0.0`). No divergence.
+
+## Official docs
+
+- @vitest/eslint-plugin: https://github.com/vitest-dev/eslint-plugin-vitest

package/templates/skills/cbp-task-complete/SKILL.md

@@ -137,9 +137,7 @@ Skip the push only when nothing was committed in Step 5 AND `/cbp-merge-main` re
 
 ### Step 7: Complete Task
 
-If `CALLER_WT` is non-empty, call `complete_task(task_id, caller_worktree_id: CALLER_WT)`. Otherwise call `complete_task(task_id)` with no worktree id — the pre-guard is skipped (backwards-compat).
-
-**When calling `complete_task`**: pass `caller_worktree_id` resolved from `npx codebyplan resolve-worktree`. The MCP server's pre-guard rejects mutations from non-matching worktrees; supplying `caller_worktree_id` ensures legitimate completion succeeds. The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 TASK-2 hard-lock.)
+Call `complete_task(task_id)`. The server resolves the caller's worktree identity from the JWT/ctx and enforces the mutate-lock (CHK-140 TASK-3 — `caller_worktree_id` input field removed). The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 hard-lock.)
 
 ### Step 7.5: Standalone Task Branch Merge
 

package/templates/skills/cbp-task-start/SKILL.md

@@ -160,9 +160,9 @@ See `dependency-vulnerability-fixes.md` "Audit Sweep at Task Start" for the sour
 
 ### Step 3.5: Worktree-Match Verification
 
-Before activating the task, verify the caller's worktree matches the assigned worktree on the target row. (Per CHK-104 TASK-2 — DB-level hard-lock prevents cross-worktree mutations.)
+Before activating the task, verify the caller's worktree matches the assigned worktree on the target row. (Per CHK-104 — DB-level hard-lock prevents cross-worktree mutations; the server resolves caller identity from the JWT/ctx.)
 
-1. Read caller worktree: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If empty, the `caller_worktree_id` parameter is omitted from the MCP call entirely — the pre-guard is skipped and the update proceeds without a worktree check (backwards-compat).
+1. Read caller worktree: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`.
 2. Determine target worktree:
    - **Checkpoint-bound tasks**: `TARGET_WT = checkpoint.worktree_id` (read from MCP `get_checkpoints`). Note: checkpoint-bound tasks may have a NULL `task.assigned_worktree_id` because the lock lives on the parent checkpoint — fall through to `checkpoint.worktree_id`.
    - **Standalone tasks**: `TARGET_WT = task.assigned_worktree_id`.
@@ -222,7 +222,7 @@ Display context summary:
 
 Use MCP `update_task(task_id, status: "in_progress")`.
 
-If worktree_id present, include `claim_worktree_id` to auto-claim the checkpoint AND `caller_worktree_id: CALLER_WT` so the MCP server's pre-guard accepts the call (CHK-104 TASK-2 hard-lock).
+If worktree_id present, include `claim_worktree_id` to auto-claim the checkpoint. The server resolves the caller's worktree identity from the JWT/ctx (CHK-140 TASK-3 — `caller_worktree_id` input field removed).
 
 ### Step 6: Auto-trigger Round Start
 

package/templates/hooks/cbp-mcp-worktree-inject.sh

@@ -1,76 +0,0 @@
-#!/bin/bash
-# @scope: org-shared
-# Hook: PreToolUse mcp__codebyplan__(update_task|complete_task|complete_round|update_checkpoint)
-# Purpose: Auto-inject caller_worktree_id into MCP mutation calls when not already
-#          present. Uses the PreToolUse hookSpecificOutput.updatedInput contract
-#          (Claude Code v2.1 — see hooks.md "PreToolUse decision control"):
-#            - Output JSON with hookSpecificOutput.permissionDecision="allow" and
-#              hookSpecificOutput.updatedInput containing the full modified tool_input.
-#          This hook NEVER exits non-zero — it is a no-op on all failure paths.
-#
-# Fallback chain:
-#   1. caller_worktree_id already present in tool_input → passthrough (no-op)
-#   2. Primary: npx codebyplan resolve-worktree → UUID found → inject
-#   3. Secondary: npx codebyplan resolve-worktree --fallback-from-branch → UUID found → inject
-#   4. Both empty → passthrough (server pre-guard skips when absent)
-#
-# NEVER exit non-zero — backwards-compat passthrough when resolver is broken.
-
-INPUT=$(cat)
-
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
-
-# Only intercept matching MCP mutation tools
-case "$TOOL_NAME" in
-  mcp__codebyplan__update_task|\
-  mcp__codebyplan__complete_task|\
-  mcp__codebyplan__complete_round|\
-  mcp__codebyplan__update_checkpoint) ;;
-  *) exit 0 ;;
-esac
-
-# If caller_worktree_id is already present, pass through unchanged
-EXISTING=$(echo "$INPUT" | jq -r '.tool_input.caller_worktree_id // empty' 2>/dev/null)
-if [ -n "$EXISTING" ]; then
-  exit 0
-fi
-
-# Try primary resolver
-UUID=$(npx --yes codebyplan resolve-worktree 2>/dev/null)
-
-# Try fallback if primary returned empty
-if [ -z "$UUID" ]; then
-  UUID=$(npx --yes codebyplan resolve-worktree --fallback-from-branch 2>/dev/null)
-fi
-
-# If no UUID resolved, passthrough unchanged
-if [ -z "$UUID" ]; then
-  exit 0
-fi
-
-# Extract tool_input and guard against null before merging
-TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input' 2>/dev/null)
-if [ -z "$TOOL_INPUT" ] || [ "$TOOL_INPUT" = "null" ]; then
-  # No tool_input to mutate — output original input unchanged
-  echo "$INPUT"
-  exit 0
-fi
-
-MERGED_TOOL_INPUT=$(echo "$TOOL_INPUT" | jq -c --arg uuid "$UUID" '. + {caller_worktree_id: $uuid}' 2>/dev/null)
-if [ -z "$MERGED_TOOL_INPUT" ] || [ "$MERGED_TOOL_INPUT" = "null" ]; then
-  echo "$INPUT"
-  exit 0
-fi
-
-# Output PreToolUse hookSpecificOutput with updatedInput
-jq -n \
-  --argjson updated "$MERGED_TOOL_INPUT" \
-  '{
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "allow",
-      updatedInput: $updated
-    }
-  }'
-
-exit 0