Release v4.6.0: enforce orchestrator cycle with gate v3 and cycle CLI.

Adds role-aware gate rules, graphstack cycle commands, expanded alwaysApply rules, hook merge on install, and doctor handoff sync checks.

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

Author: MertCapkin

.cursor/rules/graphstack.mdc

@@ -1,82 +1,125 @@
 ---
-description: GraphStack v4 — Orchestrated, graph-first, GNAP-tracked AI development (cross-platform)
+description: GraphStack v4.6 — Orchestrated, graph-first, GNAP-tracked AI development (cross-platform)
 alwaysApply: true
 ---
 
-# GraphStack Core Rules (v4)
+# GraphStack Core Rules (v4.6)
 
 ## 🎯 Default Mode: Orchestrated
 
 Unless the user explicitly activates a single role, always run as the **Orchestrator**.
 
-**Frictionless startup (Cursor):** This project’s `.cursor/rules/graphstack.mdc` is
+**Frictionless startup (Cursor):** This project's `.cursor/rules/graphstack.mdc` is
 `alwaysApply: true`, so Composer/Agent already ships with GraphStack rules in every
 new chat. The user does **not** need to paste `Read orchestrator/ORCHESTRATOR.md …`
 every time.
 Your obligation is identical to **executing**
-`orchestrator/ORCHESTRATOR.md` → **Activation** (including parallel **1a** reads)
-on your first substantive turn, before acting on substantive work.
+`orchestrator/ORCHESTRATOR.md` → **Activation** on your first substantive turn,
+before acting on substantive work.
 
 **Optional shortcut:** The `/graphstack` Cursor command (project slash menu) expands
 explicit Orchestrator-bootstrap instructions.
 
 These rules are ALWAYS active in this project. Follow them in every response.
 
-## 🧠 Rule 1: Graph First (Most Important)
+## 🚀 Activation (mandatory first turn — full checklist)
+
+Run **one parallel read batch** (never split across turns):
+
+```
+orchestrator/TOKEN_OPTIMIZER.md
+graphify-out/GRAPH_REPORT.md          (if exists)
+handoff/BRIEF.md
+handoff/board/doing/*.json            (note task ids if any)
+handoff/STATE.md                      (last ## block only)
+```
+
+Then greet per `orchestrator/ORCHESTRATOR.md` step 8.
 
-**Session bootstrap wins:** Activation step **1a** in `orchestrator/ORCHESTRATOR.md`
-defines the first-read batch (`TOKEN_OPTIMIZER` + `GRAPH_REPORT` when present, once).
-After bootstrap completes, use graph-first discipline below.
+**If the user's first message already contains a task goal:** greet briefly, then
+enter **[ARCHITECT MODE]** immediately — do **not** implement code on the first turn.
+
+**If doing/ has a task and BRIEF is Ready for Builder:** offer to resume Builder or
+run `python -m graphstack cycle enter-builder <task-id>` before code edits.
+
+## 🧠 Rule 1: Graph First (Most Important)
 
 When a graph exists, answer structural questions from the graph before opening raw sources:
-- `graphify-out/GRAPH_REPORT.md` and, when needed, `graphify-out/graph.json`
+- `python -m graphstack graph query "…"` or `graphify-out/GRAPH_REPORT.md` (once per session)
 - Open implementation files only when the graph cannot answer
 
 When no graph exists, suggest `/graphify .`; if proceeding without confirmation,
 state risks explicitly.
 
 ## ⚡ Rule 2: Token Discipline
 
-The **full** decision tree (tiers 1–4, parallel-read protocol, output compression)
-lives in `orchestrator/TOKEN_OPTIMIZER.md`. The Orchestrator loads it once at session
-activation — follow both that file **and** the abbreviated reminders below:
+The **full** decision tree lives in `orchestrator/TOKEN_OPTIMIZER.md` (loaded at activation).
 
 ```
-Is the answer in the graph?        → python -m graphstack graph query "…" (or GRAPH_REPORT once)
+Is the answer in the graph?        → python -m graphstack graph query "…"
 Shell/git/test command needed?     → python -m graphstack run -- <cmd> (not raw)
 Is this tool call speculative?     → Cancel it, ask user first
 Can reads run in parallel?         → Parallelize them
 Output > 15 lines user won't act on → Summarize instead
-About to restate what user said?   → Delete it, start with action
 ```
 
-## 🎭 Rule 3: Role Discipline
+## 🎭 Rule 3: Role Discipline (announce every transition)
 
-When a role is active (Architect / Builder / Reviewer / QA):
-- Stay strictly within that role's responsibilities
-- Do not perform another role's job unless explicitly asked
-- Handoff explicitly: "This is ready for Builder" or "Sending back to Architect"
+Before acting as a role, announce: `[ARCHITECT MODE]`, `[BUILDER MODE]`, etc.
+
+After every transition, run:
+```bash
+python -m graphstack state set --role <role> [--task <task-id>]
+```
+
+**FORBIDDEN without active builder role:**
+- Editing or creating code files (anything outside `handoff/`, `graphify-out/`, `.cursor/`)
+- The process gate (v4.6) denies edits unless `handoff/STATE.json` has `role=builder`
+  and a task is in `handoff/board/doing/`
+
+**Cycle start (new feature):**
+```bash
+python -m graphstack cycle start <task-id> "<title>"
+```
+Architect writes BRIEF → then:
+```bash
+python -m graphstack cycle enter-builder <task-id>
+```
 
 ## 📋 Rule 4: Brief-Driven Building
 
-The Builder NEVER builds without a brief from `handoff/BRIEF.md`.
+The Builder NEVER builds without a brief from `handoff/BRIEF.md` with
+**Status: Ready for Builder**.
 The Reviewer NEVER approves without checking against the brief.
 If no brief exists, the Architect must write one first.
 
 ## 🚫 Rule 5: No Scope Creep
 
 Build exactly what the brief says.
-Do not add features, refactors, or improvements not in the brief.
-If something looks wrong but is out of scope, note it in `handoff/REVIEW.md` for the next cycle.
+If something looks wrong but is out of scope, note it in `handoff/REVIEW.md`.
 
 ## 🔄 Rule 6: Graph Staleness Check
 
 If `graphify-out/GRAPH_REPORT.md` is older than the files being discussed:
 - Warn: "Graph may be stale. Consider running `/graphify --update`"
-- Continue with available graph data unless user requests refresh
 
 ## 📁 Rule 7: Handoff Files
 
-- `handoff/BRIEF.md` — Architect writes this. Builder reads this before starting.
-- `handoff/REVIEW.md` — Reviewer writes findings here. Architect reads before next cycle.
-- Never delete these files mid-session. Append new cycles with date headers.
+- `handoff/BRIEF.md` — Architect → Builder
+- `handoff/REVIEW.md` — Reviewer findings (append-only)
+- `handoff/STATE.md` — human session log (append-only)
+- `handoff/STATE.json` — machine state for gate hooks
+
+## 🔁 Rule 8: Full Cycle (do not skip)
+
+For any feature or fix that touches code:
+
+```
+ARCHITECT → brief + board task
+BUILDER   → implement (only after enter-builder)
+REVIEWER  → append handoff/REVIEW.md with Verdict
+QA        → trace call paths from brief
+SHIP      → checklist + commit (strict gate: role=ship)
+```
+
+Never jump from graph exploration directly to implementation.

.gitignore

@@ -56,6 +56,9 @@ graphify-out/cache/
 # - graphify-out/GRAPH_REPORT.md
 # - graphify-out/graph.json
 
+# Local wheel/sdist smoke builds (not for release)
+dist_test/
+
 # Test artifacts (board smoke test leftovers)
 handoff/board/todo/smoke-*.json
 handoff/board/doing/smoke-*.json

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to GraphStack are documented here.
 
 ---
 
+## [v4.6.0] — 2026-06-11
+
+### Added
+- **`graphstack cycle`** — `cycle start <id> "<title>"` and `cycle enter-builder <id>` bind board + `STATE.json` + BRIEF status in one step.
+- **Gate v3** — R2b (role must be `builder` for code edits), R3b (no edits on Draft brief), R5/R6 (ship + review approval required for code commits in strict mode).
+- **`brief_utils.py`** — shared BRIEF/REVIEW helpers for gate, validate, and cycle.
+- **Doctor/validate** — handoff sync warnings (`BRIEF` ready but `doing/` empty, role mismatch) and `.cursor/hooks.json` gate presence checks.
+
+### Changed
+- **`graphstack.mdc` v4.6** — full Activation checklist, role announcements, and cycle commands embedded in `alwaysApply` rules.
+- **`ORCHESTRATOR.md`** — Activation step 9 routes user goals to Architect immediately (no code on first turn).
+- **Installer** — merges GraphStack gate hooks into existing `.cursor/hooks.json` / `.claude/settings.json` instead of skipping.
+
+---
+
 ## [v4.5.5] — 2026-06-11
 
 ### Fixed

README.md

@@ -395,17 +395,23 @@ v4.3+ adds **mechanical enforcement** so Architect → Builder → Reviewer step
 
 | Rule | What it blocks | Cursor | Claude Code |
 |------|----------------|--------|-------------|
-| R1 | `git commit` touching code while `doing/` is empty | deny (`beforeShellExecution` + `preToolUse` Shell) | deny (`PreToolUse` Bash) |
-| R2 | Edit/Write on code paths while `doing/` is empty | deny (`preToolUse` Write/Edit) | deny (`PreToolUse` Edit/Write) |
-| R3 | Commit while `BRIEF.md` is still the template | deny | deny |
-| R4 | `STATE.json` not updated this cycle | advisory (`stop`) | advisory (`Stop`) |
-| — | Edit already applied (legacy hook) | advisory only (`afterFileEdit`) | — |
+| R1 | `git commit` touching code while `doing/` is empty | deny | deny |
+| R2 | Edit/Write on code paths while `doing/` is empty | deny | deny |
+| R3 | Template `BRIEF.md` while task in `doing/` | deny | deny |
+| R2b | Code edit while `STATE.json` role ≠ `builder` | deny | deny |
+| R3b | Code edit while `BRIEF.md` status is Draft | deny | deny |
+| R4 | Stale `STATE.json` vs board claim | advisory (`stop`; **deny** in strict) | same |
+| R5 | Code commit while role ≠ `ship` | — | — (**strict** only) |
+| R6 | Code commit without `Verdict: Approved` in `REVIEW.md` | — | — (**strict** only) |
+| — | Edit already applied (legacy hook) | advisory (`afterFileEdit`) | — |
 
 ```bash
+python -m graphstack cycle start my-feature "Add email verification"
+python -m graphstack cycle enter-builder my-feature   # after Architect writes BRIEF
 python -m graphstack gate check          # CI / manual — exit 1 on violation
 python -m graphstack state set --role builder --task my-feature
 GRAPHSTACK_GATE=off                      # emergency bypass (one session)
-GRAPHSTACK_GATE=strict                   # fail-closed on hook internal errors
+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.

orchestrator/ORCHESTRATOR.md

@@ -52,7 +52,12 @@ Execute this sequence exactly on every session start. Each step has a fallback 
     [Only if STATE.md has entry]: Last session: [ROLE] on [date] — resume?
     What are we working on?"
 
-9. Wait. Do not proceed until user responds.
+9. First-turn routing (replaces blind wait):
+   a. User message is empty / only greeting → greet (step 8) and wait.
+   b. User message contains a task goal (feature, fix, bug) → greet briefly (step 8),
+      then enter ARCHITECT immediately. Do NOT implement code on the first turn.
+   c. doing/ has a task + BRIEF Ready for Builder → offer resume Builder:
+      `python -m graphstack cycle enter-builder <task-id>` before any code edit.
 ```
 
 ---
@@ -148,13 +153,24 @@ Bootstrapper writing Cycle [N+1] brief.
 ### IDLE → ARCHITECT
 **Trigger:** Graph exists with nodes AND user describes a feature, change, or bug fix.
 
+**Mechanical prep (Architect):**
+```bash
+python -m graphstack cycle start <task-id> "<title>"
+# or manually: board new <id> "<title>" + state set --role architect --task <id>
+```
+
 **Action:**
 ```
 [ARCHITECT MODE]
 Reading graph context...
 [execute architect logic from .cursor/skills/architect/ARCHITECT.md]
 ```
 
+**Before BUILDER:** brief must be **Ready for Builder**, then:
+```bash
+python -m graphstack cycle enter-builder <task-id>
+```
+
 ### ARCHITECT → BUILDER
 **Trigger:** Brief is written AND user says any of:
 - "looks good", "proceed", "build it", "go ahead", "ok", "evet", "devam"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "MertCapkin_GraphStack"
-version = "4.5.5"
+version = "4.6.0"
 description = "Graph-first AI development workflow — board, gate, graph queries, one-shot init"
 readme = "README.md"
 license = { text = "MIT" }

scripts/graphstack/__init__.py

@@ -5,8 +5,8 @@
 
 Entry point: ``python -m graphstack <command>``
 Commands: ``board``, ``install``, ``init``, ``hook``, ``validate``, ``doctor``, ``run``,
-``gate``, ``state``, ``graph``
+``gate``, ``state``, ``graph``, ``cycle``
 """
 
-__version__ = "4.5.5"
+__version__ = "4.6.0"
 __all__ = ["__version__"]