storkit/.story_kit/specs/functional/PROJECT_MANAGEMENT.md

# Functional Spec: Project Management

## 1. Project Lifecycle State Machine
The application operates in two primary states regarding project context:

1.  **Idle (No Project):**
    *   The user cannot chat about code.
    *   The only available primary action is "Open Project".
2.  **Active (Project Loaded):**
    *   A valid local directory path is stored in the Session State.
    *   Tool execution (read/write/shell) is enabled, scoped to this path.

## 2. Selection Logic
*   **Trigger:** User initiates "Open Project".
*   **Mechanism:** Path entry in the selection screen.
*   **Validation:**
    *   The backend receives the selected path.
    *   The backend verifies:
        1.  Path exists.
        2.  Path is a directory.
        3.  Path is readable.
    *   If valid -> State transitions to **Active**.
    *   If invalid because the path does not exist:
        *   The backend creates the directory.
        *   The backend scaffolds the Story Kit metadata under the new project root:
            *   `.story_kit/README.md`
            *   `.story_kit/specs/README.md`
            *   `.story_kit/specs/00_CONTEXT.md`
            *   `.story_kit/specs/tech/STACK.md`
            *   `.story_kit/specs/functional/` (directory)
            *   `.story_kit/stories/archive/` (directory)
        *   If scaffolding succeeds -> State transitions to **Active**.
        *   If scaffolding fails -> Error returned to UI, State remains **Idle**.
    *   If invalid for other reasons -> Error returned to UI, State remains **Idle**.

## 3. Security Boundaries
*   Once a project is selected, the `SessionState` struct in Rust locks onto this path.
*   All subsequent file operations must validate that their target path is a descendant of this Root Path.