loki-mode 6.60.0 → 6.62.0

package/state/test_manager.ts

@@ -0,0 +1,366 @@
+/**
+ * Tests for TypeScript State Manager
+ *
+ * Run with: npx ts-node state/test_manager.ts
+ * Or with Deno: deno run --allow-read --allow-write state/test_manager.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+import {
+  StateManager,
+  StateChange,
+  ManagedFile,
+  getStateDiff,
+  getStateManager,
+  resetStateManager,
+  ConflictStrategy,
+  VersionVector,
+  PendingUpdate,
+  ConflictInfo,
+} from "./manager";
+
+// Test helpers
+function assert(condition: boolean, message: string): void {
+  if (!condition) {
+    throw new Error(`Assertion failed: ${message}`);
+  }
+}
+
+function assertEqual<T>(actual: T, expected: T, message: string): void {
+  const actualStr = JSON.stringify(actual);
+  const expectedStr = JSON.stringify(expected);
+  if (actualStr !== expectedStr) {
+    throw new Error(
+      `Assertion failed: ${message}\n  Expected: ${expectedStr}\n  Actual: ${actualStr}`
+    );
+  }
+}
+
+// Test runner
+async function runTests(): Promise<void> {
+  // Create temp directory
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "state-manager-test-"));
+  const lokiDir = path.join(tempDir, ".loki");
+
+  console.log("Testing StateManager (TypeScript)...");
+
+  try {
+    // Test: Manager initialization
+    const manager = new StateManager({ lokiDir, enableWatch: false, enableEvents: false });
+    assert(fs.existsSync(path.join(lokiDir, "state")), "state directory should exist");
+    assert(fs.existsSync(path.join(lokiDir, "queue")), "queue directory should exist");
+    console.log("  [PASS] Manager initialized");
+
+    // Test: set_state
+    const change1 = manager.setState("test.json", { key: "value" });
+    assertEqual(change1.changeType, "create", "should be create");
+    assertEqual(change1.newValue, { key: "value" }, "should have new value");
+    console.log("  [PASS] setState works");
+
+    // Test: get_state
+    const result1 = manager.getState("test.json");
+    assertEqual(result1, { key: "value" }, "should get state");
+    console.log("  [PASS] getState works");
+
+    // Test: update_state
+    const change2 = manager.updateState("test.json", { another: "field" });
+    assertEqual(
+      change2.newValue,
+      { key: "value", another: "field" },
+      "should merge updates"
+    );
+    console.log("  [PASS] updateState works");
+
+    // Test: ManagedFile enum
+    manager.setState(ManagedFile.ORCHESTRATOR, { phase: "planning" });
+    const result2 = manager.getState(ManagedFile.ORCHESTRATOR);
+    assertEqual(result2, { phase: "planning" }, "should work with enum");
+    console.log("  [PASS] ManagedFile enum works");
+
+    // Test: subscriptions
+    const changes: StateChange[] = [];
+    const subscription = manager.subscribe((change) => {
+      changes.push(change);
+    });
+    manager.setState("sub-test.json", { data: 123 });
+    assertEqual(changes.length, 1, "should receive change");
+    console.log("  [PASS] Subscriptions work");
+
+    subscription.dispose();
+    manager.setState("sub-test.json", { data: 456 });
+    assertEqual(changes.length, 1, "should not receive after dispose");
+    console.log("  [PASS] Unsubscribe works");
+
+    // Test: convenience methods
+    manager.setOrchestratorState({ phase: "dev" });
+    assertEqual(manager.getOrchestratorState(), { phase: "dev" }, "orchestrator state");
+    console.log("  [PASS] Convenience methods work");
+
+    // Test: getStateDiff
+    const diff = getStateDiff({ a: 1, b: 2 }, { a: 1, c: 3 });
+    assertEqual(diff.added, { c: 3 }, "diff added");
+    assertEqual(diff.removed, { b: 2 }, "diff removed");
+    assertEqual(diff.changed, {}, "diff changed");
+    console.log("  [PASS] getStateDiff works");
+
+    // Test: delete_state
+    manager.setState("to-delete.json", { temp: true });
+    const change3 = manager.deleteState("to-delete.json");
+    assert(change3 !== null, "should return change");
+    assertEqual(change3!.changeType, "delete", "should be delete");
+    const result3 = manager.getState("to-delete.json");
+    assert(result3 === null, "should be null after delete");
+    console.log("  [PASS] deleteState works");
+
+    // Test: corrupted JSON handling
+    const corruptedPath = path.join(lokiDir, "corrupted.json");
+    fs.writeFileSync(corruptedPath, "{ this is not valid json }");
+    const resultCorrupted = manager.getState("corrupted.json");
+    assert(resultCorrupted === null, "corrupted JSON should return null");
+    console.log("  [PASS] Corrupted JSON handling works");
+
+    // Test: empty file handling
+    const emptyPath = path.join(lokiDir, "empty.json");
+    fs.writeFileSync(emptyPath, "");
+    const resultEmpty = manager.getState("empty.json");
+    assert(resultEmpty === null, "empty file should return null");
+    console.log("  [PASS] Empty file handling works");
+
+    // Test: partial/truncated JSON handling
+    const partialPath = path.join(lokiDir, "partial.json");
+    fs.writeFileSync(partialPath, '{"key": "value", "incomplete":');
+    const resultPartial = manager.getState("partial.json");
+    assert(resultPartial === null, "partial JSON should return null");
+    console.log("  [PASS] Partial JSON handling works");
+
+    // Test: corrupted JSON with default value
+    const resultWithDefault = manager.getState("corrupted.json", { fallback: true });
+    assertEqual(resultWithDefault, { fallback: true }, "should return default for corrupted");
+    console.log("  [PASS] Corrupted JSON with default works");
+
+    // Cleanup
+    manager.stop();
+
+    console.log("");
+    console.log("All basic TypeScript tests passed!");
+
+    // Run optimistic update tests
+    await runOptimisticUpdateTests();
+
+  } finally {
+    // Cleanup temp directory
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+// Optimistic Update Tests (SYN-014)
+async function runOptimisticUpdateTests(): Promise<void> {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "optimistic-test-"));
+  const lokiDir = path.join(tempDir, ".loki");
+
+  console.log("");
+  console.log("Testing Optimistic Updates (SYN-014)...");
+
+  try {
+    // Test: VersionVector
+    console.log("  Testing VersionVector...");
+    const vv1 = new VersionVector();
+    vv1.increment("source1");
+    assert(vv1.get("source1") === 1, "version should be 1");
+    vv1.increment("source1");
+    assert(vv1.get("source1") === 2, "version should be 2");
+    assert(vv1.get("nonexistent") === 0, "nonexistent should be 0");
+    console.log("  [PASS] VersionVector increment works");
+
+    // Test: VersionVector merge
+    const vv2 = new VersionVector();
+    vv2.increment("source2");
+    vv2.increment("source2");
+    const merged = vv1.merge(vv2);
+    assert(merged.get("source1") === 2, "merged source1 should be 2");
+    assert(merged.get("source2") === 2, "merged source2 should be 2");
+    console.log("  [PASS] VersionVector merge works");
+
+    // Test: VersionVector concurrent
+    const vvA = new VersionVector();
+    vvA.increment("agentA");
+    const vvB = new VersionVector();
+    vvB.increment("agentB");
+    assert(vvA.concurrentWith(vvB), "should be concurrent");
+    console.log("  [PASS] VersionVector concurrent detection works");
+
+    // Test: VersionVector dominates
+    const vvDom1 = new VersionVector();
+    vvDom1.increment("source1");
+    vvDom1.increment("source1");
+    const vvDom2 = new VersionVector();
+    vvDom2.increment("source1");
+    assert(vvDom1.dominates(vvDom2), "vvDom1 should dominate vvDom2");
+    assert(!vvDom2.dominates(vvDom1), "vvDom2 should not dominate vvDom1");
+    console.log("  [PASS] VersionVector dominates works");
+
+    // Test: serialization
+    const vvSer = new VersionVector({ source1: 3, source2: 2 });
+    const dict = vvSer.toDict();
+    const vvDeser = VersionVector.fromDict(dict);
+    assert(vvDeser.get("source1") === 3, "deserialized source1 should be 3");
+    assert(vvDeser.get("source2") === 2, "deserialized source2 should be 2");
+    console.log("  [PASS] VersionVector serialization works");
+
+    // Test: StateManager optimistic updates
+    const manager = new StateManager({ lokiDir, enableWatch: false, enableEvents: false });
+
+    // Test: basic optimistic update
+    const pending = manager.optimisticUpdate("test.json", "key1", "value1", "agent1");
+    assert(pending.status === "pending", "should be pending");
+    assert(pending.key === "key1", "key should match");
+    assert(pending.value === "value1", "value should match");
+
+    const state = manager.getState("test.json");
+    assert(state !== null && state.key1 === "value1", "value should be applied");
+    console.log("  [PASS] optimisticUpdate works");
+
+    // Test: version tracking
+    manager.optimisticUpdate("test.json", "key2", "value2", "agent2");
+    const vv = manager.getVersionVector("test.json");
+    assert(vv.get("agent1") === 1, "agent1 version should be 1");
+    assert(vv.get("agent2") === 1, "agent2 version should be 1");
+    console.log("  [PASS] Version tracking works");
+
+    // Test: pending updates tracking
+    const pendingList = manager.getPendingUpdates("test.json");
+    assert(pendingList.length === 2, "should have 2 pending updates");
+    console.log("  [PASS] Pending updates tracking works");
+
+    // Test: conflict detection
+    const manager2 = new StateManager({
+      lokiDir: path.join(tempDir, ".loki2"),
+      enableWatch: false,
+      enableEvents: false,
+    });
+    manager2.optimisticUpdate("conflict.json", "key1", "local_value", "agent1");
+
+    const remoteState = {
+      key1: "remote_value",
+      _version_vector: { agent2: 1 },
+    };
+
+    const conflicts = manager2.detectConflicts("conflict.json", remoteState, "agent2");
+    assert(conflicts.length === 1, "should have 1 conflict");
+    assert(conflicts[0].key === "key1", "conflict key should be key1");
+    assert(conflicts[0].localValue === "local_value", "local value should match");
+    assert(conflicts[0].remoteValue === "remote_value", "remote value should match");
+    console.log("  [PASS] Conflict detection works");
+
+    // Test: conflict resolution - last write wins
+    manager2.setConflictStrategy(ConflictStrategy.LAST_WRITE_WINS);
+    const resolved = manager2.resolveConflicts("conflict.json", conflicts);
+    assert(resolved.key1 === "remote_value", "remote value should win");
+    assert(conflicts[0].resolution === "last_write_wins", "resolution should be last_write_wins");
+    console.log("  [PASS] Last-write-wins resolution works");
+
+    // Test: conflict resolution - merge for dicts
+    const manager3 = new StateManager({
+      lokiDir: path.join(tempDir, ".loki3"),
+      enableWatch: false,
+      enableEvents: false,
+    });
+    manager3.optimisticUpdate("merge.json", "config", { a: 1, b: 2 }, "agent1");
+    manager3.setConflictStrategy(ConflictStrategy.MERGE);
+
+    const remoteDict = {
+      config: { b: 3, c: 4 },
+      _version_vector: { agent2: 1 },
+    };
+
+    const dictConflicts = manager3.detectConflicts("merge.json", remoteDict, "agent2");
+    const resolvedDict = manager3.resolveConflicts("merge.json", dictConflicts);
+    const mergedConfig = resolvedDict.config as Record<string, number>;
+    assert(mergedConfig.a === 1, "merged a should be 1");
+    assert(mergedConfig.b === 3, "merged b should be 3 (remote wins)");
+    assert(mergedConfig.c === 4, "merged c should be 4");
+    console.log("  [PASS] Merge resolution for dicts works");
+
+    // Test: commit pending updates
+    const manager4 = new StateManager({
+      lokiDir: path.join(tempDir, ".loki4"),
+      enableWatch: false,
+      enableEvents: false,
+    });
+    manager4.optimisticUpdate("commit.json", "key1", "value1", "agent1");
+    manager4.optimisticUpdate("commit.json", "key2", "value2", "agent1");
+
+    const committed = manager4.commitPendingUpdates("commit.json");
+    assert(committed === 2, "should commit 2 updates");
+
+    const remaining = manager4.getPendingUpdates("commit.json");
+    assert(remaining.length === 0, "should have no pending updates");
+    console.log("  [PASS] Commit pending updates works");
+
+    // Test: rollback pending updates
+    const manager5 = new StateManager({
+      lokiDir: path.join(tempDir, ".loki5"),
+      enableWatch: false,
+      enableEvents: false,
+    });
+    const originalState = { original: true };
+    manager5.setState("rollback.json", originalState);
+
+    manager5.optimisticUpdate("rollback.json", "key1", "value1", "agent1");
+    manager5.optimisticUpdate("rollback.json", "key2", "value2", "agent1");
+
+    const rolledBack = manager5.rollbackPendingUpdates("rollback.json", originalState);
+    assert(rolledBack === 2, "should rollback 2 updates");
+
+    const restoredState = manager5.getState("rollback.json");
+    assertEqual(restoredState, originalState, "state should be restored");
+    console.log("  [PASS] Rollback pending updates works");
+
+    // Test: sync with remote
+    const manager6 = new StateManager({
+      lokiDir: path.join(tempDir, ".loki6"),
+      enableWatch: false,
+      enableEvents: false,
+    });
+    manager6.setState("sync.json", { existing: "value" });
+    manager6.optimisticUpdate("sync.json", "local_key", "local_value", "agent1");
+
+    const syncRemote = {
+      existing: "value",
+      remote_key: "remote_value",
+      _version_vector: { agent2: 1 },
+    };
+
+    const { resolvedState, conflicts: syncConflicts, committed: syncCommitted } =
+      manager6.syncWithRemote("sync.json", syncRemote, "agent2");
+
+    assert(syncConflicts.length === 0, "should have no conflicts (different keys)");
+    assert(syncCommitted === 1, "should commit 1 update");
+    assert(resolvedState.local_key === "local_value", "local key should be preserved");
+    console.log("  [PASS] Sync with remote works");
+
+    // Cleanup managers
+    manager.stop();
+    manager2.stop();
+    manager3.stop();
+    manager4.stop();
+    manager5.stop();
+    manager6.stop();
+
+    console.log("");
+    console.log("All Optimistic Update tests passed!");
+
+  } finally {
+    // Cleanup temp directory
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+// Run tests
+runTests().catch((err) => {
+  console.error("Test failed:", err);
+  process.exit(1);
+});

package/templates/README.md

@@ -11,6 +11,9 @@ claude --dangerously-skip-permissions
 
 # Or via CLI
 ./autonomy/run.sh templates/e-commerce.md
+
+# Or scaffold a new project from a template
+loki init my-project --template saas-starter
 ```
 
 ## Templates
@@ -27,12 +30,20 @@ claude --dangerously-skip-permissions
 
 | Template | Description | Tech Stack | Est. Time |
 |----------|-------------|------------|-----------|
+| [rest-api.md](rest-api.md) | REST API with CRUD, pagination, filtering, Swagger docs (no auth) | Express, TypeScript, Prisma, SQLite | 25-35 min |
 | [rest-api-auth.md](rest-api-auth.md) | REST API with JWT auth, registration, login, refresh, rate limiting | Express/FastAPI, PostgreSQL, JWT, bcrypt | 30-45 min |
-| [full-stack-demo.md](full-stack-demo.md) | Bookmark manager with tags, search, and filtering | React, Express, SQLite, TailwindCSS | 30-60 min |
 | [cli-tool.md](cli-tool.md) | File organizer CLI with subcommands, config, watch mode, undo | Node.js, Commander.js, chalk, chokidar | 30-45 min |
 | [discord-bot.md](discord-bot.md) | Moderation bot with slash commands, auto-mod, reaction roles | discord.js, SQLite, node-cron | 45-60 min |
 | [chrome-extension.md](chrome-extension.md) | Tab manager extension with groups, sessions, search, memory monitor | Manifest V3, vanilla JS, Chrome APIs | 30-45 min |
 | [blog-platform.md](blog-platform.md) | Blog with markdown CMS, categories, RSS feed, SEO | Next.js, CodeMirror, SQLite, TailwindCSS | 45-60 min |
+| [full-stack-demo.md](full-stack-demo.md) | Bookmark manager with tags, search, and filtering | React, Express, SQLite, TailwindCSS | 30-60 min |
+| [web-scraper.md](web-scraper.md) | Configurable scraper with pagination, robots.txt, multi-format export | Python, httpx, BeautifulSoup4, SQLite | 30-45 min |
+| [data-pipeline.md](data-pipeline.md) | ETL pipeline with multi-source ingestion, transforms, monitoring | Python, Pydantic, SQLAlchemy, Click | 30-45 min |
+| [dashboard.md](dashboard.md) | Real-time analytics dashboard with charts, tables, drag-and-drop layout | React, Recharts, TanStack Table, WebSocket | 45-60 min |
+| [game.md](game.md) | Browser-based 2D game with enemy AI, scoring, levels, high scores | HTML5 Canvas, TypeScript, Web Audio API | 30-45 min |
+| [slack-bot.md](slack-bot.md) | Slack bot with slash commands, events, interactive messages, scheduling | Node.js, Bolt SDK, SQLite | 30-45 min |
+| [npm-library.md](npm-library.md) | npm package with TypeScript, dual ESM/CJS, tree shaking, auto docs | TypeScript, tsup, Vitest, typedoc | 30-45 min |
+| [microservice.md](microservice.md) | Containerized service with health checks, logging, Prometheus metrics | Express, TypeScript, Docker, Prisma, pino | 30-45 min |
 
 ### Complex
 
@@ -57,6 +68,7 @@ Every template follows a consistent structure:
 - **Requirements** - Non-functional requirements
 - **Testing** - Test strategy and coverage expectations
 - **Out of Scope** - Explicit boundaries to prevent scope creep
+- **Acceptance Criteria** - Measurable conditions for each feature
 - **Success Criteria** - How to know when it is done
 - **Purpose Footer** - What aspect of Loki Mode this template exercises
 
@@ -69,12 +81,15 @@ Every template follows a consistent structure:
 **Building something real?** Pick the template closest to your goal and customize it. The complex templates (`saas-starter.md`, `e-commerce.md`, `ai-chatbot.md`) are production-grade starting points.
 
 **Testing specific agent types:**
-- Frontend agent: `static-landing-page.md`, `chrome-extension.md`
-- Backend agent: `api-only.md`, `rest-api-auth.md`, `discord-bot.md`
+- Frontend agent: `static-landing-page.md`, `chrome-extension.md`, `dashboard.md`
+- Backend agent: `api-only.md`, `rest-api.md`, `rest-api-auth.md`, `microservice.md`
 - Full-stack agent: `full-stack-demo.md`, `blog-platform.md`
-- DevOps/CLI agent: `cli-tool.md`
+- DevOps/CLI agent: `cli-tool.md`, `data-pipeline.md`
+- Bot agent: `discord-bot.md`, `slack-bot.md`
 - Mobile agent: `mobile-app.md`
 - AI/ML agent: `ai-chatbot.md`
+- Game agent: `game.md`
+- Library agent: `npm-library.md`
 
 ## Customizing Templates
 

package/templates/dashboard.md

@@ -33,6 +33,51 @@ A real-time analytics dashboard that visualizes key business metrics with intera
 - Responsive design tested at 3 breakpoints (mobile, tablet, desktop)
 - Accessibility: all charts have aria labels, tables are keyboard navigable
 
+## Project Structure
+```
+/
+├── src/
+│   ├── components/
+│   │   ├── charts/            # Line, bar, pie, area chart components
+│   │   ├── tables/            # Data table with sorting and filtering
+│   │   ├── layout/            # Dashboard grid, drag-and-drop wrapper
+│   │   └── controls/          # Date picker, export buttons, filters
+│   ├── hooks/
+│   │   ├── useWebSocket.ts    # Real-time data subscription
+│   │   └── useLayout.ts       # Layout persistence (localStorage)
+│   ├── services/
+│   │   └── api.ts             # Mock data API client
+│   ├── types/
+│   │   └── index.ts           # Shared TypeScript types
+│   ├── App.tsx
+│   └── main.tsx
+├── server/
+│   ├── index.ts               # Express + WebSocket server
+│   └── mockData.ts            # Sample metrics generator
+├── tests/
+│   ├── charts.test.tsx        # Chart rendering tests
+│   └── e2e/                   # Playwright tests
+├── package.json
+└── README.md
+```
+
+## Out of Scope
+- Real database or data warehouse connections
+- User authentication or multi-tenant dashboards
+- Server-side rendering
+- PDF report generation
+- Alerting or notification rules
+- Historical data backfill
+- Custom chart builder UI
+
+## Acceptance Criteria
+- All four chart types (line, bar, pie, area) render with correct data
+- Date range filter applies to every widget on the dashboard
+- WebSocket pushes update visible charts without page refresh
+- Layout changes via drag-and-drop persist after browser reload
+- CSV export matches displayed table data exactly
+- PNG export captures the selected chart at screen resolution
+
 ## Success Metrics
 - Dashboard loads with sample data and renders all chart types
 - Date range filter updates all widgets simultaneously

package/templates/data-pipeline.md

@@ -33,6 +33,51 @@ An ETL data pipeline that ingests data from multiple sources, transforms it thro
 - Incremental processing verified across multiple runs
 - Dead letter queue captures all failure categories
 
+## Project Structure
+```
+/
+├── src/
+│   ├── pipeline/
+│   │   ├── runner.py          # Pipeline execution engine
+│   │   ├── transforms.py      # Built-in transform functions
+│   │   └── validators.py      # Schema validation logic
+│   ├── sources/
+│   │   ├── csv_source.py      # CSV file reader
+│   │   ├── json_source.py     # JSON API reader
+│   │   └── db_source.py       # PostgreSQL reader
+│   ├── sinks/
+│   │   └── loader.py          # Target data store writer
+│   ├── monitoring/
+│   │   └── metrics.py         # Processing metrics collector
+│   ├── cli.py                 # Click CLI entrypoint
+│   └── config.py              # YAML config loader
+├── pipelines/
+│   └── example.yaml           # Sample pipeline definition
+├── tests/
+│   ├── test_transforms.py     # Transform function tests
+│   ├── test_validators.py     # Schema validation tests
+│   └── test_pipeline.py       # Integration tests
+├── pyproject.toml
+└── README.md
+```
+
+## Out of Scope
+- Real-time streaming (Kafka, Kinesis)
+- Distributed processing (Spark, Dask)
+- Web-based pipeline builder UI
+- Data lineage or provenance tracking
+- Alerting integrations (PagerDuty, Slack)
+- Cloud-native deployment (Airflow, Dagster)
+- Data catalog or discovery features
+
+## Acceptance Criteria
+- Pipeline definition in YAML configures sources, transforms, and sinks
+- CSV, JSON, and database sources each read data correctly
+- Invalid records are routed to the dead letter queue with error details
+- Incremental mode skips previously processed records on re-run
+- Metrics report records processed, errors, and elapsed time
+- Cron scheduling triggers pipeline runs at configured intervals
+
 ## Success Metrics
 - Pipeline processes sample dataset end-to-end without errors
 - Invalid records quarantined with descriptive error messages

package/templates/game.md

@@ -33,6 +33,54 @@ A browser-based 2D game with player controls, enemy AI, scoring, levels, and per
 - Controls responsive on both keyboard and touch (mobile)
 - No memory leaks during extended play sessions
 
+## Project Structure
+```
+/
+├── src/
+│   ├── engine/
+│   │   ├── game.ts            # Main game loop and state machine
+│   │   ├── renderer.ts        # Canvas rendering layer
+│   │   ├── input.ts           # Keyboard and touch input handler
+│   │   └── audio.ts           # Web Audio API wrapper
+│   ├── entities/
+│   │   ├── player.ts          # Player sprite and controls
+│   │   ├── enemy.ts           # Enemy types and AI patterns
+│   │   └── projectile.ts      # Bullets and projectiles
+│   ├── systems/
+│   │   ├── collision.ts       # AABB collision detection
+│   │   ├── scoring.ts         # Score and level progression
+│   │   └── highscores.ts      # LocalStorage leaderboard
+│   ├── assets/
+│   │   ├── sprites/           # Sprite images
+│   │   └── sounds/            # Sound effect files
+│   ├── main.ts                # Entry point
+│   └── config.ts              # Game constants and key bindings
+├── tests/
+│   ├── collision.test.ts      # Collision detection tests
+│   └── scoring.test.ts        # Score and level logic tests
+├── index.html
+├── package.json
+└── README.md
+```
+
+## Out of Scope
+- Multiplayer or networked gameplay
+- 3D rendering or WebGL
+- Level editor or user-generated content
+- Achievements or progression system beyond levels
+- Mobile app packaging (Capacitor, Electron)
+- Analytics or telemetry
+- In-app purchases or monetization
+
+## Acceptance Criteria
+- Game transitions through menu, playing, paused, and game-over states
+- Player movement responds within one frame of input
+- At least three enemy types exhibit distinct movement patterns
+- Collision detection correctly identifies overlapping sprites
+- Score increases on enemy defeat and displays on screen
+- High score table persists across browser sessions
+- Sound effects play on collision, shoot, and level-up events
+
 ## Success Metrics
 - Game starts, plays, and ends with proper state transitions
 - Player can move, shoot, and interact with enemies

package/templates/microservice.md

@@ -34,6 +34,55 @@ A containerized microservice with health checks, structured logging, graceful sh
 - Graceful shutdown completes within timeout
 - Metrics endpoint serves valid Prometheus format
 
+## Project Structure
+```
+/
+├── src/
+│   ├── app.ts                 # Express app setup, middleware stack
+│   ├── server.ts              # Entry point with graceful shutdown
+│   ├── config/
+│   │   └── index.ts           # Env-based config with validation
+│   ├── middleware/
+│   │   ├── requestId.ts       # Correlation ID injection
+│   │   ├── healthCheck.ts     # Liveness and readiness probes
+│   │   └── metrics.ts         # Prometheus metrics collection
+│   ├── routes/
+│   │   └── items.ts           # Example resource routes
+│   ├── repositories/
+│   │   └── itemRepo.ts        # Repository pattern data access
+│   ├── logger.ts              # pino structured logger
+│   └── types/
+│       └── index.ts           # Shared types
+├── prisma/
+│   ├── schema.prisma          # Database schema
+│   └── migrations/            # Database migrations
+├── tests/
+│   ├── items.test.ts          # API integration tests
+│   └── healthCheck.test.ts    # Health probe tests
+├── Dockerfile                 # Multi-stage build
+├── docker-compose.yml         # Local dev with PostgreSQL
+├── package.json
+└── README.md
+```
+
+## Out of Scope
+- Service mesh or sidecar proxy configuration
+- Message queue integration (RabbitMQ, Kafka)
+- API gateway or load balancer setup
+- Distributed tracing (OpenTelemetry spans)
+- Secret management (Vault, AWS Secrets Manager)
+- Kubernetes manifests or Helm charts
+- CI/CD pipeline configuration
+
+## Acceptance Criteria
+- Docker image builds with multi-stage Dockerfile under 150MB
+- GET /health/live returns 200 immediately after startup
+- GET /health/ready returns 200 only when database is connected
+- All request logs are valid JSON containing a correlation ID
+- SIGTERM triggers graceful shutdown: stops accepting new connections and drains existing ones
+- GET /metrics returns valid Prometheus exposition format
+- Environment variables validated on startup; missing required vars cause exit 1
+
 ## Success Metrics
 - Service starts in Docker and responds to API requests
 - Health probes return healthy status after startup