wpkernel · pipewrk · Oct 7, 2025 · Oct 6, 2025 · Oct 6, 2025 · Oct 7, 2025
diff --git a/.bin/watchman b/.bin/watchman
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# Minimal stub to disable real watchman usage in sandboxed environments.
+# Always respond with an empty sockname so clients fall back to node watchers.
+if [[ "$1" == "--no-pretty" && "$2" == "get-sockname" ]]; then
+	printf '{ "version": "stub", "sockname": "" }\n'
+	exit 0
+fi
+
+# Return failure for any other commands to avoid unexpected behaviour.
+printf 'watchman stub: command not supported\n' >&2
+exit 1
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -60,17 +60,13 @@ Tick any public packages this PR changes functionally.
 
 ## Release
 
-Choose one and include a changeset summary (edit if scope grows).
+Choose one and document in CHANGELOG.md files.
 
-- [ ] **patch** — bugfixes / alignment
-- [ ] **minor** — feature sprint (default)
-- [ ] **major** — breaking API
+- [ ] **patch** — bugfixes / alignment (0.x.1)
+- [ ] **minor** — feature sprint (default) (0.x.0)
+- [ ] **major** — breaking API (x.0.0)
 
-> Create/update changeset:
->
-> ```bash
-> pnpm cs:new:minor "Sprint 5: Bindings & Interactivity (Block Bindings, Interactivity API, providers)"
-> ```
+> Update CHANGELOG.md files in affected packages with summary of changes.
 >
 > _If infra/docs-only, add label **no-release**._
 
@@ -79,6 +75,6 @@ Choose one and include a changeset summary (edit if scope grows).
 - [ ] Tests pass (`pnpm test`, where relevant: `pnpm e2e`)
 - [ ] Lint passes (`pnpm lint`)
 - [ ] Types pass (`pnpm typecheck`, `pnpm typecheck:tests`)
-- [ ] Changeset added/updated (or PR labelled `no-release`)
+- [ ] CHANGELOG.md updated in affected packages (or PR labelled `no-release`)
 - [ ] Docs updated (site/README)
 - [ ] Examples updated (if API changed)
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -45,13 +45,11 @@ WordPress plugin demonstrating a complete jobs & applications system that exerci
 
 1. **Before starting**: Always update sprint docs and share your understanding of current scope with user
 2. **PR creation**: ALWAYS use `.github/PULL_REQUEST_TEMPLATE.md` - never create ad-hoc PRs
-3. **Changeset required**: One changeset per sprint (use `pnpm cs:new:minor "Sprint N: headline"`)
+3. **CHANGELOG updates**: Update CHANGELOG.md files in affected packages with changes
 4. **Roadmap alignment**: Link PR to roadmap section and sprint doc/spec
 5. **Branch management**: Delete branch when PR is merged
 6. **Issue tracking**: Ensure GitHub issue exists for new task before creating branch
 
-See [RELEASING.md](../RELEASING.md) for complete release workflow.
-
 ## Core Code Practices
 
 ### Type Safety

diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -45,14 +45,4 @@ pnpm prettier --write '**/*.md' --log-level=error > /dev/null 2>&1
 node scripts/normalize-punctuation.js > /dev/null 2>&1
 git add '**/*.md'
 
-# Check for changeset (only on feature branches)
-BRANCH=$(git branch --show-current)
-case "$BRANCH" in
-  sprint-*|feat/*|fix/*)
-    if [ -z "$(ls .changeset/*.md 2>/dev/null | grep -v README)" ]; then
-      echo ""
-      echo "⚠️  No changeset found. Consider: pnpm changeset"
-      echo ""
-    fi
-    ;;
-esac
+# Note: Manual versioning - update CHANGELOG.md files in affected packages before committing
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,178 +1,84 @@
 # AGENTS.md - WP Kernel
 
-> 💡 For human contributors: see [DEVELOPMENT.md](./DEVELOPMENT.md) for setup, workflow, and environment details.  
-> This file focuses on agent/contribution rules.
-
-**Purpose**: Operational guide for coding agents (Codex, etc.) working on WP Kernel. Follow the commands and constraints below. Finish only when checks are green and diffs are minimal.
-
-## Project Overview (for agents)
-
-- **Architecture**: Rails-like WordPress framework. **JS is source of truth**; PHP is a thin bridge (REST + capabilities + optional server bindings).
-- **Core primitives**: Actions (orchestrate writes), Resources (transport + stores + cache keys + events), Views (blocks + bindings + Interactivity API), Jobs (background).
-- **Non-negotiables**
-    - UI never calls transport directly. **All writes flow through Actions.**
-    - Events must use **canonical registry names**. No ad-hoc events.
-    - Errors are typed `KernelError` subclasses. Never throw a plain `Error`.
-
-## Monorepo Layout
-
-```
-packages/
-	wp-kernel/            # core framework (resources, actions, events, jobs)
-	wp-kernel-ui/         # UI components & design system
-	wp-kernel-cli/        # scaffolding & DX tools
-	wp-kernel-e2e-utils/  # e2e utilities (validated via showcase)
-app/
-	showcase/             # demo plugin exercising full kernel
-docs/                   # public API docs & guides
-information/            # product spec, example plugin specs, roadmap, event taxonomy
-```
+## Scope & Precedence
 
-## Environment & Tooling
-
-- **Node**: v20.x LTS or higher (minimum for Vite 7). **pnpm** workspace.
-- **WordPress**: 6.8+ required (Script Modules API is core to framework).
-- **Development environments**: wp-env (Docker + PHP 8.1+) OR WordPress Playground (WASM, no Docker).
-- **E2E testing**: Optional. Only needed if writing/running E2E tests (uses Playwright + `@geekist/wp-kernel-e2e-utils`).
-
-- **Commands** (always use exactly these):
-    - Install: `pnpm install`
-    - Format/lint: `pnpm lint --fix` (or `pnpm format`)
-    - Typecheck (code): `pnpm typecheck`
-    - Typecheck (tests): `pnpm typecheck:tests`
-    - Test (all): `pnpm test`
-        > Do **not** use `--filter` for tests; it breaks our harness.
-    - Build (if needed): `pnpm build`
-
-    - **When running agents (Codex, Co‑Pilot, etc.) inside private containers or CI**, set the environment variable `CI=1` before running any `git` or `pnpm` commands. This ensures non-interactive behaviour and avoids prompts that could block automation.
-
-    - **Note:** The pre-commit hook may take some time to complete. It performs typechecks and tests before allowing a commit. Contributors should wait patiently until it finishes.
-
-**When in doubt**: run install → typecheck → tests → lint fix → tests again.
-
----
-
-## Definition of Done (DoD)
-
-1. `pnpm typecheck` and `pnpm typecheck:tests` pass.
-2. `pnpm test` is green and **coverage does not regress**:
-    - ≥95% statements/lines, ≥98% functions globally.
-    - Branch coverage median ≥90% (file-level dips acceptable if global median holds).
-3. New public APIs covered, error paths tested.
-4. No `any` types introduced; project/test globals updated if needed (`global.d.ts`, `tests/test-globals.d.ts`).
-5. Follow folder conventions:
-
-```
-
-app/
-resources/  # defineResource()
-actions/    # defineAction()
-views/      # bindings + Interactivity
-jobs/       # defineJob()
-
-```
-
----
-
-## File & Refactor Guards
-
-- Keep modules/tests under **500 lines**. If approaching the limit:
-- Extract utilities/interfaces or split modules.
-- Before large refactors, open a planning comment and summarise the split.
-
----
-
-## Action & Resource Patterns (enforced)
-
-- **Actions-first**. Example:
-
-```ts
-import { CreateThing } from '@/app/actions/Thing/Create';
-await CreateThing({ data: formData });
-```
-
-- **Resources**: one `defineResource()` defines client, store, cache keys, events.
-- **Events**: import from the canonical registry only.
+This document provides operational guidance for coding agents (Codex, etc.) working on WP Kernel. Follow the commands and constraints below. Complete tasks only when checks are green and diffs are minimal.
 
----
+## Project Architecture & Invariants
 
-## PHP Bridge
+- Rails-like WordPress framework: **JS is source of truth**; PHP acts as a thin transport and capability bridge.
+- Core primitives: Actions (handle writes), Resources (transport, stores, cache keys, events), Views (blocks, bindings, Interactivity API), Jobs (background).
+- Non-negotiables:
+    - UI never calls transport directly; **all writes flow through Actions**.
+    - Use only **canonical registry event names**; no ad-hoc events.
+    - Errors must be typed `KernelError` subclasses; never throw plain `Error`.
 
-- Treat PHP as a strict transport/capability contract. No business logic drift.
-- If changing types across PHP/JS, stop and raise a comment with a migration note.
+## Project Structure & Module Organisation
 
----
+- The repo is a monorepo with multiple packages under `packages/`.
+- Each package uses `src/` for source code, `tests/` for tests, and `types/` for TypeScript definitions.
+- Modules have clear separation of concerns and minimal cross-package dependencies.
+- Avoid deep imports across packages (e.g., no direct imports from `packages/*/src/**`).
+- Use explicit exports and imports to maintain encapsulation and module boundaries.
 
-## Test Strategy
-
-- **E2E tests are optional** for framework users - only needed if contributing or writing E2E tests for your own project.
-- Target e2e realism. `@geekist/wp-kernel-e2e-utils` is validated **via** `app/showcase` e2e; do not unit-test `e2e-utils` in isolation.
-- Flaky tests: prefer serial mode or better selectors/cleanup over sleeps.
-
----
-
-## Coverage Hotspots
-
-- Keep `error`, `http`, and `resource` core near **100%**.
-- Defensive branches that are genuinely hard to reach are acceptable if documented.
-
----
-
-## Commit, PR, and Review Protocol
+## Environment & Tooling
 
-- Small, cohesive commits. One concern per commit.
-- **ALWAYS use the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`) - never create ad-hoc PRs
-- PR title format: Sprint headline (e.g., "Sprint 5: Bindings & Interactivity")
-- Link to Roadmap section and Sprint doc/spec in PR description
-- Include changeset unless labelled `no-release` (see [RELEASING.md](./RELEASING.md))
-- Before requesting review: run `pnpm lint --fix && pnpm typecheck && pnpm typecheck:tests && pnpm test`.
+- Node v20.x LTS or higher (required for Vite 7).
+- WordPress 6.8+ (Script Modules API required).
+- Development environments: `wp-env` (Docker + PHP 8.1+) or WordPress Playground (WASM, no Docker).
+- E2E testing is optional; uses Playwright and `@geekist/wp-kernel-e2e-utils`.
+- Commands:
+    - Install: `pnpm install`
+    - Format/lint: `pnpm lint --fix` and `pnpm format`
+    - Typecheck code: `pnpm typecheck`
+    - Typecheck tests: `pnpm typecheck:tests`
+    - Test all: `pnpm test` (do not use `--filter`)
+    - Build: `pnpm build` (if needed)
+- We have `types/globals.d.ts`, `tests/test-globals.d.ts`, and stubs in `tests/test-utils/wp.ts` for typing and testing support. Use these and update incrementally as needed.
+- When running agents (Codex, Co-Pilot, etc.) inside private containers or CI, set `CI=1` before running any `git` commands to ensure non-interactive behavior.
+
+## Quality & Coverage
+
+- Maintain ≥95% statements/lines and ≥98% functions coverage globally.
+- Branch coverage median ≥90% (some file-level dips allowed if global median holds).
+- Keep core modules (error, http, resource) near 100% coverage.
+- Defensive branches that are hard to reach are acceptable if documented.
+- Avoid flaky tests; use serial mode or improved selectors/cleanup instead of sleeps.
+
+## Workflow & Policies
+
+- Definition of Done (DoD):
+    - Pass `pnpm typecheck` and `pnpm typecheck:tests`.
+    - Pass `pnpm test` with no coverage regression.
+    - Test new public APIs and error paths.
+    - No `any` types introduced; update globals if needed.
+    - Follow folder conventions.
+- Always run before requesting review:
+  `pnpm lint --fix && pnpm typecheck && pnpm typecheck:tests && pnpm test`
+
+## Commit & PR Guidelines
+
+- Make small, focused commits (one concern per commit).
+- Always use the PR template (`.github/PULL_REQUEST_TEMPLATE.md`).
+- PR title format: Sprint headline (e.g., "Sprint 5: Bindings & Interactivity").
+- Link to Roadmap section and Sprint doc/spec in PR description.
 - Respond to all review feedback; avoid duplication; extract interfaces when suggested.
 
----
-
 ## Agent Execution Policy (Codex)
 
-- **Approval mode**: default to read/write in workspace. Ask before:
+- Default to read/write in workspace.
+- Ask before:
     - Writing outside workspace, changing dotfiles, or enabling network access.
     - Installing new dev dependencies.
-    - Creating or modifying PRs (always use PR template)
-
-- **Never**: run destructive commands, alter Git history, or publish artefacts.
-- **PR creation**: Always use `.github/PULL_REQUEST_TEMPLATE.md` - no ad-hoc PRs
+    - Creating or modifying PRs (always use PR template).
+- Never run destructive commands, alter Git history, or publish artifacts.
 - Always show plan, then diffs, then run checks. Close task only after DoD passes.
 
----
-
-## Package-specific Notes
-
-- `wp-kernel-e2e-utils`: treated as a support lib; validated by showcase e2e only.
-- `wp-kernel-ui`: respect design tokens and component boundaries; add stories if created.
-- `wp-kernel-cli`: keep scaffolds idempotent; snapshot tests preferred.
-
----
-
-## Typical Flows
-
-### Bug fix
-
-1. Reproduce with a focused test.
-2. Minimal fix in the smallest package.
-3. Run full checks; ensure coverage does not drop.
-4. Add a short regression test name: `fix: <symptom>`.
-
-### Feature
-
-1. Add/extend Actions and Resources first; wire Views via bindings.
-2. Emit canonical events; update cache invalidation.
-3. Add tests; update docs if API changed.
-
----
-
 ## What NOT to do
 
-- ✗ Call transport from UI components
-- ✗ Create ad-hoc event names
-- ✗ Deep-import across packages (`packages/*/src/**`)
-- ✗ Use `any` or throw plain `Error`
-- ✗ Skip cache invalidation after writes
-- ✗ Ignore TS errors or coverage regressions
+- Call transport from UI components.
+- Create ad-hoc event names.
+- Deep-import across packages (`packages/*/src/**`).
+- Use `any` or throw plain `Error`.
+- Skip cache invalidation after writes.
+- Ignore TypeScript errors or coverage regressions.