@erclx/aitk 0.89.0 → 0.90.0

package/src/intake/items.ts

@@ -0,0 +1,174 @@
+import { bodyLines } from '@/markdown/scan'
+
+/**
+ * The index points at items and answers nothing itself, so it carries no
+ * answer slot for this verb to reach. It also displays the item format inside a
+ * fence, which the fence walk already masks, so skipping it by name is about
+ * what the file is rather than about the block it holds.
+ */
+export const INDEX_FILE = '00-overview.md'
+
+/**
+ * An item heading, labeled per cluster file rather than per folder.
+ *
+ * The label carries an optional letter suffix because a pass that splits one
+ * finding after the fact numbers the halves `3a` and `3b` rather than
+ * renumbering every item below them. A pattern accepting digits alone parses
+ * such a file without complaint and drops those items, leaving them
+ * unanswerable through this verb with nothing reporting the gap.
+ */
+const HEADING = /^###\s+(\d+[a-z]*)\.\s*(.*)$/i
+
+/** A bolded field bullet, which is every line an item carries. */
+const FIELD = /^-\s+\*\*([^*]+):\*\*\s*(.*)$/
+
+/**
+ * Any heading, which ends the item above it.
+ *
+ * A numbered `###` is tested first and opens the next item, so what reaches
+ * here is a heading that is not an item and therefore closes the one open. The
+ * narrower test for `##` alone let a `### Notes` block stay inside the item
+ * above it, and the stray slot such a block carries then displaced the real
+ * one, leaving the item reading as answered while its own slot sat empty and
+ * sending a write into the wrong section.
+ */
+const SECTION = /^#{1,6}\s/
+
+export interface IntakeItem {
+  /** The label as the heading spells it, such as `3` or `3a`. */
+  readonly label: string
+  readonly title: string
+  /** Line the heading sits on, 1-based against the whole file. */
+  readonly line: number
+  /** Line the answer slot sits on, absent when the item carries no slot. */
+  readonly answerLine: number | undefined
+  /** Text in the slot, absent when the slot is empty and the item is unread. */
+  readonly answer: string | undefined
+  readonly open: string | undefined
+  readonly suggested: string | undefined
+  readonly worth: string | undefined
+}
+
+interface Draft {
+  label: string
+  title: string
+  line: number
+  answerLine: number | undefined
+  answer: string | undefined
+  open: string | undefined
+  suggested: string | undefined
+  worth: string | undefined
+}
+
+function seal(draft: Draft): IntakeItem {
+  return { ...draft }
+}
+
+/**
+ * Reads every item a cluster file holds, in file order.
+ *
+ * The walk runs over `bodyLines` rather than a raw split so the item format
+ * block a folder copies into its own files parses as the sample it is. A
+ * heading counted out of a fence shifts nothing on its own, but it offers an
+ * answer slot no reader owns and the write-back would land inside the sample.
+ */
+export function readItems(text: string): IntakeItem[] {
+  const items: IntakeItem[] = []
+  let draft: Draft | undefined
+
+  for (const line of bodyLines(text)) {
+    if (line.fenced) continue
+
+    const heading = HEADING.exec(line.text)
+
+    if (heading) {
+      if (draft) items.push(seal(draft))
+      draft = {
+        label: heading[1].toLowerCase(),
+        title: heading[2].trim(),
+        line: line.number,
+        answerLine: undefined,
+        answer: undefined,
+        open: undefined,
+        suggested: undefined,
+        worth: undefined,
+      }
+      continue
+    }
+
+    if (!draft) continue
+
+    if (SECTION.test(line.text)) {
+      items.push(seal(draft))
+      draft = undefined
+      continue
+    }
+
+    const field = FIELD.exec(line.text)
+    if (!field) continue
+
+    const value = field[2].trim()
+
+    switch (field[1].trim().toLowerCase()) {
+      case 'you':
+        draft.answerLine = line.number
+        draft.answer = value === '' ? undefined : value
+        break
+      case 'open':
+        draft.open = value
+        break
+      case 'suggested':
+        draft.suggested = value
+        break
+      case 'worth it':
+        draft.worth = value
+        break
+    }
+  }
+
+  if (draft) items.push(seal(draft))
+
+  return items
+}
+
+/**
+ * Puts a selection in one item's slot, leaving every other line as it was.
+ *
+ * The rewrite replaces the whole line rather than patching inside it, which is
+ * the reason this is a verb at all. A stream editor expands an unescaped
+ * ampersand in the replacement to the whole match and exits zero on a
+ * non-match, so an answer carrying one would rewrite the line it anchored to
+ * and a missed slot would report success with the answer lost.
+ *
+ * The answer occupies one line, and the caller owes that guarantee. A line
+ * break splices a bare continuation into the item matching none of the patterns
+ * the reader tests, so the slot reads back as the text before the break while
+ * the item counts as answered, which puts correcting it behind the refusal on
+ * an item that already carries one.
+ */
+export function writeAnswerLine(
+  text: string,
+  answerLine: number,
+  answer: string,
+): string {
+  const lines = text.split('\n')
+  lines[answerLine - 1] = `- **You:** ${answer}`
+  return lines.join('\n')
+}
+
+/** An item nobody has reached, which is an empty slot rather than a missing one. */
+export function isUnread(item: IntakeItem): boolean {
+  return item.answerLine !== undefined && item.answer === undefined
+}
+
+/**
+ * An item carrying no slot at all, which the format says ships on every one.
+ *
+ * Such an item is neither unread nor answered, and counting it as either hides
+ * it: as answered it drops out of the work a reader is told remains, and as
+ * unread it joins a list whose every entry the answer verb then refuses. It is
+ * reported on its own so the file gets fixed.
+ */
+export function isMalformed(item: IntakeItem): boolean {
+  return item.answerLine === undefined
+}

package/standards/intake.md

@@ -89,6 +89,7 @@ Where an item touches a task already on the board, say so in the index rather th
 ```
 
 - `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
+- Number items per cluster file, and give a finding split after the fact a letter suffix on the number it came from, as in `3a` beside `3`. Renumbering the items below it instead moves every label a reader or an answer already cited.
 - `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default.
 - `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
 
@@ -106,10 +107,18 @@ That inverts the plan file's contract, where a blank answer slot means accept th
 
 Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
 
+A slot is filled two ways. The operator types into the cluster file, or answers in chat and a verb lands the selection on the item. Both put the answer on the item, which is what keeps retrieval working, and neither lets a session decide one. An answer given in conversation and never written back leaves the item unread, since the file rather than the conversation is the record.
+
+An item already carrying an answer is refused rather than overwritten, whichever route the second answer arrives by. A filled slot is a decision already made, and revising one is the operator editing their own line.
+
 ## Retrieval
 
 Answers live on items, so one pass over the folder reports every touched slot.
 
+A session with the toolkit CLI on PATH reads the folder through `aitk intake list`, which reports per-folder counts bare and one folder's items with `--json`, and takes `--unread` to keep only the empty slots. It is the surface under test, and it skips the index and every fenced sample, which the greps below cannot do.
+
+The greps stay for a reader without the CLI, and they overcount by whatever the folder displays in a fence.
+
 ```bash
 awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' *.md
 ```

package/standards/skill.md

@@ -208,7 +208,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 
 ### Output and tuning
 
-- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. Bare filenames are not clickable in the terminal.
+- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.

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.