@erclx/aitk 3.12.1 → 3.13.0

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

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

package/governance/rules/lang/120-bash.md

@@ -0,0 +1,18 @@
+---
+description: Route bash script authoring to the interactive or non-interactive skill, and name the lint gate
+paths:
+  - '**/*.sh'
+---
+
+# Bash standards
+
+## Skill routing
+
+- Use `bash-script` for an interactive or human-facing script: prompts, a visual timeline UI, framed terminal output.
+- Use `cli-script` for a non-interactive script: automation, CI, cron, a pipeline helper, or anything run by an agent rather than watched by a person.
+- Load the matched skill's own reference templates rather than hand-rolling interactivity or logging patterns outside them.
+
+## Lint gate
+
+- Format with `shfmt --write --indent 2` and lint with `shellcheck --severity=warning` before committing a script.
+- Fix a shellcheck finding at the source. Suppress one with a directive comment only for a genuine false positive, and state why beside the suppression.

package/governance/rules/lib/305-e2e-reliability.md

@@ -0,0 +1,34 @@
+---
+description: Enforce settled waits and falsifiable guards in end-to-end tests
+paths:
+  - 'e2e/*.ts'
+  - 'e2e/**/*.ts'
+---
+
+# End-to-end reliability standards
+
+## Waiting
+
+- Settle on the condition a step waits for. Use `expect.poll` or a web-first assertion ahead of any read.
+- Reserve a fixed duration for an assertion that nothing happened across a window.
+- Bound every settle with an explicit timeout.
+- Do not raise a timeout to clear a failure that reproduces under load. Replace the wait with a settle.
+- Do not read a value once after a pause. Poll it.
+
+## Falsifiable guards
+
+- Assert the set under test is non-empty before asserting a property over its members.
+- Raise from an instrument that was refused rather than returning a value a passing assertion accepts.
+- Run a new guard against the defect it was written for, and see it fail, before trusting it.
+- Do not weaken an assertion to clear a failure. Narrow the wait instead.
+
+## Reproducing a failure that only appears in CI
+
+- Reproduce under `Emulation.setCPUThrottlingRate` rather than by rerunning the gate.
+- Read the state the assertion does not: which markers were set, which listeners fired, how far a transition ran.
+- Vary the condition under suspicion deliberately. Do not compare counts across runs that differed in something uncontrolled.
+- Read the check conclusion as its own act. A green diff review reports nothing about the gate.
+
+## Authority
+
+- Follow `.claude/rules/lib/300-testing-ts.md` for framework choice, file placement, and test naming.

package/governance/rules/lib/306-test-scope.md

@@ -0,0 +1,25 @@
+---
+description: Enforce which specs and which engines an end-to-end run covers at each point in the loop
+paths:
+  - 'e2e/*.ts'
+  - 'e2e/**/*.ts'
+---
+
+# Test scope standards
+
+## Selecting a run
+
+- Narrow an end-to-end run by spec path or by test name. Never narrow it by engine.
+- Run one named test while iterating on a behavior: `bun run test:e2e -- -g '<name>'`.
+- Run one surface while iterating on that surface: `bun run test:e2e -- e2e/<area>.spec.ts`.
+- Run `bun run test:e2e:changed` to select specs from the import graph.
+- Run the whole suite before pushing.
+- Pass `--project` in a local run only to reproduce a failure that engine has already reported. The CI matrix passes it on every job, one engine per leg, which is the gate rather than a narrowed run.
+- Do not add a script that pins a default run to one engine.
+
+## Instruments
+
+- Answer a question about the running page with a script against the dev server rather than with the suite.
+- Do not enable `fullyParallel` in `playwright.config.ts`.
+- Follow `.claude/rules/ui/440-surface-capture.md` for capture scope.
+- Follow `.claude/rules/lib/305-e2e-reliability.md` for waits and guards.

package/governance/rules/lib/350-security-web.md

@@ -4,6 +4,7 @@ paths:
   - '**/*.tsx'
   - '**/*.jsx'
   - '**/*.html'
+  - '**/*.astro'
 ---
 
 # Web security standards

package/governance/rules/ui/450-link-behavior.md

@@ -0,0 +1,19 @@
+---
+description: Enforce the same-tab default for an outbound link and for a mail link
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+---
+
+# Link behavior standards
+
+## Default target
+
+- Open a link in the same tab. Reserve `target="_blank"` for a destination that would discard in-progress work if it replaced the current page, such as a document a user is midway through elsewhere.
+- Do not add `target="_blank"` as a default for every external link.
+
+## mailto: links
+
+- Open a `mailto:` link in the same tab. It hands off to the mail client rather than replacing page content, so a new tab leaves an empty tab behind.

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture"]
+rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]

package/governance/stacks/base.toml

@@ -1,4 +1,4 @@
 extends = ""
 # Both folders whole. Every rule authored under them ships to a base consumer,
 # so adding one is a single edit rather than a file and a name here.
-rules = ["core", "claude"]
+rules = ["core", "claude", "120-bash"]

package/governance/stacks/react.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture"]
+rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]

package/package.json

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

package/tooling/web/manifest.toml

@@ -43,6 +43,7 @@ packages = [
 "test:ui" = "vitest --ui"
 "test:coverage" = "vitest run --coverage"
 "test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test"
+"test:e2e:changed" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --only-changed"
 "test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --ui"
 "test:e2e:report" = "playwright show-report"
 "check:full" = "./scripts/verify.sh && bun run test:e2e"

package/tooling/web/reference.md

@@ -103,6 +103,7 @@ Append rows:
 | `bun run test:run` | Run Vitest once with verbose reporter. |
 | `bun run test:coverage` | Run Vitest with coverage. |
 | `bun run test:e2e` | Run Playwright E2E tests. |
+| `bun run test:e2e:changed` | Run Playwright E2E tests for specs the import graph reaches from the current diff. |
 | `bun run screenshot` | Build, preview, then capture screenshots. |
 
 `aitk tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.