Upating README for living spec

.living_spec/README.md

@@ -50,7 +50,7 @@ When the user asks for a feature, follow this 4-step loop strictly:
     *   **User Story:** "As a user, I want..."
     *   **Acceptance Criteria:** Bullet points of observable success.
     *   **Out of scope:** Things that are out of scope so that the LLM doesn't go crazy
-*   **Git:** The Assistant initiates a new local feature branch (e.g., `feature/story-name`) immediately.
+*   **Git:** Make a local feature branch for the story, named from the story (e.g., `feature/story-33-camera-format-auto-selection`). You must create and switch to the feature branch before making any edits.
 
 ### Step 2: The Spec (Digest)
 *   **Action:** Update the files in `specs/`.
@@ -66,17 +66,81 @@ When the user asks for a feature, follow this 4-step loop strictly:
 
 ### Step 4: Verification (Close)
 *   **Action:** Write a test case that maps directly to the Acceptance Criteria in the Story.
-*   **Action:** Run compilation and make sure it succeeds without errors. Fix warnings if possible. Run tests and make sure they all pass before proceeding. Ask questions here if needed.
+*   **Action:** Run compilation and make sure it succeeds without errors. Consult `specs/tech/STACK.md` and run all required linters listed there (treat warnings as errors). Run tests and make sure they all pass before proceeding. Ask questions here if needed.
-*   **Action:** Ask the user to accept the story. **Wait for user acceptance.**
+*   **Action:** Do not accept stories yourself. Ask the user if they accept the story. If they agree, move the story file to `stories/archive/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary).
 *   **Action:** When the user accepts:
-    1. Mark the acceptance criteria as complete (change `[ ]` to `[x]`)
+    1. Move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`)
-    2. Move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`)
+    2. Commit both changes to the feature branch
-    3. Commit both changes to the feature branch
+    3. Perform the squash merge: `git merge --squash feature/story-name`
-    4. Perform the squash merge: `git merge --squash feature/story-name`
+    4. Commit to master with a comprehensive commit message
-    5. Commit to master with a comprehensive commit message
+    5. Delete the feature branch: `git branch -D feature/story-name`
-    6. Delete the feature branch: `git branch -D feature/story-name`
 *   **Important:** Do NOT mark acceptance criteria as complete before user acceptance. Only mark them complete when the user explicitly accepts the story.
 
+**CRITICAL - NO SUMMARY DOCUMENTS:**
+*   **NEVER** create a separate summary document (e.g., `STORY_XX_SUMMARY.md`, `IMPLEMENTATION_NOTES.md`, etc.)
+*   **NEVER** write terminal output to a markdown file for "documentation purposes"
+*   The `specs/` folder IS the documentation. Keep it updated after each story.
+*   If you find yourself typing `cat << 'EOF' > SUMMARY.md` or similar, **STOP IMMEDIATELY**.
+*   The only files that should exist after story completion:
+    *   Updated code in `src/`
+    *   Updated specs in `specs/`
+    *   Archived story in `stories/archive/`
+
+---
+
+
+## 3.5. Bug Workflow (Simplified Path)
+
+Not everything needs to be a full story. Simple bugs can skip the story process:
+
+### When to Use Bug Workflow
+*   Defects in existing functionality (not new features)
+*   State inconsistencies or data corruption
+*   UI glitches that don't require spec changes
+*   Performance issues with known fixes
+
+### Bug Process
+1.  **Document Bug:** Create `bugs/bug-N-short-description.md` with:
+    *   **Symptom:** What the user observes
+    *   **Root Cause:** Technical explanation (if known)
+    *   **Reproduction Steps:** How to trigger the bug
+    *   **Proposed Fix:** Brief technical approach
+    *   **Workaround:** Temporary solution if available
+2.  **Fix Immediately:** Make minimal code changes to fix the bug
+3.  **Archive:** Move fixed bugs to `bugs/archive/` when complete
+4.  **No Spec Update Needed:** Unless the bug reveals a spec deficiency
+
+### Bug vs Story
+*   **Bug:** Existing functionality is broken → Fix it
+*   **Story:** New functionality is needed → Spec it, then build it
+*   **Spike:** Uncertainty/feasibility discovery → Run spike workflow
+
+---
+
+## 3.6. Spike Workflow (Research Path)
+
+Not everything needs a story or bug fix. Spikes are time-boxed investigations to reduce uncertainty.
+
+### When to Use a Spike
+*   Unclear root cause or feasibility
+*   Need to compare libraries/encoders/formats
+*   Need to validate performance constraints
+
+### Spike Process
+1.  **Document Spike:** Create `spikes/spike-N-short-description.md` with:
+    *   **Question:** What you need to answer
+    *   **Hypothesis:** What you expect to be true
+    *   **Timebox:** Strict limit for the research
+    *   **Investigation Plan:** Steps/tools to use
+    *   **Findings:** Evidence and observations
+    *   **Recommendation:** Next step (Story, Bug, or No Action)
+2.  **Execute Research:** Stay within the timebox. No production code changes.
+3.  **Escalate if Needed:** If implementation is required, open a Story or Bug and follow that workflow.
+4.  **Archive:** Move completed spikes to `spikes/archive/`.
+
+### Spike Output
+*   Decision and evidence, not production code
+*   Specs updated only if the spike changes system truth
 
 ---
 
@@ -88,6 +152,7 @@ When the LLM context window fills up (or the chat gets slow/confused):
 3.  **Handoff:** The only context the new LLM needs is in the `specs/` folder.
     *   *Prompt for New Session:* "I am working on Project X. Read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `stories/` to see what is pending."
 
+
 ---
 
 ## 5. Setup Instructions (For the LLM)