@erclx/aitk 0.89.0 → 0.89.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.89.0",
+  "version": "0.89.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/SKILL.md

@@ -196,6 +196,8 @@ properly and stop when you cannot.
 Serialize any track that touches a shared wiring seam with another in flight.
 Merge the branch with the smallest shared-file footprint first, and merge a
 branch touching `CLAUDE.md`, a Claude context entry, or a regenerated `index.md`
-last. Have every sibling rebase on the new `main` before the next merge. Assign
-a distinct port per track when two workers run a server, since each session
-spawns its own process.
+last. Have every sibling rebase on the new `main` before the next merge. Two
+workers running a server take a port apiece without being told to, since a
+stack derives it from the worktree it runs in through `scripts/worktree-port.sh`.
+Read that value rather than assigning one, and set `WORKTREE_PORT_OFFSET` by
+hand only when two worktrees derive the same offset.

package/claude/skills/claude-worktree/REQUIREMENT.md

@@ -11,6 +11,10 @@ Without this skill, the user names the worktree by hand, and a name matching no
 
 Entry also writes the bare flag into the shared config, which strands the main worktree. Every command run there fails while the files sit untouched on disk, and the linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout and finds the repository broken. A rename onto a branch that already exists is the third failure, and it is the one that destroys work rather than blocking it.
 
+The tree the entry hands over is also not one the session can run. Dependencies live in a folder git ignores and never shares between working directories, so a fresh worktree arrives with none, and nothing on the entry path says so. The session finds out from whichever command needs them first, and the message it gets names a missing module rather than an empty working directory.
+
+A stack that derives its ports from the working directory has the same shape. The number is correct and invisible, and `claude-orchestrate` sends a reader here to read it rather than assign one, so the entry that knows the working directory is the surface that owes it.
+
 ## Must
 
 - Derive the name from the plan matched to the current branch, falling through the ordered sources rather than picking
@@ -21,9 +25,13 @@ Entry also writes the bare flag into the shared config, which strands the main w
 - Test the target branch and the target directory before entering, so a stop costs no worktree
 - Read the bare flag before writing it, and repair it on both sides of entry
 - Announce the repair only when a write actually happened
+- Report on one line whether the entered worktree carries its dependencies, naming the command that installs them when it does not
+- Report the same way when the project declares no package manifest, since silence there reads as a passing check
+- Report the port offset this worktree derives, and say so when the project installs no derivation
 
 ## Must not
 
+- Install dependencies on the session's behalf. Entering a worktree to read is as common as entering one to run, and an install is slow and needs a network.
 - Pick between plans when more than one could match. Ask.
 - Enter on a name inferred from session context without confirmation
 - Delete or overwrite a branch or a worktree directory that already carries the target name

package/claude/skills/claude-worktree/SKILL.md

@@ -96,4 +96,26 @@ git config core.bare false
 
 The flag is not set on every entry, so read before writing and announce only when the write happened. Tracked upstream as `anthropics/claude-code#58345`, closed as not planned, so the repair stays until the tool changes.
 
+## Step 6: report whether the tree can run
+
+A linked worktree is a second working directory over one repository, and every ecosystem installs its dependencies into a folder git ignores. Nothing copies that folder across, so a fresh worktree arrives without it and the session learns as much from whichever command needs it first, which reports a missing module rather than an empty working directory.
+
+Report the state on one line. Do not install. Entering a worktree to read is as common as entering one to run, and an install is slow, needs a network, and picks an ecosystem on the session's behalf.
+
+Read the worktree root and emit the first line that matches:
+
+- `package.json` present, `node_modules/` missing: `Dependencies are not installed. Run <install> before any build, test, or server command.` Take `<install>` from the lockfile beside the manifest, and use `bun install` when no lockfile names one.
+- A `pyproject.toml` or `requirements.txt` present, `.venv/` missing: `No virtual environment. Create and populate one before running anything.`
+- A manifest present with its folder alongside it: `Dependencies are installed.`
+- No package manifest of either kind: `No package manifest, so there is nothing to install.`
+
+The last line is what keeps the step honest on a stack this skill cannot read. Entry is not stack-aware, and silence is indistinguishable from a check that passed.
+
+Then report the port this worktree derives, on a second line:
+
+- `scripts/worktree-port.sh` present: run `bash scripts/worktree-port.sh` and emit `Port offset <n>. Every served port adds it to the stack default.`
+- Absent: `No port derivation installed, so every served port is the stack default.`
+
+The offset is what `claude-orchestrate` sends a reader here to read rather than assign, and what an operator overrides through `WORKTREE_PORT_OFFSET` when two worktrees derive the same value. Deriving it correctly and printing it nowhere leaves both instructions naming a number no surface emits.
+
 Do not invoke `ExitWorktree` from this skill. Exit is the user's call.

package/docs/operating-model.md

@@ -125,8 +125,10 @@ at two or three worker tracks and split them across the stack so they do not
 collide on the same files.
 
 Unit checks run freely in many worktrees at once.
-Only fixed-port work (a dev server, an end-to-end run, a screenshot) and
-singleton resources (one local model server, one GPU) serialize. See
+A dev server, an end-to-end run, and a screenshot run alongside each other on a
+web stack, since every worktree derives its own port. Singleton resources (one
+local model server, one GPU) still serialize, as does any port a stack fixes by
+hand. See
 [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for merge order and the
 port-collision detail.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.89.0",
+  "version": "0.89.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/tooling/astro/configs/astro.config.mjs

@@ -3,9 +3,14 @@ import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'astro/config'
 import path from 'path'
 
+const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
+
 export default defineConfig({
   integrations: [react()],
   site: process.env.ASTRO_SITE,
+  server: {
+    port: 4321 + portOffset,
+  },
   vite: {
     plugins: [tailwindcss()],
     resolve: {
@@ -13,5 +18,11 @@ export default defineConfig({
         '@': path.resolve('./src'),
       },
     },
+    server: {
+      strictPort: true,
+    },
+    preview: {
+      strictPort: true,
+    },
   },
 })

package/tooling/astro/configs/playwright.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig, devices } from '@playwright/test'
 
 const isCI = !!process.env.CI
+const baseURL = `http://localhost:${4321 + (Number(process.env.WORKTREE_PORT_OFFSET) || 0)}`
 
 export default defineConfig({
   testDir: 'e2e',
@@ -10,7 +11,7 @@ export default defineConfig({
   reporter: isCI ? 'list' : 'html',
   use: {
     trace: 'on-first-retry',
-    baseURL: 'http://localhost:4321',
+    baseURL,
   },
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
@@ -19,7 +20,7 @@ export default defineConfig({
   ],
   webServer: {
     command: 'bun run build && bun run preview',
-    url: 'http://localhost:4321',
-    reuseExistingServer: !isCI,
+    url: baseURL,
+    reuseExistingServer: false,
   },
 })

package/tooling/astro/manifest.toml

@@ -15,15 +15,17 @@ packages = [
 ]
 
 [scripts]
-"dev" = "astro dev"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro dev"
 "build" = "astro check && astro build"
-"preview" = "astro preview"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro preview"
 "astro" = "astro"
 "typecheck" = "astro check"
 "setup" = "./scripts/setup.sh"
 
 [scripts.override]
-"screenshot" = "PREVIEW_PORT=4321 bash scripts/screenshot.sh"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) bash scripts/screenshot.sh"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro dev"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro preview"
 
 [gitignore]
 "# Astro" = [".astro/"]

package/tooling/astro/reference.md

@@ -17,9 +17,9 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 ## What ships as golden configs
 
-- `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field.
+- `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field. Port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`. Astro merges the user's `vite` block into the config backing both its dev and its static preview server, and feeds `server.port` through as the preview port, so the port sits at the top level while the bind guarantee sits under `vite`.
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
-- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port 4321. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`.
+- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
 - `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). `src/pages/**` exempt from filename and folder naming conventions because Astro's file-based routing ties names to URL segments.
 
@@ -49,7 +49,7 @@ Add `prettier-plugin-astro` first in plugins, then `prettier-plugin-tailwindcss`
 
 Append to the `## Scripts` table:
 
-| `bun run dev` | Start the Astro dev server on port 4321. |
+| `bun run dev` | Start the Astro dev server on port 4321, plus this worktree's port offset. |
 | `bun run build` | Run `astro check` then build the static output. |
 | `bun run preview` | Serve the built site locally. |
 | `bun run astro` | Expose the Astro CLI. |

package/tooling/vite-react/configs/playwright.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig, devices } from '@playwright/test'
 
 const isCI = !!process.env.CI
+const baseURL = `http://localhost:${5173 + (Number(process.env.WORKTREE_PORT_OFFSET) || 0)}`
 
 export default defineConfig({
   testDir: 'e2e',
@@ -10,7 +11,7 @@ export default defineConfig({
   reporter: isCI ? 'list' : 'html',
   use: {
     trace: 'on-first-retry',
-    baseURL: 'http://localhost:5173',
+    baseURL,
   },
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
@@ -19,7 +20,7 @@ export default defineConfig({
   ],
   webServer: {
     command: 'bun run dev',
-    url: 'http://localhost:5173',
-    reuseExistingServer: !isCI,
+    url: baseURL,
+    reuseExistingServer: false,
   },
 })

package/tooling/vite-react/configs/vite.config.ts

@@ -3,6 +3,8 @@ import react from '@vitejs/plugin-react'
 import path from 'path'
 import { defineConfig } from 'vite'
 
+const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
+
 export default defineConfig({
   plugins: [react(), tailwindcss()],
   resolve: {
@@ -11,4 +13,12 @@ export default defineConfig({
     },
   },
   base: process.env.VITE_BASE_URL ?? '/',
+  server: {
+    port: 5173 + portOffset,
+    strictPort: true,
+  },
+  preview: {
+    port: 4173 + portOffset,
+    strictPort: true,
+  },
 })

package/tooling/vite-react/manifest.toml

@@ -11,11 +11,13 @@ packages = [
 ]
 
 [scripts]
-"dev" = "vite"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite"
 "build" = "tsc --noEmit && vite build"
-"preview" = "vite preview"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite preview"
 "typecheck" = "tsc --noEmit"
 "setup" = "./scripts/setup.sh"
 
 [scripts.override]
 "build" = "tsc --noEmit && vite build"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite preview"

package/tooling/vite-react/reference.md

@@ -16,16 +16,16 @@ The vite-react stack covers Vite + React + TypeScript projects: web apps and Chr
 
 ## What ships as golden configs
 
-- `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path.
+- `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path. Dev port `5173` and preview port `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
 - `vitest.config.ts`: merges from `vite.config.ts`, jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
-- `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port 5173, trace under `use`.
+- `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, trace under `use`.
 - `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom` in types.
 
 ## Chrome extension variant
 
 When scaffolding a Chrome extension, override the installed golden configs:
 
-- `vite.config.ts`: use `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Set `server.port: 5173`, `server.strictPort: true`, `server.hmr.clientPort: 5173`, and `chrome-extension://` in CORS origins. Drop `VITE_BASE_URL`.
+- `vite.config.ts`: use `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Keep the derived `server.port` and `server.strictPort: true`, set `server.hmr.clientPort` to the same derived value, and add `chrome-extension://` to CORS origins. Drop `VITE_BASE_URL`.
 - `vitest.config.ts`: use a standalone `defineConfig` (no `mergeConfig`). crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly. Add `**/release/**` to excludes and `manifest.config.ts`, `**/*.d.ts` to coverage excludes.
 - `playwright.config.ts`: chromium-only (Firefox and WebKit cannot run extensions). Bundled `chromium` channel. No `baseURL` or `webServer`. Tests load the built extension directly from `dist/`.
 - `e2e/fixtures.ts`: extend Playwright base `test` with `context` (persistent context loading the extension from `dist/`) and `extensionId` (extracted from service worker URL). Rename `use` to `apply` to avoid the React hooks ESLint rule. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
@@ -45,7 +45,7 @@ When scaffolding a Chrome extension, override the installed golden configs:
 
 Append to the `## Scripts` table:
 
-| `bun run dev` | Start the Vite dev server on port 5173. |
+| `bun run dev` | Start the Vite dev server on port 5173, plus this worktree's port offset. |
 | `bun run build` | Typecheck then build the production bundle. |
 | `bun run preview` | Serve the built bundle locally. |
 | `bun run typecheck` | Run `tsc --noEmit`. |

package/tooling/web/configs/scripts/worktree-port.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Prints a port for this working directory: the base itself in a normal
+# checkout, and the base plus a per-worktree offset in a linked git worktree,
+# so two worktrees of one repository never serve on one port.
+
+base="${1:-0}"
+band=50
+
+offset() {
+  if [[ -n "${WORKTREE_PORT_OFFSET:-}" ]]; then
+    echo "$WORKTREE_PORT_OFFSET"
+    return
+  fi
+
+  local git_dir common_dir name
+  git_dir=$(git rev-parse --git-dir 2>/dev/null) || {
+    echo 0
+    return
+  }
+  common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || {
+    echo 0
+    return
+  }
+
+  if [[ "$(cd "$git_dir" && pwd -P)" == "$(cd "$common_dir" && pwd -P)" ]]; then
+    echo 0
+    return
+  fi
+
+  name=$(basename "$(git rev-parse --show-toplevel)")
+  echo $(($(printf '%s' "$name" | cksum | cut -d' ' -f1) % band + 1))
+}
+
+echo $((base + $(offset)))

package/tooling/web/manifest.toml

@@ -42,13 +42,13 @@ packages = [
 "test:run" = "vitest run --reporter=verbose"
 "test:ui" = "vitest --ui"
 "test:coverage" = "vitest run --coverage"
-"test:e2e" = "playwright test"
-"test:e2e:ui" = "playwright test --ui"
+"test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) playwright test"
+"test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) playwright test --ui"
 "test:e2e:report" = "playwright show-report"
 "check:full" = "./scripts/verify.sh && bun run test:e2e"
 
 [scripts.override]
-"screenshot" = "bash scripts/screenshot.sh"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) bash scripts/screenshot.sh"
 
 [gitignore]
 "# Build" = ["dist/"]

package/tooling/web/reference.md

@@ -16,6 +16,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
+- `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone.
 
 ## What stays in per-stack adapters
 
@@ -32,6 +33,17 @@ Framework glue lives in `tooling/vite-react/configs/` or `tooling/astro/configs/
 - Path alias `@` maps to `./src` in both tsconfig and the framework's build config.
 - Tsconfig is unified at root with `noEmit: true` in Vite stacks. Astro uses the scaffold default from `@astrojs/check`.
 
+## Ports
+
+Two worktrees of one repository run the same stack, so a fixed port makes the second one attach to the first.
+
+- Derive every served port from `scripts/worktree-port.sh`. Never write a port literal into a script string.
+- Read `WORKTREE_PORT_OFFSET` in a config and add it to the stack's default port. Unset yields the default, so a plain clone keeps the port it has always served on.
+- Draw the offset from a band of 50, hashed from the worktree folder name. Two worktrees can hash to one offset, so set `WORKTREE_PORT_OFFSET` by hand to break a tie.
+- Force-replace `dev` and `preview` through `[scripts.override]`. Both stacks' scaffolds define those keys, and a plain `[scripts]` entry never replaces a key the scaffold already wrote.
+- Set `strictPort` on every dev and preview server. A server that walks to the next free port serves where nothing is looking for it.
+- Set Playwright `reuseExistingServer: false`. Reuse attaches to whatever answers on the port, which reports a pass against another branch's code and prints nothing to say so.
+
 ## Anti-patterns
 
 Sticky negative knowledge. Do not relearn.