everything is broke, gsd is ass

PROJECT_STATE.md

@@ -0,0 +1,224 @@
+# Claude Code State & Control System
+
+This document contains **everything you need** to keep Claude Code from losing context, looping, or rewriting history:
+
+1. A canonical `PROJECT_STATE.md` file template
+2. A full set of **copy‑paste prompts** for working with Claude Code
+3. Claude Code **hooks / scripts** to automate checkpoints and recovery
+
+---
+
+## 1️⃣ PROJECT_STATE.md (CANONICAL FILE)
+
+Create this file at the root of your repo.
+
+```md
+# PROJECT STATE — CANONICAL
+
+⚠️ This file is the single source of truth.
+⚠️ Sections marked LOCKED may not be modified unless the user explicitly says "unlock".
+⚠️ Claude must read this file before doing any work.
+
+---
+
+## Goal (LOCKED)
+<!-- 1–3 sentences. Immutable unless explicitly changed by the user. -->
+
+
+## Non‑Negotiable Constraints (LOCKED)
+- No re‑evaluation of prior decisions
+- No alternative architectures unless explicitly requested
+- No refactors outside the active task
+- No scope expansion
+
+
+## Architecture Decisions (LOCKED)
+-
+-
+
+
+## Current Phase
+<!-- Short name + description -->
+
+
+## Active Tasks
+<!-- Only tasks Claude is allowed to work on -->
+- [ ]
+- [ ]
+
+
+## Completed Tasks
+- [x]
+
+
+## Open Questions (User‑Owned)
+<!-- Claude may not answer these unless asked -->
+-
+
+
+## Checkpoints (APPEND‑ONLY)
+
+### Checkpoint YYYY‑MM‑DD HH:MM
+- What exists:
+- What is missing:
+- Known issues:
+- Next step:
+```
+
+---
+
+## 2️⃣ CLAUDE CODE PROMPTS (COPY / PASTE)
+
+Save this section as `CLAUDE_PROMPTS.md` if you want it separate.
+
+---
+
+### 🔹 Initialize Project State
+```
+Create or update PROJECT_STATE.md.
+Write the goal, non‑negotiable constraints, architecture decisions, and an initial task list.
+Do NOT write code.
+Do NOT speculate.
+This file is canonical.
+```
+
+---
+
+### 🔹 Start Any Work Session
+```
+Before doing anything, read PROJECT_STATE.md in full.
+Summarize:
+- Goal
+- Current Phase
+- Active Tasks
+Then proceed with the first unfinished task only.
+Do not modify PROJECT_STATE.md unless explicitly told to.
+```
+
+---
+
+### 🔹 Execute a Task (No Drift)
+```
+Work only on the selected Active Task.
+Do not introduce new abstractions.
+Do not refactor unrelated code.
+Do not re‑analyze architecture.
+Produce the minimum change required.
+```
+
+---
+
+### 🔹 Write a Checkpoint
+```
+Write a new checkpoint to PROJECT_STATE.md.
+Append only under the Checkpoints section.
+Do not modify earlier content.
+Summarize truthfully:
+- What exists
+- What is missing
+- Known issues
+- Next step
+```
+
+---
+
+### 🔹 Context Reset / Recovery
+```
+Clear context.
+Read PROJECT_STATE.md completely.
+Summarize:
+- Goal
+- Current Phase
+- Active Tasks
+Then continue from the next unfinished task.
+```
+
+---
+
+### 🔹 Scope Guard (When Claude Starts Drifting)
+```
+Stop.
+This is out of scope.
+Re‑read PROJECT_STATE.md.
+Return to the current Active Task.
+```
+
+---
+
+### 🔹 Lock or Unlock Sections
+```
+Unlock the following section(s):
+- <section name>
+No other sections may be modified.
+```
+
+---
+
+## 3️⃣ CLAUDE CODE HOOKS / SCRIPTS
+
+These assume Claude Code can run shell commands or that you trigger them manually.
+
+---
+
+### 🧠 Auto‑Checkpoint Script
+Create `checkpoint.sh`
+
+```bash
+#!/usr/bin/env bash
+
+echo "\n### Checkpoint $(date '+%Y-%m-%d %H:%M')" >> PROJECT_STATE.md
+echo "- What exists:" >> PROJECT_STATE.md
+echo "- What is missing:" >> PROJECT_STATE.md
+echo "- Known issues:" >> PROJECT_STATE.md
+echo "- Next step:" >> PROJECT_STATE.md
+echo "" >> PROJECT_STATE.md
+```
+
+Use prompt:
+```
+Run checkpoint.sh and then fill in the new checkpoint accurately.
+```
+
+---
+
+### 🔁 Session Start Hook
+Create `session_start.md`
+
+```md
+Read PROJECT_STATE.md.
+You may not write code until you summarize:
+- Goal
+- Current Phase
+- Active Tasks
+```
+
+Paste this at the top of every new Claude Code session.
+
+---
+
+### 🧯 Emergency Reset Hook
+Create `RESET.md`
+
+```md
+STOP ALL WORK.
+Discard assumptions from previous context.
+Read PROJECT_STATE.md in full.
+State what the next correct action is.
+Do not code until confirmed.
+```
+
+---
+
+## Final Rule (Read This Once)
+
+Claude Code is a **stateless executor**, not a planner.
+
+This system turns it into:
+- A reliable implementer
+- A resumable worker
+- A non‑looping assistant
+
+If Claude starts looping, drifting, or "thinking creatively" — it means the rails weren’t explicit enough.
+
+Tighten the rails.
+