release: GraphStack v4.3.0 — deterministic process gate

Adds mechanical handoff enforcement so Architect → Builder steps are harder to skip silently, while keeping the full MD-based orchestrator workflow unchanged.

New CLI: graphstack gate (check / hook cursor / hook claude) and graphstack state (handoff/STATE.json). Hook adapters for Cursor (.cursor/hooks.json) and Claude Code (.claude/settings.json). Portable gate-hook.ps1 / gate-hook.sh shims resolve py -3 vs python on Windows.

Gate rules: deny code commits/edits without a board task in doing/; deny commits when BRIEF.md is still the template; advisory STATE.json staleness on turn end. Fail-open on hook errors; bypass via GRAPHSTACK_GATE=off.

Also: framework handoff hygiene (.graphstack-framework + validate warnings), Builder/Orchestrator confirmation fix, token rules condensed to TOKEN_OPTIMIZER.md, README/CHANGELOG updated. 74 tests passing.
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: MertCapkin

.claude/settings.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 claude",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 claude",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

.cursor/hooks.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 cursor" }
+    ],
+    "afterFileEdit": [
+      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 cursor" }
+    ],
+    "stop": [
+      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 cursor" }
+    ]
+  }
+}

.cursor/skills/architect/ARCHITECT.md

@@ -159,7 +159,4 @@ When `handoff/REVIEW.md` has a rejection:
 
 ## Token Rules (Architect)
 
-- Read GRAPH_REPORT.md once per session — never twice
-- Query graph.json for structural questions instead of reading multiple files
-- If you need to read a raw file: read only the relevant function/class, not the whole file
-- Never produce output the user didn't ask for
+Follow `orchestrator/TOKEN_OPTIMIZER.md` (loaded at session start). Architect-specific: graph before raw files; one targeted read if the graph is insufficient; no output the user didn't ask for.

.cursor/skills/builder/BUILDER.md

@@ -29,14 +29,12 @@ When activated, execute this sequence exactly:
 4. Claim the task:
    python -m graphstack board claim <task-id> builder
 
-5. Report:
-   "Graph loaded. Brief loaded. Board task claimed: [task-id]
-    Objective: [one line from brief]
-    Files to change: [list]
-    Acceptance criteria: [N items]
-    Ready to build. Proceed?"
+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>
 
-6. Wait for user confirmation before writing any code.
+6. Report once, then start building immediately:
+   "[BUILDER MODE] Task: [task-id] | Criteria: [N] | Files: [list]"
 ```
 
 ---
@@ -166,10 +164,4 @@ Ready for Reviewer.
 
 ## Token Rules (Builder)
 
-```
-Read GRAPH_REPORT.md once → never again this session
-Read each file maximum once → use context after
-Parallel file reads when possible → one tool call, multiple files
-No speculative reads → only read what the brief requires
-No output longer than needed → code + brief explanation only
-```
+Follow `orchestrator/TOKEN_OPTIMIZER.md` (loaded at session start). Builder-specific: read only brief-listed files; parallel reads in one tool call; no speculative exploration.

.github/workflows/ci.yml

@@ -97,6 +97,13 @@ jobs:
               "scripts/graphstack/platform_utils.py",
               "scripts/graphstack/constants.py",
               "scripts/graphstack/validate.py",
+              "scripts/graphstack/gate.py",
+              "scripts/graphstack/state.py",
+              "scripts/gate-hook.sh",
+              "scripts/gate-hook.ps1",
+              ".cursor/hooks.json",
+              ".claude/settings.json",
+              ".graphstack-framework",
               ".graphifyignore",
               "docs/case-studies/graphstack-self.md",
           ]
@@ -134,6 +141,9 @@ jobs:
       - name: Validate project layout (graphstack validate)
         run: python -m graphstack validate
 
+      - name: Process gate check (graphstack gate)
+        run: python -m graphstack gate check
+
       - name: Refresh knowledge graph (CI)
         run: graphify update .
 

.graphstack-framework

@@ -0,0 +1,3 @@
+# GraphStack framework source repository (not a consumer project).
+# handoff/ must ship as templates — reset BRIEF/REVIEW/STATE and clear board/done/
+# before release commits. See CONTRIBUTING.md.

CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to GraphStack are documented here.
 
 ---
 
+## [v4.3.0] — 2026-06-11
+
+### Added
+- **`graphstack gate`** — deterministic process enforcement: `gate check` (CI/manual), `gate hook cursor`, `gate hook claude`. Rules: deny code commits/edits when no board task is in `doing/`, or when `BRIEF.md` is still the template. Fail-open on hook errors; bypass via `GRAPHSTACK_GATE=off` or `handoff/.gate-off`.
+- **`graphstack state`** — machine-readable `handoff/STATE.json` (`set` / `get` / `clear`) for hook verification and resume.
+- **Hook adapters** — `.cursor/hooks.json` (Cursor 3.x, `version: 1`) and `.claude/settings.json` (Claude Code `PreToolUse` + `Stop`). Installer writes OS-specific commands (`gate-hook.ps1` on Windows, `gate-hook.sh` on Unix).
+- **`scripts/gate-hook.sh` / `scripts/gate-hook.ps1`** — portable shims (resolve `py -3` / `python3` / `python` without hardcoding).
+- **`.graphstack-framework` marker** — `validate` warns when the framework repo ships dirty handoff state (non-template brief, `done/` tasks, active `STATE.md` entries).
+- **Pytest** — `test_gate.py` (26 tests), `test_state.py` (5 tests).
+
+### Changed
+- **ORCHESTRATOR** — token tier detail moved to `TOKEN_OPTIMIZER.md` (reference only); state persistence now includes `state set`.
+- **BUILDER** — removed duplicate user confirmation at activation (Orchestrator brief confirmation is the single human gate); activation now runs `state set` and builds immediately.
+- **ARCHITECT / BUILDER** — token rules condensed to pointers to `TOKEN_OPTIMIZER.md`.
+- **CI** — `graphstack gate check` step; required-files manifest includes gate modules and hook shims.
+- **README** — Process Gate section; Limitations updated.
+
+### Fixed
+- **Windows hook launcher** — hooks no longer hardcode `python` (often missing on Windows); shims prefer `py -3`.
+
+---
+
 ## [v4.2.0] — 2026-05-17
 
 ### Added

CONTRIBUTING.md

@@ -56,6 +56,20 @@ When you introduce a copy change, restart Cursor once locally (and mention that
 
 ---
 
+## Framework repo: reset `handoff/` before release commits
+
+This repository **is** GraphStack (marker: `.graphstack-framework`). The `handoff/` folder ships as **empty templates** for projects that run `install.sh` — not as a log of our own development cycles.
+
+Before pushing framework changes to GitHub:
+
+1. Restore `handoff/BRIEF.md`, `handoff/REVIEW.md`, and `handoff/STATE.md` to their templates (no real task content).
+2. Remove any `handoff/board/done/*.json` and `handoff/STATE.json`.
+3. Run `python -m graphstack validate` — warnings `framework_*` should be zero.
+
+Consumer projects keep their handoff history; only this source repo resets.
+
+---
+
 ## Pull Request Guidelines
 
 - **One PR per change.** Don't bundle unrelated edits.

README.md

@@ -7,14 +7,14 @@ One prompt starts the entire lifecycle — from blank repo to production.
 
 [![CI](https://github.com/MertCapkin/graphstack/actions/workflows/ci.yml/badge.svg)](https://github.com/MertCapkin/graphstack/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-v4.2.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-v4.3.0-blue)](CHANGELOG.md)
 [![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-success)](#compatibility)
 [![Works with Cursor](https://img.shields.io/badge/Works%20with-Cursor-blue)](https://cursor.sh)
 [![Works with Claude Code](https://img.shields.io/badge/Works%20with-Claude%20Code-orange)](https://claude.ai/code)
 
 </div>
 
-> **v4.2 highlights:** `graphstack run` — token-safe shell output for git/tests (quality-preserving compaction, no external deps). Plus v4.1: `pip install -e .`, `validate` / `doctor`, CI graph checks. See [CHANGELOG.md](CHANGELOG.md).
+> **v4.3 highlights:** `graphstack gate` — deterministic handoff enforcement via Cursor + Claude Code hooks (brief + board task required before code changes). Plus v4.2 `graphstack run` (token-safe shell output), v4.1 `validate` / `doctor`. See [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
@@ -306,7 +306,7 @@ GraphStack is a **workflow protocol** (markdown + handoff files), not a runtime
 
 | Topic | Reality |
 |-------|---------|
-| Role automation | The Orchestrator state machine lives in `ORCHESTRATOR.md`. Models can skip Activation or transitions unless you use discipline + `graphstack validate`. |
+| Role automation | Prompts alone cannot guarantee discipline. v4.3 adds **`graphstack gate`** (hook-enforced) + `state set` + `validate`. Hooks block code commits/edits without a claimed board task; turn-end hooks are advisory only. |
 | 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 + GraphStack install + `/graphify` + Cursor — four steps, not zero-config. |
@@ -347,6 +347,29 @@ Independent Python implementation (MIT) — inspired by common agent-tooling pat
 
 ---
 
+## Process Gate (`graphstack gate`)
+
+v4.3 adds **mechanical enforcement** so Architect → Builder → Reviewer steps are harder to skip silently.
+
+| Rule | What it blocks | Platform |
+|------|----------------|----------|
+| R1 | `git commit` touching code while `handoff/board/doing/` is empty | Cursor + Claude Code |
+| R2 | Edit/Write on code paths while `doing/` is empty | Claude Code (`PreToolUse`) |
+| R3 | Commit while `BRIEF.md` is still the template and a task is in `doing/` | Both |
+| R4 | *(advisory)* `STATE.json` not updated this cycle | Turn-end hooks |
+
+```bash
+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)
+```
+
+**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). Hooks **fail open** if Python is missing — a crashing gate is worse than no gate.
+
+> **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).
+
+---
+
 ## What Gets Installed
 
 ```