feat: add configurable board path support

feature-requests/configurable-board-path/01-scope.md

@@ -0,0 +1,76 @@
+# Scope
+
+## Objective
+
+Implement a low-drift configurable board-path feature that lets Kanban load and persist board state from an explicit custom file path while preserving current default behavior.
+
+## Source request
+
+GitHub discussion `#228`:
+- “when executing the kanban command then we should have the option to set the customised board path so that we can load the project specific board and track the board.json in git.”
+
+## Locked goals
+
+- support a custom board file path
+- preserve current default path behavior
+- keep workspace identity based on repo path and existing workspace index
+- keep current task/session/worktree behavior unchanged
+- keep CLI/task seams compatible
+
+## Recommended v1 scope
+
+- add one canonical board-path resolver
+- add one supported configuration source for board-path override
+- refactor workspace-state reads/writes to use that resolver
+- add validation and tests for default and override behavior
+- document path semantics and limitations
+
+## Non-goals
+
+- no workspace-state storage redesign
+- no full relocation of all workspace files unless evidence forces it
+- no new external API
+- no board import/export workflow
+- no Prompt Forge integration work in this branch
+- no changes under `src/cline-sdk/`
+- no broad UI redesign
+
+## Decision gates
+
+### Gate 1: config surface
+
+Chosen:
+- persisted project runtime config as the canonical source
+
+Deferred:
+- launch-time CLI flag
+
+Reason:
+- lower drift than threading a launch-only override through every boot path
+- aligns with existing per-project config pattern
+
+### Gate 2: storage split policy
+
+Chosen:
+- `board.json` only in v1
+
+Deferred:
+- relocating `sessions.json` and `meta.json`
+
+Reason:
+- matches the actual feature request
+- lowest drift
+- avoids turning a file-path feature into a broader persistence migration
+
+Accepted tradeoff:
+- `statePath` no longer fully implies board location
+- API/doc language must become more precise
+
+## Success criteria
+
+1. Kanban still works unchanged with no custom configuration.
+2. A configured custom board file path is used for board read/write.
+3. `sessions.json` and `meta.json` behavior remains deterministic.
+4. Malformed custom board files fail loudly and clearly.
+5. CLI/runtime/project flows continue to resolve the same workspace identity.
+6. Tests cover default, override, and failure cases.

feature-requests/configurable-board-path/02-ticket-index.md

@@ -0,0 +1,162 @@
+# Ticket Index
+
+## Summary
+
+This branch is a brownfield persistence change. Most work belongs in `src/state/workspace-state.ts`, config plumbing, and workspace-state integration tests.
+
+## Tickets
+
+### T-00 Feature folder scaffolding
+- Model: `gpt-5.4-mini low`
+- Scope:
+  - feature docs
+  - ticket index
+  - orchestration prompt
+  - Cavekit kit/validation/tracking artifacts
+- Status:
+  - done
+
+### T-01 Existing behavior audit
+- Model: `gpt-5.4-mini medium`
+- Scope:
+  - enumerate every current assumption that board path equals `<statePath>/board.json`
+  - identify all code paths that read or write board state
+  - identify docs/tests that pin current path semantics
+- Primary files:
+  - `src/state/workspace-state.ts`
+  - `src/server/workspace-registry.ts`
+  - `src/trpc/projects-api.ts`
+  - `src/trpc/workspace-api.ts`
+  - `test/integration/workspace-state.integration.test.ts`
+  - `docs/architecture.md`
+- Acceptance:
+  - drift map written into tracking
+  - no assumed seams left undocumented
+
+### T-02 Board-path config source
+- Model: `gpt-5.4-mini medium`
+- Scope:
+  - add canonical board-path override source
+  - prefer project runtime config for v1
+  - if project config chosen, add typed field and normalization
+- Primary files:
+  - `src/config/runtime-config.ts`
+  - `src/core/api-contract.ts` if config contract changes require it
+  - related config tests
+- Acceptance:
+  - default config unchanged
+  - override can be read deterministically
+  - invalid/empty override rejected or normalized clearly
+
+### T-03 Storage resolver extraction
+- Model: `gpt-5.4-mini medium`
+- Scope:
+  - create one exported resolver for:
+    - `statePath`
+    - `boardPath`
+    - `sessionsPath`
+    - `metaPath`
+  - preserve current defaults
+- Primary files:
+  - `src/state/workspace-state.ts`
+- Acceptance:
+  - no direct hardcoded board-path joins remain outside resolver
+  - default resolver outputs match current behavior
+
+### T-04 Workspace-state persistence refactor
+- Model: `gpt-5.4-medium`
+- Scope:
+  - update load/save/mutate/read helpers to use resolved board path
+  - keep locks and revision semantics correct
+  - keep sessions/meta behavior explicit
+- Primary files:
+  - `src/state/workspace-state.ts`
+- Acceptance:
+  - default path still works
+  - configured board path works
+  - conflict behavior unchanged
+  - malformed board file errors still identify actual file path
+
+### T-05 Runtime/read-side contract audit
+- Model: `gpt-5.4-mini low`
+- Scope:
+  - decide whether `RuntimeWorkspaceStateResponse` needs `boardPath`
+  - update runtime/docs/tests if `statePath` would become misleading
+- Primary files:
+  - `src/core/api-contract.ts`
+  - `src/trpc/workspace-api.ts`
+  - `src/server/runtime-state-hub.ts`
+  - `web-ui` tests if affected
+- Acceptance:
+  - runtime contract is semantically honest
+  - no product code depends on false `statePath => board.json` assumption
+
+### T-06 CLI and operator surface
+- Model: `gpt-5.4-mini medium`
+- Scope:
+  - if needed, add a minimal CLI/configuration surface to set or inspect board-path override
+  - keep scope narrow; avoid general config overhaul
+- Primary files:
+  - `src/cli.ts`
+  - `src/commands/task.ts`
+  - config command files if existing surface is reused
+- Acceptance:
+  - operator can configure feature without manual file surgery
+  - no regression to normal launch/task commands
+
+### T-07 Integration and regression test wave
+- Model: `gpt-5.3-codex medium`
+- Scope:
+  - add or update tests for:
+    - default path
+    - custom path
+    - malformed custom board file
+    - concurrent workspace creation unaffected
+    - stale write/conflict unaffected
+- Primary files:
+  - `test/integration/workspace-state.integration.test.ts`
+  - config tests
+  - CLI tests if new flag/surface added
+- Acceptance:
+  - path feature validated end-to-end
+  - no silent fallback to old path when override configured
+
+### T-08 Docs update
+- Model: `gpt-5.4-mini low`
+- Scope:
+  - update human docs for board-path semantics
+  - note feature-request motivation and limitations
+- Primary files:
+  - `README.md`
+  - `docs/architecture.md`
+  - maybe `docs/README.md`
+- Acceptance:
+  - docs match actual resolver behavior
+  - no stale `statePath` implications remain
+
+### T-09 Final audit
+- Model: `gpt-5.4-mini low`
+- Scope:
+  - verify narrow branch scope
+  - verify no hidden persistence redesign slipped in
+  - close tracking/final validation
+- Deliverables:
+  - `09-final-validation.md`
+
+## Dependency order
+
+1. `T-01`
+2. `T-02`
+3. `T-03`
+4. `T-04`
+5. `T-05`
+6. `T-06`
+7. `T-07`
+8. `T-08`
+9. `T-09`
+
+Reason:
+- config source and resolver must settle first
+- persistence refactor depends on both
+- contract/CLI/docs should follow actual storage behavior
+- tests validate the final integrated shape

feature-requests/configurable-board-path/03-orchestration-prompt.md

@@ -0,0 +1,66 @@
+# Multi-Agent Orchestration Prompt
+
+Branch:
+- `fork/feature-request/configurable-board-path`
+
+Objective:
+- implement a low-drift configurable board-path feature for Kanban
+
+Locked constraints:
+- no SDK changes
+- no changes under `src/cline-sdk/`
+- preserve default behavior
+- no invented APIs
+- do not widen into workspace-state redesign
+
+Feature intent:
+- allow Kanban to load and persist board state from a custom board file path
+- support tracking project-specific board state in git
+
+Required brownfield facts:
+- board path is currently hardcoded in `src/state/workspace-state.ts`
+- workspace identity remains `repoPath <-> workspaceId`
+- current persistence model is directory-centric
+- request `#228` asks for custom board path, not a new storage engine
+
+Decision gates before code lands:
+1. choose canonical override source
+2. choose whether override applies only to `board.json` or to all workspace state files
+
+Recommended decisions:
+1. project runtime config as canonical source
+2. `board.json` only in v1
+
+Delegation map:
+- `gpt-5.4-mini low`
+  - audits
+  - docs
+  - contract honesty pass
+  - final validation
+- `gpt-5.4-mini medium`
+  - config plumbing
+  - resolver extraction
+  - CLI/config surface
+- `gpt-5.4-medium`
+  - workspace-state persistence refactor
+- `gpt-5.3-codex medium`
+  - integrated regression test wave
+
+Validation gates:
+1. resolver gate
+   - one canonical resolver owns board path semantics
+2. persistence gate
+   - load/save/mutate respect override and preserve revision rules
+3. compatibility gate
+   - default path behavior unchanged
+4. failure gate
+   - malformed custom board file fails loudly with actual file path
+5. scope gate
+   - no hidden relocation of sessions/meta unless explicitly approved
+
+Worker output requirements:
+- files changed
+- tests added/updated
+- assumptions
+- open risks
+- whether change widened scope beyond plan

feature-requests/configurable-board-path/04-context-index.md

@@ -0,0 +1,45 @@
+# Context Index
+
+## Entry points
+
+### Feature intent
+- feature request `#228`
+- Phase2 recommendation docs in `/lump/apps/kanban-integration-idea/docs/Phase2/`
+
+### Primary code ownership
+- `src/state/workspace-state.ts`
+
+### Supporting areas
+- `src/config/runtime-config.ts`
+- `src/trpc/workspace-api.ts`
+- `src/trpc/projects-api.ts`
+- `src/server/workspace-registry.ts`
+- `src/core/api-contract.ts`
+- `src/cli.ts`
+- `test/integration/workspace-state.integration.test.ts`
+- `docs/architecture.md`
+
+## Traversal order
+
+1. `05-refs-existing-behavior.md`
+2. `06-kit-configurable-board-path.md`
+3. `02-ticket-index.md`
+4. `07-validation.md`
+5. `08-tracking.md`
+
+## Context edges
+
+### Existing behavior refs -> kit
+- current hardcoded board path
+- directory-centric persistence model
+- repo-path-based workspace identity
+- runtime contract exposing `statePath`
+
+### Kit -> tickets
+- every ticket maps to one or more kit requirements
+
+### Tickets -> validation
+- each implementation ticket has one or more validation gates
+
+### Validation -> tracking
+- `08-tracking.md` records pass/fail/open risk for each gate