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.