Initial Commit

openspec/changes/enterprise-gaming-behavior-tree/proposal.md

@@ -0,0 +1,160 @@
+# OpenSpec Change: enterprise-gaming-behavior-tree
+
+- **Change ID**: enterprise-gaming-behavior-tree
+- **Package**: `@suaveplan/behavior-tree`
+- **Category**: gaming/ai
+- **Target path**: `gaming/ai/behavior-tree`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/behavior-tree.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/behavior-tree` on the genesis branch from scratch at enterprise quality. The package provides a behavior tree engine with composite nodes (Sequence, Selector, Parallel), decorator nodes (Inverter, Repeater, Cooldown, Timeout), leaf nodes (Action, Condition, Wait), a typed Blackboard for shared agent state, and a fluent builder API. `BehaviorTreeRunner` advances the tree one tick at a time returning `SUCCESS | FAILURE | RUNNING`. Genesis adds Zod blackboard key schemas, structured errors, OTel tick-duration histogram, injectable clock, and property tests for tree traversal invariants.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis yet — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `BehaviorTreeError`; `BT.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock` |
+| `zod` (`catalog:forms`) | Blackboard key schemas |
+| `@opentelemetry/api` (`catalog:observability`) | Tick duration histogram |
+
+---
+
+## Public API surface
+
+```ts
+type NodeStatus = 'SUCCESS' | 'FAILURE' | 'RUNNING'
+
+interface TreeNode {
+  readonly name: string
+  tick(blackboard: Blackboard, dt: number): NodeStatus
+  reset(): void
+}
+
+// Composites
+function sequence(name: string, children: TreeNode[]): TreeNode
+function selector(name: string, children: TreeNode[]): TreeNode
+function parallel(name: string, children: TreeNode[], successPolicy?: 'all' | 'any', failurePolicy?: 'all' | 'any'): TreeNode
+
+// Decorators
+function inverter(name: string, child: TreeNode): TreeNode
+function repeater(name: string, child: TreeNode, times?: number): TreeNode   // undefined = forever
+function cooldown(name: string, child: TreeNode, cooldownSeconds: number, clock?: Clock): TreeNode
+function timeout(name: string, child: TreeNode, timeoutSeconds: number, clock?: Clock): TreeNode
+
+// Leaves
+function action(name: string, fn: (bb: Blackboard, dt: number) => NodeStatus): TreeNode
+function condition(name: string, fn: (bb: Blackboard) => boolean): TreeNode
+function wait(name: string, durationSeconds: number, clock?: Clock): TreeNode
+
+// Blackboard
+function createBlackboard<T extends Record<string, unknown>>(initial?: Partial<T>): Blackboard<T>
+
+interface Blackboard<T extends Record<string, unknown> = Record<string, unknown>> {
+  get<K extends keyof T>(key: K): T[K] | undefined
+  set<K extends keyof T>(key: K, value: T[K]): void
+  has(key: keyof T): boolean
+  delete(key: keyof T): void
+  clear(): void
+  clone(): Blackboard<T>
+}
+
+// Runner
+function createBehaviorTreeRunner(root: TreeNode, blackboard: Blackboard, clock?: Clock): BehaviorTreeRunner
+
+interface BehaviorTreeRunner {
+  tick(dt: number): NodeStatus
+  reset(): void
+  readonly lastStatus: NodeStatus | null
+  readonly tickCount: number
+}
+
+// Fluent builder
+function bt(name: string): BehaviorTreeBuilder
+```
+
+### Error codes
+
+```ts
+type BtErrorCode =
+  | 'BT_EMPTY_COMPOSITE'
+  | 'BT_BLACKBOARD_KEY_NOT_FOUND'
+  | 'BT_NODE_TICK_FAILED'
+  | 'BT_INVALID_POLICY'
+```
+
+---
+
+## New additions for genesis
+
+1. **Parallel policies** — configurable success/failure policies for parallel composite.
+2. **Cooldown decorator** — injectable clock; skips subtree when cooldown active, returns `FAILURE`.
+3. **Timeout decorator** — returns `FAILURE` if child runs longer than timeout.
+4. **Blackboard clone** — `clone()` for subtree isolation in parallel branches.
+5. **OTel** — `bt.tick_duration_ms` histogram; `bt.node_status_total` counter by status.
+
+---
+
+## File layout
+
+```text
+gaming/ai/behavior-tree/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      blackboard/
+        blackboard.ts
+        blackboard.md
+        blackboard.types.ts
+        blackboard.test.ts
+        index.ts
+      nodes/
+        composites.ts
+        composites.md
+        composites.test.ts
+        decorators.ts
+        decorators.md
+        decorators.test.ts
+        leaves.ts
+        leaves.md
+        leaves.test.ts
+      runner/
+        runner.ts
+        runner.md
+        runner.types.ts
+        runner.test.ts
+        index.ts
+    builder/
+      builder.ts
+      builder.md
+      builder.test.ts
+      index.ts
+  tests/
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/npc` builds per-NPC behavior trees; `@suaveplan/r3f-npc` renders debug tree overlays. Prerequisites: `@suaveplan/error`, `@suaveplan/types`.

openspec/changes/enterprise-gaming-behavior-tree/tasks.md

@@ -0,0 +1,60 @@
+# Tasks: enterprise-gaming-behavior-tree
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/ai/behavior-tree/` (`@suaveplan/behavior-tree`, `0.1.0`, `sideEffects: false`)
+- [ ] `tsconfig.json`, `vitest.config.ts`
+
+## Phase 2 — Error codes & constants
+
+- [ ] `src/error-codes.ts` + `src/constants/index.ts`
+
+## Phase 3 — Types
+
+- [ ] `src/types/common.ts` + `common.md`
+
+## Phase 4 — Blackboard
+
+- [ ] `src/core/blackboard/blackboard.ts` — get/set/has/delete/clear/clone
+- [ ] Tests + docs
+
+## Phase 5 — Leaf nodes
+
+- [ ] `src/core/nodes/leaves.ts` — `action`, `condition`, `wait` with clock
+- [ ] Tests + docs
+
+## Phase 6 — Composite nodes
+
+- [ ] `src/core/nodes/composites.ts` — `sequence`, `selector`, `parallel` with success/failure policies
+- [ ] Tests + docs
+
+## Phase 7 — Decorator nodes
+
+- [ ] `src/core/nodes/decorators.ts` — `inverter`, `repeater`, `cooldown`, `timeout`
+- [ ] Tests + docs
+
+## Phase 8 — Runner
+
+- [ ] `src/core/runner/runner.ts` — tick loop, reset, OTel histogram, lastStatus
+- [ ] Tests + docs
+
+## Phase 9 — Fluent builder
+
+- [ ] `src/builder/builder.ts` — `bt()` chainable API producing `TreeNode` tree
+- [ ] Tests + docs
+
+## Phase 10 — Property tests
+
+- [ ] `tests/property.test.ts` — sequence: all-success → SUCCESS; selector: first-success → SUCCESS; parallel policies
+
+## Phase 11 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/behavior-tree` green
+- [ ] 100% coverage
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/behavior-tree`