docs: align README, skills, and CURSOR_PROMPTS with v4.6 cycle and gate v3.

Updates install tree, workflow diagram, limitations, slash command, and role skills to match cycle start/enter-builder handoff.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: MertCapkin

.cursor/commands/graphstack.md

@@ -1,5 +1,5 @@
 # GraphStack — start Orchestrator
 
-1. Execute **Activation** in `orchestrator/ORCHESTRATOR.md` exactly as written (including step **1a**).
-2. Greet using the scripted format from that section.
-3. Wait for user input (`Activation` wait step). If the user already embedded their goal in the same message as this command, proceed with that goal immediately after greeting.
+1. Execute **Activation** in `orchestrator/ORCHESTRATOR.md` exactly (full parallel read batch: TOKEN_OPTIMIZER, GRAPH_REPORT, BRIEF, doing/, STATE).
+2. Greet using the scripted format from step 8.
+3. **First-turn routing (step 9):** If the user already embedded a task goal in this message → greet briefly, enter **[ARCHITECT MODE]** immediately (no code on turn 1). If the message is empty → greet and wait.

.cursor/skills/architect/ARCHITECT.md

@@ -129,12 +129,18 @@ User says "new project"       → Do not proceed — signal Orchestrator to use
 
 ## Handoff to Builder
 
+At session start (if Orchestrator has not already):
+
+```bash
+python -m graphstack cycle start <task-id> "<objective one-liner>"
+```
+
 When brief is ready:
 
-1. Write `handoff/BRIEF.md`
-2. Create the GNAP board task:
+1. Write `handoff/BRIEF.md` with **Status: Ready for Builder**
+2. Announce handoff (Orchestrator runs `cycle enter-builder` before Builder writes code):
    ```bash
-   python -m graphstack board new <task-id> "<objective one-liner>"
+   python -m graphstack cycle enter-builder <task-id>
    ```
 3. Announce:
 ```

.cursor/skills/bootstrapper/BOOTSTRAPPER.md

@@ -42,7 +42,7 @@ If a graph already exists, the Orchestrator uses the Architect instead — not y
 6. Wait for approval. Revise if needed.
 
 7. Write the first brief (Cycle 1) to handoff/BRIEF.md.
-   Create the board task: python -m graphstack board new cycle-1-[module] [module name]
+   Create the cycle task: python -m graphstack cycle start cycle-1-[module] "[module name]"
 
 8. Announce handoff:
    "[BOOTSTRAPPER → BUILDER]

.cursor/skills/builder/BUILDER.md

@@ -26,12 +26,12 @@ When activated, execute this sequence exactly:
           python -m graphstack board new [brief-slug] [brief objective]
       → If 2+ matches: list them and ask user which to claim
 
-4. Claim the task:
-   python -m graphstack board claim <task-id> builder
+4. Enter builder role (preferred — sets board claim + STATE.json for gate v3):
+   python -m graphstack cycle enter-builder <task-id>
+   # Fallback if task already in doing/: board claim <task-id> builder
+   #          + state set --role builder --task <task-id>
 
-5. Update machine-readable state (Orchestrator already confirmed the brief —
-   do NOT ask the user again):
-   python -m graphstack state set --role builder --task <task-id>
+5. Verify STATE.json shows role=builder before any code edit (gate denies otherwise)
 
 6. Report once, then start building immediately:
    "[BUILDER MODE] Task: [task-id] | Criteria: [N] | Files: [list]"

README.md

@@ -14,7 +14,7 @@ One prompt starts the entire lifecycle — from blank repo to production.
 
 </div>
 
-> **v4.5 highlights:** Published on [PyPI](https://pypi.org/project/MertCapkin_GraphStack/) as **`MertCapkin_GraphStack`**, one-command bootstrap, `board reopen` / `list-done`. Plus v4.4 `graph query` + `init`, v4.3 gate. See [CHANGELOG.md](CHANGELOG.md).
+> **v4.6 highlights:** `graphstack cycle` (start / enter-builder), **gate v3** (role=builder for edits, strict ship/review), expanded `alwaysApply` rules, hook **merge** on install. See [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
@@ -255,9 +255,9 @@ Step 2 — every session (minimal typing):
 Example natural-language kickoff:
   "Add rate limiting to login."
 
-  [ARCHITECT]   reads graph (not raw files) → scopes change → writes BRIEF.md
+  [ARCHITECT]   cycle start → reads graph → scopes change → writes BRIEF.md
        ↓ auto
-  [BUILDER]     reads brief → queries graph for deps → builds exactly the brief
+  [BUILDER]     cycle enter-builder → reads brief → builds exactly the brief
        ↓ auto
   [REVIEWER]    checks criteria → inspects graph neighbors for side effects
        ↓ auto   (loops to Builder if rejected, max 3×)
@@ -332,12 +332,12 @@ GraphStack is a **workflow protocol** (markdown + handoff files), not a runtime
 
 | Topic | Reality |
 |-------|---------|
-| Role automation | Prompts alone cannot guarantee discipline. v4.3+ **`graphstack gate`** + v4.4 Cursor **`preToolUse`**. Hooks block commits and (on Cursor/Claude) code writes without a claimed task; `afterFileEdit` on Cursor remains advisory-only backup. |
+| Role automation | Prompts + **gate v3 (v4.6)**: code edits require `STATE.json role=builder` and a task in `doing/`. **`graphstack cycle`** binds board + state. Strict mode (`GRAPHSTACK_GATE=strict`) also enforces ship/review before code commits. `afterFileEdit` on Cursor remains advisory-only backup. |
 | Token savings | The table above is **estimated**, not guaranteed. Small repos or undisciplined sessions may use **more** tokens than unstructured chat. |
 | Knowledge graph | Value appears on **20+ file** codebases with module boundaries. Meta-repos full of markdown produce noisy graphs — use `.graphifyignore` (included in this repo). |
 | Setup | Graphify + `pip install MertCapkin_GraphStack` + `graphstack init` — or one bootstrap command. See [PyPI](https://pypi.org/project/MertCapkin_GraphStack/). |
 
-**v4.1 helpers:** `graphstack doctor` (health report) and `graphstack validate` (exit code for CI). Use `--strict` before Builder handoff; use `--fail-stale-graph` in CI after code changes.
+**Health checks:** `graphstack doctor` and `graphstack validate` (exit code for CI). v4.6 adds handoff sync + `hooks.json` checks. Use `--strict` before Builder handoff; use `--fail-stale-graph` in CI after code changes.
 
 ```bash
 graphstack doctor
@@ -391,7 +391,7 @@ Requires `graphify` on PATH (`pip install -r requirements.txt`). Agents should p
 
 ## Process Gate (`graphstack gate`)
 
-v4.3+ adds **mechanical enforcement** so Architect → Builder → Reviewer steps are harder to skip silently. v4.4 extends Cursor with `preToolUse` blocking.
+**Gate v3 (v4.6)** adds role-aware enforcement so Architect → Builder → Reviewer steps are harder to skip silently. Cursor `preToolUse` blocks edits before they land; use **`graphstack cycle`** for the mechanical handoff steps.
 
 | Rule | What it blocks | Cursor | Claude Code |
 |------|----------------|--------|-------------|
@@ -414,7 +414,7 @@ GRAPHSTACK_GATE=off                      # emergency bypass (one session)
 GRAPHSTACK_GATE=strict                   # R4–R6 + fail-closed on hook errors
 ```
 
-**Install** writes `.cursor/hooks.json` and `.claude/settings.json` with OS-specific shim commands (`scripts/gate-hook.ps1` on Windows, `scripts/gate-hook.sh` on macOS/Linux). By default hooks **fail open** if Python is missing — use `GRAPHSTACK_GATE=strict` for teams that prefer blocking over availability.
+**Install** writes or **merges** `.cursor/hooks.json` and `.claude/settings.json` with OS-specific shim commands (`scripts/gate-hook.ps1` on Windows, `scripts/gate-hook.sh` on macOS/Linux). By default hooks **fail open** if Python is missing — use `GRAPHSTACK_GATE=strict` for teams that prefer blocking over availability.
 
 > **Framework repo note:** This GitHub repo ships `handoff/` as **templates** (empty brief, no `done/` tasks). Your installed project fills those files during real work. Before contributing here, reset handoff — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
@@ -424,7 +424,8 @@ GRAPHSTACK_GATE=strict                   # R4–R6 + fail-closed on hook errors
 
 ```
 your-project/
-├── .cursor/rules/graphstack.mdc          ← always-active rules (Cursor auto-loads)
+├── .cursor/rules/graphstack.mdc          ← always-active rules v4.6 (Cursor auto-loads)
+├── .cursor/hooks.json                    ← process gate (merged on reinstall)
 ├── .cursor/commands/graphstack.md        ← `/graphstack` Cursor slash-command bootstrapper
 ├── orchestrator/
 │   ├── ORCHESTRATOR.md                   ← state machine: all transitions
@@ -439,7 +440,8 @@ your-project/
 ├── handoff/
 │   ├── BRIEF.md                          ← Architect → Builder
 │   ├── REVIEW.md                         ← Reviewer + QA findings (append-only)
-│   ├── STATE.md                          ← session state for resuming
+│   ├── STATE.md                          ← human session log (append-only)
+│   ├── STATE.json                        ← machine state for gate hooks
 │   ├── BOOTSTRAP.md                      ← cross-cycle project memory
 │   └── board/
 │       ├── todo/                         ← tasks waiting to be claimed
@@ -460,7 +462,12 @@ your-project/
 │       ├── hook.py                       ← post-commit graph-update logic
 │       ├── platform_utils.py             ← OS detection, Python finder, encoding-safe echo
 │       ├── cli.py                        ← entry point dispatcher
-│       ├── validate.py                   ← layout / brief / graph checks
+│       ├── validate.py                   ← layout / brief / graph / hooks checks
+│       ├── gate.py                       ← process gate (R1–R6)
+│       ├── state.py                      ← handoff/STATE.json
+│       ├── cycle.py                      ← cycle start / enter-builder
+│       ├── brief_utils.py                ← shared BRIEF/REVIEW helpers
+│       ├── graph.py                      ← graphify query wrappers
 │       ├── run.py                        ← shell runner with compaction
 │       ├── compact/                      ← git / pytest / generic compactors
 │       └── tests/                        ← pytest suite
@@ -498,6 +505,16 @@ bash scripts/board.sh log
 
 #### Cross-platform (any shell with Python)
 
+**Preferred — full cycle handoff (v4.6):**
+
+```bash
+python -m graphstack cycle start add-oauth "Add OAuth login with GitHub"
+# Architect writes handoff/BRIEF.md → Status: Ready for Builder
+python -m graphstack cycle enter-builder add-oauth
+```
+
+**Low-level board (still supported):**
+
 ```bash
 python -m graphstack board status
 python -m graphstack board new add-oauth Add OAuth login with GitHub
@@ -506,7 +523,7 @@ python -m graphstack board complete add-oauth
 python -m graphstack board log
 python -m graphstack run -- git status
 python -m graphstack doctor
-python -m graphstack validate --fail-stale-graph
+python -m graphstack validate --strict --fail-stale-graph
 ```
 
 Every board operation is a git commit. `git log handoff/board/` shows who did what, when.

docs/CURSOR_PROMPTS.md

@@ -1,4 +1,4 @@
-# GraphStack v4 — Cursor Prompts & Setup Guide
+# GraphStack v4.6 — Cursor Prompts & Setup Guide
 
 ---
 
@@ -89,6 +89,16 @@ Resume from last session.
 
 Architect → Builder → Reviewer → QA → Ship zinciri kullanıcı etkileşimi olmadan yürür.
 
+**v4.6 mekanik handoff (gate ile uyumlu):**
+
+```bash
+python -m graphstack cycle start my-feature "Hedefin tek cümle özeti"
+# Architect handoff/BRIEF.md yazar → Status: Ready for Builder
+python -m graphstack cycle enter-builder my-feature
+```
+
+Kod edit gate'i `role=builder` ve `doing/` task olmadan **engeller**. Takım modu: `GRAPHSTACK_GATE=strict`.
+
 ---
 
 ## 🚀 Sıfırdan Yeni Proje (Bootstrap Modu)
@@ -172,9 +182,18 @@ Run the pre-ship checklist for task [task-id].
 
 ---
 
-## 📋 Board Komutları (Terminal)
+## 📋 Cycle + Board (Terminal)
+
+**Önerilen (v4.6)** — board + STATE + BRIEF tek adımda:
+
+```bash
+python -m graphstack cycle start my-feature "OAuth login ekle"
+python -m graphstack cycle enter-builder my-feature
+python -m graphstack doctor
+python -m graphstack validate --strict
+```
 
-Üç biçim de eşdeğerdir. Shell tercihinize göre seçin.
+**Düşük seviye board** — üç biçim eşdeğerdir:
 
 **macOS / Linux (bash):**
 ```bash
@@ -209,7 +228,9 @@ python -m graphstack board log
 
 - Her Orchestrator döngüsünde mümkünse **yeni bir Cursor chat** aç — context temiz kalır
 - Cursor slash menüsünde **`/graphstack`** kullanarak Orchestrator açılışını netleştir
-- `.cursor/rules/graphstack.mdc` otomatik yüklenir, elle okutman gerekmiyor
+- `.cursor/rules/graphstack.mdc` (v4.6) otomatik yüklenir — Activation checklist içerir
+- Kod yazmadan önce: `cycle enter-builder` veya `doctor` ile handoff senkronunu kontrol et
+- `.cursor/hooks.json` yoksa gate devre dışı — `graphstack install` veya reinstall ile merge et
 - Grafı büyük değişikliklerden sonra güncelle: `/graphify --update`
-- `handoff/STATE.md` dosyasını silme — oturum geçmişin orada
+- `handoff/STATE.md` ve `STATE.json` dosyalarını silme — oturum geçmişi / gate burada
 - `handoff/board/` klasörünü commit'le — ekip arkadaşların board'u görsün

scripts/graphstack/assets/.cursor/commands/graphstack.md

@@ -1,5 +1,5 @@
 # GraphStack — start Orchestrator
 
-1. Execute **Activation** in `orchestrator/ORCHESTRATOR.md` exactly as written (including step **1a**).
-2. Greet using the scripted format from that section.
-3. Wait for user input (`Activation` wait step). If the user already embedded their goal in the same message as this command, proceed with that goal immediately after greeting.
+1. Execute **Activation** in `orchestrator/ORCHESTRATOR.md` exactly (full parallel read batch: TOKEN_OPTIMIZER, GRAPH_REPORT, BRIEF, doing/, STATE).
+2. Greet using the scripted format from step 8.
+3. **First-turn routing (step 9):** If the user already embedded a task goal in this message → greet briefly, enter **[ARCHITECT MODE]** immediately (no code on turn 1). If the message is empty → greet and wait.

scripts/graphstack/assets/.cursor/skills/architect/ARCHITECT.md

@@ -129,12 +129,18 @@ User says "new project"       → Do not proceed — signal Orchestrator to use
 
 ## Handoff to Builder
 
+At session start (if Orchestrator has not already):
+
+```bash
+python -m graphstack cycle start <task-id> "<objective one-liner>"
+```
+
 When brief is ready:
 
-1. Write `handoff/BRIEF.md`
-2. Create the GNAP board task:
+1. Write `handoff/BRIEF.md` with **Status: Ready for Builder**
+2. Announce handoff (Orchestrator runs `cycle enter-builder` before Builder writes code):
    ```bash
-   python -m graphstack board new <task-id> "<objective one-liner>"
+   python -m graphstack cycle enter-builder <task-id>
    ```
 3. Announce:
 ```

scripts/graphstack/assets/.cursor/skills/bootstrapper/BOOTSTRAPPER.md

@@ -42,7 +42,7 @@ If a graph already exists, the Orchestrator uses the Architect instead — not y
 6. Wait for approval. Revise if needed.
 
 7. Write the first brief (Cycle 1) to handoff/BRIEF.md.
-   Create the board task: python -m graphstack board new cycle-1-[module] [module name]
+   Create the cycle task: python -m graphstack cycle start cycle-1-[module] "[module name]"
 
 8. Announce handoff:
    "[BOOTSTRAPPER → BUILDER]

scripts/graphstack/assets/.cursor/skills/builder/BUILDER.md

@@ -26,12 +26,12 @@ When activated, execute this sequence exactly:
           python -m graphstack board new [brief-slug] [brief objective]
       → If 2+ matches: list them and ask user which to claim
 
-4. Claim the task:
-   python -m graphstack board claim <task-id> builder
+4. Enter builder role (preferred — sets board claim + STATE.json for gate v3):
+   python -m graphstack cycle enter-builder <task-id>
+   # Fallback if task already in doing/: board claim <task-id> builder
+   #          + state set --role builder --task <task-id>
 
-5. Update machine-readable state (Orchestrator already confirmed the brief —
-   do NOT ask the user again):
-   python -m graphstack state set --role builder --task <task-id>
+5. Verify STATE.json shows role=builder before any code edit (gate denies otherwise)
 
 6. Report once, then start building immediately:
    "[BUILDER MODE] Task: [task-id] | Criteria: [N] | Files: [list]"