23min · 23min · May 3, 2026 · May 3, 2026
diff --git a/.ai b/.ai
diff --git a/.ai-repo/.framework-sync-sha b/.ai-repo/.framework-sync-sha
@@ -0,0 +1 @@
+3efad83e7b63bfefda429796b15e84b7cd64b806
diff --git a/.ai-repo/README.md b/.ai-repo/README.md
@@ -0,0 +1,42 @@
+# Project-Specific AI Configuration
+
+This directory holds AI framework extensions specific to **this repository**.
+The shared framework lives in `.ai/` (submodule). This directory is repo-local.
+
+## Structure
+
+```
+.ai-repo/
+├── config/    ← structured repo-owned artifact layout config
+├── skills/    ← project-specific skill checklists
+├── rules/     ← project-specific conventions and constraints
+└── README.md  ← you are here
+```
+
+## Config
+
+The canonical repo-owned artifact layout lives in `.ai-repo/config/artifact-layout.json`.
+It defines the effective roadmap path, epic spec filename, milestone spec path template,
+tracking doc path template, completed epic archive path, and naming patterns for this repo.
+
+Generated assistant surfaces should mirror the resolved values from this file; they should not be the source of truth for layout.
+
+## Skills
+
+Add a `.md` file in `skills/` with a checklist format (see `.ai/skills/` for examples).
+Project skills are automatically picked up by `bash .ai/setup.sh` and distributed
+to platform adapters (Copilot, Claude, Codex).
+
+Examples of project-specific skills:
+- `deploy-to-azure.md` — deployment runbook for this project
+- `run-pipeline.md` — how to trigger the CI/CD pipeline
+- `data-export.md` — how to export fixture data from production
+
+## Rules
+
+Add a `.md` file in `rules/` for project-specific conventions:
+- `tech-stack.md` — "Use xUnit, NSubstitute, .NET 9"
+- `naming.md` — "Services use I{Name} interface pattern"
+- `testing.md` — "All tests use [Theory] for parameterized cases"
+
+These are referenced by platform adapters so the AI reads them automatically.
diff --git a/.ai-repo/config/artifact-layout.json b/.ai-repo/config/artifact-layout.json
@@ -0,0 +1,10 @@
+{
+  "roadmapPath": "ROADMAP.md",
+  "epicRootPath": "work/epics/",
+  "epicSpecFileName": "spec.md",
+  "milestoneSpecPathTemplate": "work/epics/<epic>/<milestone-id>.md",
+  "trackingDocPathTemplate": "work/epics/<epic>/<milestone-id>-tracking.md",
+  "completedEpicPathTemplate": "work/epics/completed/<epic>/",
+  "epicIdPattern": "E-{NN}",
+  "milestoneIdPattern": "m-E{NN}-<MM>-<slug>"
+}
diff --git a/.ai-repo/config/commit.json b/.ai-repo/config/commit.json
@@ -0,0 +1,7 @@
+{
+  "coAuthors": {
+    "claude":  "Claude Opus 4.7 (1M context) <noreply@anthropic.com>",
+    "copilot": "GitHub Copilot <noreply@github.com>",
+    "codex":   "OpenAI Codex <noreply@openai.com>"
+  }
+}
diff --git a/...ad-code-audit/recipes/dead-code-dotnet.md → .ai-repo/recipes/dead-code-dotnet.md b/...ad-code-audit/recipes/dead-code-dotnet.md → .ai-repo/recipes/dead-code-dotnet.md
diff --git a/...dead-code-audit/recipes/dead-code-rust.md → .ai-repo/recipes/dead-code-rust.md b/...dead-code-audit/recipes/dead-code-rust.md → .ai-repo/recipes/dead-code-rust.md
diff --git a/...ode-audit/recipes/dead-code-typescript.md → .ai-repo/recipes/dead-code-typescript.md b/...ode-audit/recipes/dead-code-typescript.md → .ai-repo/recipes/dead-code-typescript.md
diff --git a/.ai-repo/rules/project.md b/.ai-repo/rules/project.md
@@ -0,0 +1,126 @@
+# FlowTime Project Rules
+
+Project-specific conventions for the FlowTime mono-repo (Engine + Sim + UI).
+
+---
+
+## Tooling
+
+- Prefer precise edits; stick to established patterns and avoid broad refactors without context.
+- Use `rg`/`fd` for searches.
+
+## Project Layout
+
+- `src/FlowTime.Core`, `src/FlowTime.API`, `src/FlowTime.Cli`, `src/FlowTime.Contracts`, `src/FlowTime.Adapters.Synthetic` — Engine surface.
+- `src/FlowTime.Sim.Core`, `src/FlowTime.Sim.Service`, `src/FlowTime.Sim.Cli` — Simulation surface.
+- `src/FlowTime.UI`, `src/FlowTime.UI.Tests` — Blazor WebAssembly UI.
+- `tests/` mirrors project names (e.g., `tests/FlowTime.Core.Tests`, `tests/FlowTime.Sim.Tests`, `tests/FlowTime.Api.Tests`).
+- `docs/` — Engine/shared documentation. `docs-sim/` is archived — ignore unless explicitly requested.
+- `work/` — AI framework housekeeping: epics, epic-local milestone specs/tracking docs, gaps, decisions.
+
+## Workflow Artifact Layout
+
+- The canonical artifact layout for this repo is defined in `.ai-repo/config/artifact-layout.json`.
+- Older `*-log.md` files are historical and may remain until the related epic/docs are actively migrated.
+- `work/milestones/` is a compatibility stub only. Do not create active specs or logs there.
+- `ROADMAP.md` is the framework roadmap path.
+- `work/epics/epic-roadmap.md` can remain as a supplemental epic index/sequencing document while it is still useful.
+
+## Milestone Status Sync
+
+- Milestone start and wrap must reconcile status across all repo-owned status surfaces in one pass: milestone spec, milestone tracking doc, epic milestone table (`work/epics/<epic>/spec.md`), `ROADMAP.md`, `work/epics/epic-roadmap.md` when it mentions the epic, and `CLAUDE.md` current work.
+- Do not leave an earlier milestone marked `in-progress` or `pending` once a later milestone in the same epic has started on a continuation branch.
+- Treat status-surface drift as a workflow bug, not optional housekeeping.
+
+## Coding Conventions
+
+- .NET 9 / C# 13 with implicit usings and nullable enabled.
+- Private fields **must use camelCase without a leading underscore** (`private readonly string dataDirectory;`).
+- Follow existing patterns before introducing new abstractions; check for shared contracts in `FlowTime.Contracts`.
+- Keep CLI ↔ API behaviour aligned; update relevant `.http` examples and docs when changing endpoints.
+- Use invariant culture for parsing/formatting; keep tests deterministic.
+- JSON payloads and schemas use camelCase — do not introduce snake_case fields.
+- Never reintroduce deprecated schema fields (e.g., `binMinutes`); current schema uses `{ bins, binSize, binUnit }`.
+- When inserting inline code containing `|` inside Markdown tables, escape the pipe as `\|`.
+
+## Branching & Versioning
+
+- Epic integration branches use `epic/E-{NN}-<slug>`. Every numbered epic gets an integration branch; milestone branches branch from it and merge back into it.
+- Milestone branches use `milestone/<milestone-id>`.
+- Feature branches use `feature/<surface>-<milestone-id>/<desc>` when a milestone needs parallel work.
+- Single-surface quick changes can branch from `main` and PR directly back to `main` when no milestone integration branch is needed.
+- Conventional commits: `feat(api):`, `fix(sim):`, `docs:`, etc.
+- Commit messages: conventional prefix, no icons/emoji; subject + short bullet body capturing the milestone and key work/tests touched.
+- Version format `<major>.<minor>.<patch>[-pre]`; milestone completions typically bump minor (e.g., `0.6.0 → 0.7.0`).
+- Release notes in `docs/releases/` with milestone-based naming (e.g., `SIM-M2.7-v0.6.0.md`).
+
+## Build & Run
+
+- `dotnet build FlowTime.sln` / `dotnet test FlowTime.sln`
+- VS Code tasks: `build`, `test`, `start-api`, `stop-api`, `start-sim-api`, `stop-sim-api`, `start-ui`, `stop-ui`
+- Engine API: `dotnet run --project src/FlowTime.API` → port 8081
+- Sim API: `dotnet run --project src/FlowTime.Sim.Service` with `ASPNETCORE_URLS=http://0.0.0.0:8090`
+- UI: `dotnet run --project src/FlowTime.UI`
+- Default ports: 8081 (Engine API), 8090 (Sim API), 5219/7047 (UI), 8091 (Sim diagnostics), 5091 (Engine dev profile)
+- Build and test before handing work back.
+
+## Devcontainer Port Safety
+
+- **Never blindly kill all processes on port 8081** — the devcontainer port-forwarder listens there; killing it destroys the session.
+- To free port 8081, filter by process name: only kill `dotnet` processes.
+- Use the `kill-port-8081` VS Code task — it filters safely.
+- Verify processes before killing: `lsof -ti:PORT`, `ps aux | grep`. Use `pkill -f "ProcessName"` or `lsof -ti:PORT | xargs -r kill -TERM`. Never `kill <PORT>`.
+- Send SIGTERM first, wait, then SIGKILL only if still alive. Never start with `kill -9`.
+
+## Testing
+
+- Unit tests: fast and deterministic; no network or file-system side effects.
+- API tests: use `WebApplicationFactory<Program>`; prefer real dependencies over mocks.
+- Sim tests: `tests/FlowTime.Sim.Tests` — covers CLI, template parsing, provenance, service behaviours.
+- Integration tests: `tests/FlowTime.Integration.Tests` for cross-surface scenarios.
+
+### UI testing (hard rule)
+
+- **UI work must be eval'd end-to-end in a real browser.** Every milestone that ships new or changed UI (Blazor or Svelte) must include Playwright tests that drive the feature in a real browser and verify the rendered outcome. Type checks and unit tests on pure helpers are necessary but not sufficient — they do not catch broken event handlers, state leaks, reactive glitches, or CSS-driven breakage. The user experience is the contract; a passing test must prove the user experience works.
+- **Playwright infrastructure lives at `tests/ui/`** with config at `tests/ui/playwright.config.ts`, specs under `tests/ui/specs/`, and helpers under `tests/ui/helpers/`. Add new specs alongside existing ones.
+- **Graceful skip when infrastructure is down.** If the API or dev server isn't running, the spec should skip with a clear message rather than fail. Follow the existing pattern used by the Rust engine integration tests (health probe → skip on unavailable).
+- **Svelte UI runs on port 5173** (vite dev). **Blazor UI runs on port 5219**. Override `baseURL` per-spec if needed.
+- **Vitest covers pure logic.** Svelte/TS pure functions (helpers, store derivations, protocol encoding) should have vitest unit tests in `ui/src/**/*.test.ts`. These run fast and guard the foundation; Playwright guards the integration.
+- **Cover the critical paths.** For each user-facing surface: (1) page loads and renders expected initial state, (2) at least one user interaction drives a visible change, (3) reset/undo/error-recovery paths behave correctly, (4) key latency or correctness metrics that the UI exposes actually display correct values.
+
+## Truth Discipline
+
+### Precedence (highest to lowest)
+1. **Code + passing tests** define live truth.
+2. **`work/decisions.md`** defines approved direction.
+3. **Epic specs and epic-local milestone specs** under `work/epics/` define implementation target, within their scope.
+4. **Architecture docs** (`docs/`) summarize and connect the above — they never outrank code or decisions.
+5. **Historical and exploration docs** are context only — never implementation authority.
+
+If code, decisions.md, and an architecture doc disagree, do not choose arbitrarily. Report the mismatch and ask.
+
+### Truth classes
+- **`docs/`** — current ground truth. If it's in `docs/`, it describes what IS (shipped, provable by code/tests).
+- **`work/epics/`** — decided-next and exploration. Proposals, specs, architectural direction for future work.
+- **`docs/archive/`**, **`docs/releases/`** — historical. What WAS. Do not use for current state.
+- **`docs/notes/`** — exploration only. Brainstorming, research, ideas. Never treat as implementation authority.
+
+### Guards
+- Do not describe a target contract in present tense unless it is live.
+- Do not let one file simultaneously act as current reference and historical archive.
+- Do not restate a canonical contract in many places from memory — point to the owning doc.
+- Do not let adapter/UI projection become the only place where semantics exist.
+- Do not keep "temporary" compatibility shims without explicit deletion criteria.
+- When a milestone explicitly owns a bridge or cleanup seam, do not preserve the bridge helper past that milestone as a tolerated coexistence state. Treat the surviving helper as incomplete work.
+- Do not reconstruct semantic or analytical identity in adapters or clients from `kind`, `logicalType`, file stems, or similar heuristics when compiled/runtime facts can own that truth.
+- When a runtime boundary changes, prefer forward-only regeneration of runs, fixtures, and approved outputs over compatibility readers that recover missing facts.
+- Do not keep both a bridge abstraction and its compiled replacement once the replacement milestone is active unless the spec explicitly allows a coexistence window.
+- "API stability" does not mean "keep old functions around." When a function has no production callers after a refactor, delete it and its tests in the same change — do not retain it as a dead alternative entry point under the banner of keeping the existing surface stable.
+- Do not treat aspirational docs as implementation authority.
+
+## Documentation
+
+- Engine + shared docs in `docs/`; use Mermaid for diagrams (not ASCII art).
+- Keep docs/schemas/templates aligned when touching contracts or schemas.
+- Repository language: English. No time or effort estimates in docs or plans.
+- Treat sibling checkouts as read-only references unless the user instructs otherwise.
diff --git a/.ai-repo/scratch/.gitignore b/.ai-repo/scratch/.gitignore
@@ -0,0 +1,3 @@
+# Scratch dir — contents never tracked (see .ai/paths.md → Scratch Dir).
+*
+!.gitignore
diff --git a/.claude/skills/devcontainer/SKILL.md → .ai-repo/skills/devcontainer.md b/.claude/skills/devcontainer/SKILL.md → .ai-repo/skills/devcontainer.md
@@ -1,8 +1,3 @@
----
-name: devcontainer
-description: "> **This is archived content, not an active framework skill.** The active skill at `.ai/skills/devcontainer.md` is a 40-line generic core. If your repo relies on the detail below (Dockerfile templates"
----
-<!-- AUTO-GENERATED from source by sync.sh — do not edit manually -->
 # Long-form devcontainer reference (archived)
 
 > **This is archived content, not an active framework skill.** The active skill at `.ai/skills/devcontainer.md` is a 40-line generic core. If your repo relies on the detail below (Dockerfile templates, stack-specific blocks, worktree topology), copy the relevant sections into your own `.ai-repo/skills/devcontainer.md` — that file overrides the framework skill for this repo.
@@ -298,4 +293,4 @@ Do NOT put the worktree inside the main workspace — it duplicates the entire r
 | Tool caches | `/home/vscode/.cache/` | safe (costs re-download time) |
 | Build artifacts | `_build/`, `node_modules/`, `.venv/` | safe (costs rebuild time) |
 | Runtime data | `runtime/data/` (or project equivalent) | **not safe** — this is durable local state |
-| Git worktrees | `/workspaces/worktrees/` | **not safe** — contains work in progress |
+| Git worktrees | `/workspaces/worktrees/` | **not safe** — contains work in progress |
diff --git a/.claude/skills/ui-debug/SKILL.md → .ai-repo/skills/ui-debug.md b/.claude/skills/ui-debug/SKILL.md → .ai-repo/skills/ui-debug.md
@@ -1,8 +1,3 @@
----
-name: ui-debug
-description: "Diagnose UI issues quickly and reproducibly."
----
-<!-- AUTO-GENERATED from source by sync.sh — do not edit manually -->
 # Skill: ui-debug
 
 Diagnose UI issues quickly and reproducibly.
@@ -15,4 +10,4 @@ Diagnose UI issues quickly and reproducibly.
 - [ ] Check for an existing Playwright test — run or update it before manual fixes
 - [ ] Prefer Playwright tests for deterministic reproduction
 - [ ] If updating snapshots, note why and keep diffs minimal
-- [ ] Avoid external network calls; mock or stub where needed
+- [ ] Avoid external network calls; mock or stub where needed
diff --git a/.claude/settings.json b/.claude/settings.json
@@ -1,6 +1,23 @@
 {
-  "enabledPlugins": {
-    "aiwf-extensions@ai-workflow-rituals": true,
-    "wf-rituals@ai-workflow-rituals": true
+  "statusLine": {
+    "type": "command",
+    "command": "bash .claude/statusline.sh"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai/tools/scratch-audit.sh"
+          },
+          {
+            "type": "command",
+            "command": "[ -x .ai-repo/bin/wf-graph ] && .ai-repo/bin/wf-graph report --graph work/graph.yaml --status 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
   }
 }