@erclx/aitk 0.8.0

package/standards/tasks.md

@@ -0,0 +1,140 @@
+---
+title: Tasks reference
+description: Folder layout, filename convention, and content rules for .claude/tasks/
+---
+
+# Tasks reference
+
+Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task. Update when a task starts, completes, or changes scope. When to open a task at all is project policy, not a shape rule, and lives in `CLAUDE.md`.
+
+The folder is gitignored. Board state changes when work ships rather than when a branch is written, so committing it would put a claim about the future into the diff of an unrelated pull request. The git log records what shipped.
+
+## Layout
+
+```plaintext
+.claude/tasks/
+├── index.md              ← generated, never hand-edited
+├── priority.md           ← hand-maintained execution order
+├── v09.0-sync-paths.md
+└── v13.0-toolkit-drift.md
+```
+
+One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
+
+`index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
+
+`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why the order is what it is belongs in `.claude/ROADMAP.md`, which is committed because that rationale has no substitute record.
+
+Group tasks by readiness rather than by status, one row per task, with a stated column for what each is blocked on. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
+
+The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+
+## Filenames
+
+`vXX.Y-<slug>.md`, where the version is the phase label zero-padded to two digits and the slug is kebab-case.
+
+Padding is load-bearing. Index entries sort by filename and nothing else, so a bare `v9.0` sorts after `v15.0` and the catalog reads out of board order. `standards/versioning.md` governs the label itself and permits free renumbering, so expect the occasional rename. Nothing points at a task filename, since a `Plan:` line runs from task to plan rather than the reverse.
+
+## Frontmatter
+
+Every task file carries both fields. The index walker fails the whole folder when one is missing, which surfaces the gap on the next edit.
+
+```yaml
+---
+title: 'v13.0: Detect and close toolkit drift in target projects'
+description: Record what a target installed and report the delta against the toolkit
+---
+```
+
+- `title`: the phase label and the task title, matching the H1. Quote it, since a leading `vX.Y:` reads as a key to a YAML parser.
+- `description`: what the task achieves, in one line. A session reads this in the index to decide whether to open the file.
+
+## File format
+
+Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable, findings are past and factual, and as flat bullets at the same indent they are visually identical. A heading separates them at no cost. Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
+
+Size the outcomes so one pull request closes all of them. A task whose outcomes span two pull requests ships the first half and leaves the rest open, with nothing recording which outcomes the merged work covered, so the board reads as in-progress work that no branch is carrying. Split the task before handing it off rather than after. This is what `## Archiving` below depends on, since a task closes whole or not at all.
+
+Prefix the H1 with the `vX.Y:` phase label, then a short title whose form depends on the task type:
+
+- Feature: an outcome describing what the user can now do
+- Fix: a problem statement describing what is wrong
+- Chore: an imperative describing what is being done
+
+```markdown
+---
+title: 'vX.Y: Title'
+description: One line on what this task achieves
+---
+
+# vX.Y: Title
+
+Plan: [feature-<slug>](../plans/feature-<slug>.md)
+Groundwork: [<slug>](../.tmp/groundwork/<slug>/)
+Issue: #NNN
+Pull request: #NNN
+
+Why this task exists and what it depends on.
+
+## Outcomes
+
+- [ ] Outcome: what done looks like
+- [ ] Outcome: what done looks like
+
+## Findings
+
+- What constrains the task, dated where it matters.
+
+> Test strategy: <unit | component | e2e | visual | manual>, what is being verified
+```
+
+## Origin
+
+Every task names where it came from, through a `Plan:`, `Groundwork:`, or `Issue:` line under the title. Include each only when the file, folder, or issue it names exists.
+
+A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track or an open issue that no task points at is work already decided and on its way to being forgotten.
+
+`Plan:` and `Groundwork:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.claude/tasks/`, which makes it `../plans/` and `../.tmp/groundwork/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
+
+Phase-label format and where labels may appear are governed by `standards/versioning.md`.
+
+`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../.tmp/plans-archive/feature-<slug>.md`. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it. One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
+
+`Groundwork:` points at `../.tmp/groundwork/<slug>/`, the folder `claude-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
+
+`Pull request:` records which pull request carries the task's work, as a bare `#NNN` the way `Issue:` does. It is not an origin, so a task without one is well-formed. `git-pr` writes it when a pull request opens, which is the one step that always runs whether the chain drives it or a person does.
+
+The line is what lets a merge close its own task. Every merge on `main` is a squash carrying the number in its subject, so the number survives where a branch name does not, and `aitk tasks archive --pull-request <n>` resolves the task from it. Without the line the board can only be swept blind, and a blind sweep cannot tell a shipped task from an abandoned one. One task, one pull request: two tasks naming the same number refuse to archive rather than both moving.
+
+## What goes in
+
+- Task entries describing observable behavior, one outcome per line
+- A test strategy line naming the mechanism and what it verifies
+- Findings stating what constrains the task, including blockers and dependencies
+
+## What does not go in
+
+- Class names, file paths, function names, or prop names in any entry or title
+- Code-level steps or implementation detail. Behavioral specifics are fine.
+- Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `.claude/ARCHITECTURE.md`.
+- Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
+- "In progress" or "Blocked" headings. Note status inline on the outcome instead.
+- Sequencing rationale or which version is active. Those belong in `.claude/ROADMAP.md`, which is committed because that reasoning has no substitute record.
+
+## Archiving
+
+Never delete a task file. A shipped task moves to `.claude/.tmp/task-archive/` under its own name, and the live index regenerates without it. `aitk tasks archive` owns the move, the ordering-row removal, and the index regen as one unit.
+
+Two callers reach that command. The `claude-tasks` skill runs it inside a session, and the `post-merge` hook runs it unattended after a pull that merged the work. Both go through the command rather than moving the file themselves, so the two paths cannot drift into archiving differently. Every gate the command applies refuses with a non-zero exit rather than reporting, because a caller with nobody watching cannot act on a warning.
+
+One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/.tmp/plans-archive/` and stays gitignored, so an archived task does not start appearing in diffs. The cost is that scratch is unbacked, which is the same cost the plans archive already carries.
+
+Archiving a task does not archive its plan. `claude-docs` owns the plans sweep and moves a plan only when the closing task is its last live citation. The archive clears the task's row from `priority.md` itself, since a shipped task left in the ordering reads as ready to hand a worker. It leaves prose naming the task alone for a person to resolve.
+
+The row is matched by the link in its first cell rather than by a pattern against the whole line. A row names the task it is about in the first cell, so a link anywhere after that is a reference, such as a blocker pointing at what it waits on. Matching the line would delete the referring task's row too, on a board that is gitignored and has nothing to recover it from.
+
+Sweep the plan before archiving the task. The sweep finds its work by scanning the live folder, so a task archived first is beyond its reach for good, and the plan is left with no live task citing it and an archived task pointing at a path nothing will retarget. The archive refuses a task whose `Plan:` line still resolves inside `.claude/plans/` for that reason, which puts the ordering under a gate rather than under a convention the unattended caller cannot follow.
+
+That gate resolves the target against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file. `claude-docs` reads the line the same way, and two halves of one ordering that parsed it differently would leave a plan stranded by the form it was written in.
+
+A task with an open outcome stays on the board. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. The sweep is gated on the same condition, so archiving around an open outcome also leaves the plan behind.

package/standards/versioning.md

@@ -0,0 +1,47 @@
+---
+title: Versioning reference
+description: Phase label vs semver discipline across tasks, PRs, commits, and tags
+---
+
+# Versioning reference
+
+Two namespaces, kept separate.
+
+## Phase labels
+
+Internal coordination vocabulary used in the task board and chat.
+
+- Format is project-specific.
+- Used to order work and disambiguate streams during planning.
+- Re-numbers freely as scope shifts. Inserting a half-step between two existing labels (a `v1.5` between `v1` and `v2`) is fine.
+- Does not have to map to any external release.
+
+## Semver tags
+
+External release identity used in git tags and release notes. Independent of phase labels.
+
+- Format is semver: `v<major>.<minor>.<patch>`.
+- Tagged only when a real release is cut.
+- Does not have to map to phase labels. A single semver tag may cover work that carried several internal phase labels.
+
+## Where each appears
+
+| Surface                   | Phase labels | Semver tags                         |
+| ------------------------- | ------------ | ----------------------------------- |
+| `.claude/tasks/`          | yes          | no                                  |
+| Chat with the operator    | yes          | no                                  |
+| PR titles                 | no           | only when the PR cuts a release     |
+| Commit messages           | no           | only when the commit cuts a release |
+| Git tags                  | no           | yes                                 |
+| README and `CHANGELOG.md` | no           | yes                                 |
+
+## Rules
+
+- PR titles describe the user-observable change in conventional-commit form. Do not prefix or suffix with phase labels.
+- Commit subjects do not embed phase labels.
+- Git tags use semver only. Phase labels never become tags.
+- A PR that cuts a release may reference its semver tag in the title or body. Phase labels still do not appear.
+
+## Why
+
+Phase labels keep planning conversations efficient. They make `git log`, PR titles, and the tag list unreadable when they leak in. A future reader cannot reconstruct what an internal label meant without the matching task file, which is gitignored. Semver tags carry meaning independent of conversation state and survive in git history. Keeping the two namespaces apart preserves both.

package/standards/wireframes.md

@@ -0,0 +1,67 @@
+---
+title: Wireframe reference
+description: Shape and content rules for .claude/wireframes/<surface>.md files
+---
+
+# Wireframe reference
+
+Applies to per-surface entries under `.claude/wireframes/`. Skip for `index.md`, which is regenerated by `aitk indexes regen`.
+
+A wireframe file captures the spatial layout and interaction intent of one UI surface. It is not an implementation log. The check for any single line: would it still be true if the surface were rebuilt in a different framework? If not, it belongs in `.claude/context/`.
+
+## What a working wireframe looks like
+
+A wireframe works when someone can rebuild the surface from it without opening the components:
+
+- What is on screen, and where does it sit relative to everything else?
+- Which states can a visitor reach, and what does each one look like?
+- What does it say, word for word?
+
+A wireframe that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, names the surface (`Header`, `Section nav`, `Footer`).
+- `description` (required): one line on when and where the surface appears.
+
+Both fields feed `.claude/wireframes/index.md` when regenerated.
+
+## Layout
+
+- Draw each surface as an ASCII block inside a `plaintext` fence. One fence per distinct layout.
+- Label regions with `←` annotations. Never use `#` for annotations.
+- Show a region's role, not its styling. `← status pill` reads better than a class name or hex value.
+- Keep the grid honest. The ASCII proportions should match the intended widths, since conveying proportion is the wireframe's job.
+
+## Variants
+
+- Add a second fence only when the layout itself changes across a breakpoint or state. A wider gutter alone is not a new layout.
+- Name each variant by what triggers it (`## Desktop (≥768px)`, `## Empty state`), not by an arbitrary label.
+- One H2 per variant. Do not stack unrelated surfaces in one file. Keep one surface per file, indexed by `index.md`.
+
+## Copy
+
+- Carry UI copy verbatim in the ASCII block or a short list below it. The wireframe is the source of truth for on-screen text.
+- Mark copy that is dynamic or templated so a reader does not treat a placeholder as final text.
+
+## Behavior
+
+- Describe interaction intent: what the visitor does, what changes on screen, what each state looks like.
+- State the rule, not the mechanism. `The rail tracks the active section as the visitor scrolls` is intent. The scroll handler, throttle, and observer margins are not.
+- Keep it to a short list. A Behavior section longer than the layout is a sign implementation detail has leaked in.
+
+## What moves to .claude/context/
+
+Implementation detail that answers how the surface is built belongs in a `.claude/context/` entry, not the wireframe:
+
+- Algorithms, event-handler code, and lifecycle ordering
+- Framework component names, props, and CSS class or token names
+- Pixel-exact spacing, timing constants, and observer thresholds
+- Workarounds and rejected approaches
+
+Reference the context entry from the wireframe by path when a reader needs the mechanism. The wireframe stays answerable on its own for layout and intent.
+
+## Maintenance
+
+- When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
+- ASCII blocks sit inside fenced code, so the prose-standards hook ignores them. The Behavior and Copy prose around them is still prose. Follow `standards/prose.md`.

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

@@ -0,0 +1,17 @@
+import react from '@astrojs/react'
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'astro/config'
+import path from 'path'
+
+export default defineConfig({
+  integrations: [react()],
+  site: process.env.ASTRO_SITE,
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: {
+        '@': path.resolve('./src'),
+      },
+    },
+  },
+})

package/tooling/astro/configs/eslint.config.js

@@ -0,0 +1,79 @@
+import js from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import astro from 'eslint-plugin-astro'
+import prettier from 'eslint-config-prettier'
+import checkFile from 'eslint-plugin-check-file'
+import reactHooks from 'eslint-plugin-react-hooks'
+import simpleImportSort from 'eslint-plugin-simple-import-sort'
+import vitest from 'eslint-plugin-vitest'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig([
+  globalIgnores([
+    'dist',
+    '.astro',
+    'coverage',
+    '.claude',
+    '.vscode',
+    '.husky',
+    'test-results',
+    'playwright-report',
+    'blob-report',
+    'playwright/.cache',
+  ]),
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...astro.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: {
+      'simple-import-sort': simpleImportSort,
+      'check-file': checkFile,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
+      ],
+      'check-file/filename-naming-convention': [
+        'error',
+        { '**/*.{ts,tsx,astro}': 'KEBAB_CASE' },
+        { ignoreMiddleExtensions: true },
+      ],
+      'check-file/folder-naming-convention': [
+        'error',
+        { 'src/**/!(__tests__|pages)': 'KEBAB_CASE' },
+      ],
+    },
+  },
+  {
+    files: ['**/*.{jsx,tsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+    },
+  },
+  {
+    files: ['*.config.{js,mjs,cjs,ts}', 'astro.config.mjs'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
+    ...vitest.configs.recommended,
+  },
+  prettier,
+])

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

@@ -0,0 +1,25 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const isCI = !!process.env.CI
+
+export default defineConfig({
+  testDir: 'e2e',
+  forbidOnly: isCI,
+  retries: isCI ? 2 : 0,
+  workers: isCI ? 1 : undefined,
+  reporter: isCI ? 'list' : 'html',
+  use: {
+    trace: 'on-first-retry',
+    baseURL: 'http://localhost:4321',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+  ],
+  webServer: {
+    command: 'bun run build && bun run preview',
+    url: 'http://localhost:4321',
+    reuseExistingServer: !isCI,
+  },
+})

package/tooling/astro/configs/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "astro.config.mjs", "e2e", "playwright.config.ts"],
+  "exclude": ["dist", ".astro", "vitest.config.ts"]
+}

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

@@ -0,0 +1,22 @@
+import { getViteConfig } from 'astro/config'
+
+export default getViteConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['src/test/setup.ts'],
+    passWithNoTests: true,
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.astro/**',
+      '**/e2e/**',
+      '**/.{idea,git,cache,output,temp}/**',
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'src/test/setup.ts', 'e2e/', '**/*.astro'],
+    },
+  },
+})

package/tooling/astro/manifest.toml

@@ -0,0 +1,32 @@
+[stack]
+name = "astro"
+extends = "web"
+runtime = "bun"
+scaffold = "bun create astro@latest {{name}} -- --template minimal --typescript strict --no-install --no-git --skip-houston --yes"
+
+[dependencies.dev]
+packages = [
+  "astro",
+  "@astrojs/react",
+  "@astrojs/check",
+  "eslint-plugin-astro",
+  "astro-eslint-parser",
+  "prettier-plugin-astro",
+]
+
+[scripts]
+"dev" = "astro dev"
+"build" = "astro check && astro build"
+"preview" = "astro preview"
+"astro" = "astro"
+"typecheck" = "astro check"
+"setup" = "./scripts/setup.sh"
+
+[scripts.override]
+"screenshot" = "PREVIEW_PORT=4321 bash scripts/screenshot.sh"
+
+[gitignore]
+"# Astro" = [".astro/"]
+
+[verify]
+prepare = "bunx astro add react --yes"

package/tooling/astro/reference.md

@@ -0,0 +1,60 @@
+# Tooling Astro reference
+
+> Extends: `web`. Apply web stack first.
+
+## Overview
+
+The astro stack covers Astro + TypeScript projects: content sites, marketing sites, blogs, and docs. Interactive islands use React only. Output is static. It ships golden configs for `astro.config.mjs`, `vitest.config.ts` (using `getViteConfig` from `astro/config`), `playwright.config.ts` (preview-server backed), a `tsconfig.json` that extends `astro/tsconfigs/strict`, and an `eslint.config.js` that overrides the web layer's config to include `eslint-plugin-astro` and exclude React-refresh rules.
+
+## Scaffold checklist
+
+1. Scaffold with `bunx create-astro@latest`. Choose `TypeScript: Strict`. Skip git init and install.
+2. Add React integration: `bunx astro add react`. Do not use `astro add tailwind`. That command installs the v3 integration. Tailwind v4 arrives via the web manifest.
+3. Install web tooling: `aitk tooling sync web .`
+4. Install astro adapter: `aitk tooling sync astro .`
+5. Extend `.claude/context/ci.md` and `.claude/context/development.md` per the web reference's extend sections plus the astro rows below.
+6. Run `bun run lint:fix` then `bun run check`.
+
+## 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.
+- `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/`.
+- `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.
+
+## Typecheck
+
+`astro check` replaces `tsc --noEmit` because `tsc` cannot parse `.astro` files. `build` runs `astro check && astro build`.
+
+## Vitest scope
+
+Unit-test React island components (`.tsx`) only. Do not test `.astro` files. Page-level behavior is verified by Playwright against rendered output.
+
+Vitest is pinned to `^3` in the web manifest. Vitest `^4` bundles rolldown-vite (vite@8), which ignores the esbuild JSX config in `@vitejs/plugin-react` and breaks `.tsx` tests, plus emits deprecation warnings. Unpin once `@astrojs/react` ships a rolldown-aware plugin (or astro's bundled vite reaches 8).
+
+## Setup script
+
+- File: `scripts/setup.sh`. Destructive: deletes `.git` and self-removes after running. Run once immediately after scaffolding.
+- Prompt for project name, normalize to kebab-case, derive title-cased display name.
+- Update `package.json` name and version, inject verify/clean/update scripts, remove setup.
+- Update `astro.config.mjs`: set `site` if provided.
+- Update `<title>` and `<meta name="description">` in the default layout.
+
+## Prettier (extend)
+
+Add `prettier-plugin-astro` first in plugins, then `prettier-plugin-tailwindcss` last (per its docs). Add a parser override for `.astro` files.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run dev` | Start the Astro dev server on port 4321. |
+| `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. |
+| `bun run typecheck` | Run `astro check`. |
+
+## CI docs (extend)
+
+In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.

package/tooling/base/configs/.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*.sh]
+indent_style = space
+indent_size = 2

package/tooling/base/configs/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Summary
+
+<Action Verb> <Direct Object> to <Result>.
+
+## Key Changes
+
+- <Verb> <specific component/file/function> (<reason if non-obvious>)
+- <Verb> <specific component/file/function>
+
+<!-- ## Technical Context (optional, omit for docs/config/trivial changes) -->
+<!-- - <Why this approach was taken, not what changed> -->
+
+## Testing
+
+- [ ] <Specific command or test case>
+- [ ] <Edge case verified>
+
+<!-- Visuals: include only if clarifying architecture, UI, or complex logic flows -->

package/tooling/base/configs/.github/workflows/verify.yml

@@ -0,0 +1,35 @@
+name: Verify
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  static-checks:
+    name: 🛡️ Static Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install Shell Tools
+        run: sudo apt-get install -y shfmt shellcheck
+
+      - name: Check Formatting
+        run: bun run check:format
+
+      - name: Check Spelling
+        run: bun run check:spell
+
+      - name: Check Shell
+        run: bun run check:shell

package/tooling/base/configs/.husky/commit-msg

@@ -0,0 +1 @@
+bunx commitlint --edit "$1"

package/tooling/base/configs/.husky/post-merge

@@ -0,0 +1,61 @@
+#!/usr/bin/env sh
+
+# Names archive candidates after a pull merges work in.
+#
+# Every step before the merge fires from a chain and the archive fires when a
+# person remembers, so shipped tasks accumulate on a board that reads as ready
+# to hand a worker. This is the only event that lands after a merge.
+#
+# Candidates rather than closed tasks, because an all-`[x]` board entry does not
+# mean the work merged. `claude-docs` marks outcomes on the branch as step 1 of
+# the ship chain, so a task can read closed while its pull request is still open
+# or already abandoned. The board is gitignored and an archived task has nothing
+# to recover it, so `claude-tasks` confirms the work is on `main` before moving
+# anything and this output says so rather than implying the check is done.
+#
+# It announces and never moves a file. The board is gitignored, so a shell-side
+# archive leaves no diff to review with nobody watching, and `index.md` is
+# regenerated by a session-scoped hook that a `mv` from a shell never fires.
+#
+# Husky runs this as `sh -e`, so the shebang is advisory and any bare command
+# returning non-zero aborts the hook and prints a husky failure. Keep every
+# test inside an `if` condition, which errexit exempts.
+
+root=$(git worktree list --porcelain 2>/dev/null | grep -m 1 '^worktree ' | cut -d' ' -f2-) || root=''
+[ -n "$root" ] || exit 0
+
+# The board is shared scratch at the main worktree root, and `git worktree
+# list` puts that root first. A pull inside a linked worktree fires this same
+# hook, so trusting the working directory would read a board that is not there.
+board="$root/.claude/tasks"
+[ -d "$board" ] || exit 0
+
+closed=""
+count=0
+
+for file in "$board"/*.md; do
+  [ -f "$file" ] || continue
+
+  case "$file" in
+  */index.md | */priority.md) continue ;;
+  esac
+
+  # Gate on the same condition both archive verbs gate on: at least one closed
+  # outcome and none open. A file carrying no outcomes at all falls out here,
+  # which is what keeps notes on the board from being announced as tasks.
+  if grep -q '^- \[ \]' "$file"; then
+    continue
+  fi
+
+  if grep -q '^- \[x\]' "$file"; then
+    closed="$closed  $(basename "$file" .md)
+"
+    count=$((count + 1))
+  fi
+done
+
+[ "$count" -gt 0 ] || exit 0
+
+printf '\n📋 %s archive candidate(s) on the board:\n%s\n' "$count" "$closed"
+printf 'Outcomes are marked on the branch, so each still needs its work confirmed\n'
+printf 'on main. Run /claude-tasks, which checks that and sweeps the plan first.\n\n'

package/tooling/base/configs/.husky/post-rewrite

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+
+# Runs the `post-merge` board check for anyone pulling with rebase.
+#
+# `git pull` under `pull.rebase=true` runs `git rebase`, which fires this event
+# and never `post-merge`. Without this the trigger is a silent no-op on that
+# machine, which is the wrong failure mode for a hook whose whole purpose is to
+# stop a shipped task being forgotten. The base stack ships both hooks to every
+# target, where the pull style is not something this repository controls.
+#
+# Only the `rebase` argument delegates. `post-rewrite` also fires on
+# `commit --amend`, which rewrites nothing on the board and would print the
+# candidate list on an ordinary amend.
+
+[ "$1" = "rebase" ] || exit 0
+
+hook="$(dirname "$0")/post-merge"
+[ -f "$hook" ] || exit 0
+
+# shellcheck source=/dev/null
+. "$hook"