@erclx/aitk 0.88.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.88.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/claude/skills/decision-escalate/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: decision-escalate
+description: Scope boundary for handing a decision back to the operator, and the batching contract that keeps the handoff to one turn
+---
+
+# Decision escalate requirement
+
+## Gap
+
+Without this skill, a session facing a decision that belongs to the operator asks about it one question at a time across several turns, so the operator answers each without knowing how many are open and cannot trade one against another. It asks in prose with no options attached, so the operator has to invent the alternatives before picking one. It names an option and omits what the other one buys, so the pick is made blind. It escalates a call it could have settled from the repository or from its own judgment, which spends the operator's attention on work the session owed.
+
+It also empties a long backlog into one turn, so the questions past the first few arrive in no order and the operator cannot tell which ones the work is actually stalled on. It carries on with work the unanswered questions govern, so an answer arrives against output already built the other way. It takes the answer, acts, and leaves the plan, task, or record that posed the question reading as open, so the next session re-asks a decision the operator already made.
+
+A body written around a named tool fails a third way. A session on a surface carrying no structured question tool reads an instruction it cannot execute and falls back to whatever it would have done unaided, which is the per-decision ask this file exists against.
+
+The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
+
+`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has `snippets/decision-help.md` behind it and the second had no surface at all.
+
+## Must
+
+- Collect every open decision before asking any of them, so the operator sees the set rather than the first one
+- Put the whole batch in one turn, since a batch split across turns is the per-decision ask this skill exists to replace
+- Give each question two to four options, each carrying what it means and what it costs, with the recommendation ranked first and named as such
+- State the behavior first and the tool second, so the body runs on a chat surface carrying no structured question tool
+- Cap a batch at four questions and say how many are held, since a structured question tool takes four and an uncapped batch hides the overflow
+- Hold every escalated decision until it is answered, and continue only the work depending on none of them
+- Route a pick that changes a written artifact into that artifact under the standard owning it, rather than leaving it in the session
+
+## Must not
+
+- Answer on the operator's behalf, or treat the recommendation as the answer because no reply arrived
+- Escalate a decision the session can settle from its own judgment or from reading the repository, which is the first branch of the rule and belongs to the session
+- Escalate a decision already taken, which goes to the record that holds it rather than back to the operator
+
+## Guards
+
+- Nothing open, stop rather than manufacturing a question to justify the invocation
+
+## Out of scope
+
+- Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
+- The chat-side pick with no repository behind it, which `snippets/decision-help.md` covers and reaches a different reader
+- Writing the decision into a plan, task, or architecture record, which each owning standard governs and this skill only routes to
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so escalating is the operator's call rather than a description match.

package/claude/skills/decision-escalate/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: decision-escalate
+description: Collects every open decision whose answer turns on the operator's preference, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
+disable-model-invocation: true
+---
+
+# Decision escalate
+
+Put every open decision that belongs to the operator as one batch, each carrying its options and a recommended default, then stop until the batch is answered.
+
+One batch is the whole point. A session that asks one question, acts, then asks the next spends the operator's attention once per decision and hides how many are open.
+
+## Guards
+
+- If nothing is open, stop: `❌ Nothing to escalate. Every open call is one this session can make.`
+- Escalate only a decision whose answer turns on the operator's preference. A judgment call with two or three reasonable options the session can weigh is a pick with the tradeoff stated in one sentence, taken without asking.
+- Escalate only what is open now. A decision already taken this session goes to the artifact that records it rather than back to the operator.
+- Do not act on any decision in the batch before it is answered. Continue the work that depends on none of them.
+- Do not escalate a question the session can answer by reading the repository. Read first, and escalate what the tree does not settle.
+
+## Step 1: collect what is open
+
+Sweep the session for every decision still unmade. The usual sources:
+
+- A plan question whose answer turns on preference rather than measurement
+- A fork the session parked to keep moving, where both branches still ship
+- A default the session took silently that changes what the operator receives
+- A scope boundary the request left ambiguous, where the two readings produce different work
+
+Drop anything the session can settle. What survives is the batch.
+
+## Step 2: shape each question
+
+Each entry carries a short header naming the axis, the question itself, and two to four options. Give every option what it means and what it costs. Rank the recommendation first and say it is the recommendation.
+
+An option with no stated cost is not an option, since the operator picks it without knowing what the other one buys.
+
+Cap the batch at four. A structured question tool takes four, and a batch past that is a session asking to be redesigned rather than answered. When more than four are open, send the four blocking the most work and say in one line how many are held.
+
+## Step 3: put the batch
+
+Put every question in one turn. Never split the batch across turns and never ask the first while the rest stay unstated.
+
+When the session runs on a surface carrying a structured question tool, such as `AskUserQuestion` in Claude Code, send the whole batch through one call with one entry per decision. The tool renders the options and collects the picks together.
+
+Otherwise write the batch as a numbered list in one message, each question followed by its lettered options with the recommendation marked. The behavior is the same on either surface, and only the rendering changes.
+
+Batch shape:
+
+```plaintext
+<N> open decisions. <M> held.
+
+1. <axis>: <question>
+   a. <option> (recommended): <what it means>, <what it costs>
+   b. <option>: <what it means>, <what it costs>
+
+2. <axis>: <question>
+   a. <option> (recommended): <what it means>, <what it costs>
+   b. <option>: <what it means>, <what it costs>
+```
+
+## Step 4: wait
+
+Stop after the batch. Do not answer on the operator's behalf, do not act on the recommendation because it is the recommendation, and do not fill the wait with work the batch would invalidate.
+
+An operator who answers some and not others has answered those. Continue on the answered ones and hold the rest.
+
+## Step 5: record and continue
+
+Restate each pick in one line, then continue the work.
+
+A pick that changes a written artifact goes into that artifact under the rule its own standard sets. An answer to an open plan question rewrites that question's `- Suggested:` line to the pick and names the operator as its source, leaving the `- Answer:` slot blank, per `.claude/standards/plan.md`, or `${CLAUDE_SKILL_DIR}/../../standards/plan.md` when the project does not have it. The standard bars a session from filling that slot even when the operator supplied the pick, and the blank slot resolves to the rewritten suggestion, so the record carries the operator's decision either way. A pick that settles nothing written stays in the session.
+
+Output after the answers land:
+
+```plaintext
+✅ <N> decisions answered
+<axis>: <pick>
+<axis>: <pick>
+<M held, restated in one line each>
+```

package/docs/agents/markdown-audit.md

@@ -51,7 +51,7 @@ A banned word is bounded on a word character or a hyphen either side. A plain wo
 
 A banned spelling keeps the plain word boundary, hyphens included. The two bans target different things: a word ban targets the word, so reading a compound as one word is correct, while a spelling ban targets the orthography inside it, which sits in `behaviour-driven` as plainly as it sits alone.
 
-Two ban shapes stay unmeasured and the report says so on every run. A phrase ban carries a placeholder standing in for the rest of the sentence, so no literal match reaches it, and every rule under `## Voice` is a judgment. A report listing hits without naming those would read as a verdict on the whole standard.
+Two ban shapes stay unmeasured and the report says so on every run. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim sit in the first group by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole standard.
 
 ### Bullets, paragraphs, and depth
 

package/docs/ai-workflow.md

@@ -169,6 +169,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `aitk:claude-intake`         | File a brain dump into an inventory under `.claude/intake/`, one item per finding with a verdict                     |
 | `aitk:claude-groundwork`     | Before a plan is warranted, measure an unknown in a track folder under `.claude/groundwork/`                         |
 | `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                            |
+| `aitk:decision-escalate`     | Batch every open decision that turns on your preference into one set of questions, each with a recommended default   |
 | `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                     |
 | `aitk:claude-orchestrate`    | Assert the orchestrator role, refill the ready queue, and dispatch the feature, review, and worktree skills          |
 | `aitk:claude-diagram`        | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image |

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.88.0",
+  "version": "0.89.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/standards/index.md

@@ -13,10 +13,10 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
-- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
-- [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
+- [Prose reference](prose.md): Voice, language, what prose may claim, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md

package/standards/markdown.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown reference
-description: Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
 ---
 
 # Markdown reference
@@ -9,11 +9,11 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 ## Scope
 
-Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have no shape of their own.
+Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have no shape of their own.
 
 Does not govern:
 
-- Voice, word choice, and the wording of a `title` or `description`: `prose.md`
+- Voice, word choice, what prose may claim, and the wording of a `title` or `description`: `prose.md`
 - What sections a document has, or what belongs in each: the standard for that document type
 - The text inside a fenced block, which follows the conventions of its own language rather than these
 - The scan that applies the punctuation bans to finished text on its way out: `publish.md`
@@ -49,6 +49,10 @@ Does not govern:
 - Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
 - In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
 
+## Dates
+
+- Write a date as `YYYY-MM-DD` wherever one appears, in frontmatter, in prose, and in a filename. Never a month name, a slash-separated form, or a two-digit year.
+
 ## Punctuation
 
 - Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them.

package/standards/prose.md

@@ -1,6 +1,6 @@
 ---
 title: Prose reference
-description: Voice, language, and frontmatter wording for reference markdown
+description: Voice, language, what prose may claim, and frontmatter wording for reference markdown
 ---
 
 # Prose reference
@@ -11,11 +11,11 @@ The yield covers voice alone. The language rules below stay in force on every su
 
 ## Scope
 
-Governs voice, word choice, and frontmatter wording wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, yields on voice alone where that standard states one, and carries no template because voice is written across every document and has none of its own to shape.
+Governs voice, word choice, what prose may claim about its subject and its sources, and frontmatter wording wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, yields on voice alone where that standard states one, and carries no template because voice is written across every document and has none of its own to shape.
 
 Does not govern:
 
-- Headings, list and paragraph structure, code spans, punctuation, emphasis, and file references: `markdown.md`
+- Headings, list and paragraph structure, code spans, the form a date takes, punctuation, emphasis, and file references: `markdown.md`
 - What sections a document has, or what belongs in each: the standard for that document type
 - Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
 - Phase-label and semver discipline: `versioning.md`
@@ -44,8 +44,14 @@ Does not govern:
 - Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
 - Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
 - Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
+- Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
+- Do not name a person, company, or product to borrow its authority. Name a source only where the claim turns on who made it.
+- Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
+- Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
 
-The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and these are word choice. A surface applying both reads both files.
+The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and the bans here reach the words a sentence chooses and the claims it makes. A surface applying both reads both files.
+
+Illustrate a pattern ban with a multi-word phrase. An audit reading this section harvests the single lowercase backticked words out of every `- Do not use ` bullet into a literal ban set, so a one-word example bans that word everywhere it appears rather than banning the pattern it stands for. Both the toolkit command and the audit hook a project installs parse that shape, so the constraint holds wherever this file lands.
 
 ## Frontmatter descriptions
 

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/claude/seeds/CLAUDE.md

@@ -36,11 +36,15 @@
 
 ## Output
 
-- After creating or modifying a file, include its path on its own line so terminal emulators can make it clickable. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
+- After creating or modifying a file, include its path on its own line so the reader can open it. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
+- Read `CLAUDE_CODE_ENTRYPOINT` once, at the first response that emits a path, and reuse it for the rest of the session. The surface cannot change mid-session, so a second read only confirms the first.
+- When it reads `claude-desktop`, emit each path as a markdown link carrying the path as its text and an absolute `file://` URI as its target, resolving a relative path against the main project root to build that target. The desktop file tree hides dotted folders, so a bare path into one names a file the reader cannot reach.
+- On every other value, including unset, emit the path bare. A terminal emulator makes it clickable through its own path detection, and link markup defeats that.
+- Both forms govern a path emitted in a response. A path written into a markdown file follows `.claude/standards/markdown.md` instead, which backticks a file reference and never repeats it as a link label.
 - Use the path the user's editor can resolve. The editor is rooted at the main project root.
-- In the main worktree: relative from `pwd` works because `pwd` equals the editor root
+- In the main worktree: relative from `pwd` works because `pwd` equals the editor root.
 - In a linked worktree (under `.claude/worktrees/<name>/`): use absolute paths. Relative paths from worktree `pwd` would not resolve against the editor's project root.
-- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. For single-file changes, the path on its own line is enough.
+- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. Every path under them takes the form the entrypoint selected rather than the first alone. For single-file changes, the path on its own line is enough.
 
 ## Key paths
 

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.