release: GraphStack v4.5.0 — one-command bootstrap and PyPI bundle

Adds graphstack graph/init, bootstrap.ps1/sh for Cursor one-liner install, bundled workflow assets for pip wheels, board reopen/list-done, Cursor preToolUse gate, and PyPI publish workflow.

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

Author: MertCapkin

.cursor/hooks.json

@@ -1,6 +1,12 @@
 {
   "version": 1,
   "hooks": {
+    "preToolUse": [
+      {
+        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 cursor",
+        "matcher": "Write|Shell|Delete|Edit"
+      }
+    ],
     "beforeShellExecution": [
       { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gate-hook.ps1 cursor" }
     ],

.cursor/rules/graphstack.mdc

@@ -42,7 +42,7 @@ lives in `orchestrator/TOKEN_OPTIMIZER.md`. The Orchestrator loads it once at se
 activation — follow both that file **and** the abbreviated reminders below:
 
 ```
-Is the answer in the graph?        → Use graph, skip raw file read
+Is the answer in the graph?        → python -m graphstack graph query "…" (or GRAPH_REPORT once)
 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

.cursor/skills/architect/ARCHITECT.md

@@ -43,6 +43,13 @@ When activated, do this sequence exactly — no skipping:
 
 Before writing any brief, query the graph for:
 
+**Preferred — scoped graph query (Tier 1, free):**
+```bash
+python -m graphstack graph query "modules near login and session"
+python -m graphstack graph query "god nodes in auth cluster"
+python -m graphstack graph path <changed-file> <suspected-consumer>
+```
+
 **1. God nodes** — high-connectivity modules that the change might touch:
 ```
 From graph.json: nodes with degree > 10 near the change area

.github/workflows/ci.yml

@@ -99,6 +99,13 @@ jobs:
               "scripts/graphstack/validate.py",
               "scripts/graphstack/gate.py",
               "scripts/graphstack/state.py",
+              "scripts/graphstack/graph.py",
+              "scripts/graphstack/init_cmd.py",
+              "scripts/graphstack/bootstrap.py",
+              "scripts/graphstack/assets/orchestrator/ORCHESTRATOR.md",
+              "scripts/bootstrap.ps1",
+              "scripts/bootstrap.sh",
+              "scripts/sync_assets.py",
               "scripts/gate-hook.sh",
               "scripts/gate-hook.ps1",
               ".cursor/hooks.json",

.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Sync bundled workflow assets
+        run: python scripts/sync_assets.py
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Run tests
+        run: |
+          python -m pip install --quiet pytest
+          python -m pip install --quiet -e .
+          python -m pytest scripts/graphstack/tests -q
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -18,6 +18,8 @@ __pycache__/
 .venv/
 venv/
 *.egg-info/
+dist/
+build/
 
 # Node
 node_modules/

CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to GraphStack are documented here.
 
 ---
 
+## [v4.5.0] — 2026-06-11
+
+### Added
+- **One-command bootstrap** — `scripts/bootstrap.ps1` (Windows) and `scripts/bootstrap.sh` (Unix) for Cursor terminal: pip install + `graphstack init . -y --install-deps`.
+- **PyPI packaging** — workflow files bundled in `graphstack/assets/`; `scripts/sync_assets.py`; `.github/workflows/publish.yml`.
+- **`graphstack init --install-deps`** — auto `pip install graphifyy` + `graphify cursor install` when missing.
+- **`board reopen <id> [--to todo|doing]`** — move completed tasks back to active columns.
+- **`board list-done [--limit N]`** — list completed tasks only.
+- **`docs/PYPI.md`** — maintainer publish guide.
+
+### Changed
+- **Installer** — resolves workflow sources from dev repo or bundled PyPI assets (`install_source_root()`).
+- **README** — prominent one-liner install section for Cursor users.
+
+---
+
+## [v4.4.0] — 2026-06-11
+
+### Added
+- **`graphstack graph`** — graphify wrappers: `query`, `path`, `explain`, `update` (graph-first reads without manual `graph.json` parsing).
+- **`graphstack init`** — one-shot onboarding: install + `graphify update` + `doctor`.
+- **Gate v2 (Cursor)** — `preToolUse` hook blocks `Write`/`Shell`/`Edit`/`Delete` without a claimed board task (before edit, not just advisory).
+- **`GRAPHSTACK_GATE=strict`** — fail-closed on hook internal errors (default remains fail-open).
+
+### Changed
+- **Installer** — Cursor `hooks.json` includes `preToolUse` matcher; ships `graph.py` and `init_cmd.py`.
+- **TOKEN_OPTIMIZER / ARCHITECT** — mandate `graphstack graph query` as the primary graph access path.
+- **validate / doctor** — `graph_ok` check for the graph query module.
+- **CONTRIBUTING** — updated for Python CLI + pytest workflow.
+
+### Fixed
+- **README Process Gate** — platform matrix documents Cursor vs Claude enforcement differences honestly.
+
+---
+
 ## [v4.3.0] — 2026-06-11
 
 ### Added

CONTRIBUTING.md

@@ -1,17 +1,19 @@
 # Contributing to GraphStack
 
-GraphStack is intentionally simple: it's markdown files, a bash script, and a shell installer. The barrier to contribution is low by design.
+GraphStack is a **workflow system** backed by a small Python CLI (`scripts/graphstack/`).
+Most files are instruction markdown for AI roles; the Python package provides board,
+validate, gate, graph query wrappers, and cross-platform install.
 
 ---
 
 ## What GraphStack Is (and Isn't)
 
-GraphStack is a **workflow system**, not a code library. Every file in this repo is either:
-- An instruction file that an AI reads (`.md`)
-- A shell script (`board.sh`, `install.sh`, `post-commit`)
-- Documentation
+GraphStack combines:
+- **Instruction files** an AI reads (`.cursor/skills/`, `orchestrator/`)
+- **Handoff files** humans and agents share (`handoff/`)
+- **Python CLI** — `pip install -e .` then `python -m graphstack …`
 
-There is no build step. No package.json. No dependencies to install to contribute.
+There is no Node build step. Python 3.8+ and pytest are required to run tests.
 
 ---
 
@@ -31,11 +33,11 @@ If you think GraphStack is missing a role (e.g., a Security Auditor, a Performan
 2. Get feedback before writing the file
 3. Once approved: add `.cursor/skills/<rolename>/<ROLENAME>.md`, update `ORCHESTRATOR.md` with the transition rule, add a prompt to `docs/CURSOR_PROMPTS.md`, and register the new path in `scripts/graphstack/installer.py`'s `FILE_COPIES`.
 
-### 3. Improve the board script
+### 3. Improve the board / CLI
 
-`scripts/board.sh` is pure bash + python3. If you find a bug or want to add a command (e.g., `board.sh reopen`, `board.sh list-done`), open a PR with:
-- The change
-- A manual test showing it works (paste the terminal output)
+Board logic lives in `scripts/graphstack/board.py` (Python). Shell shims (`board.sh`, `board.ps1`) delegate to it.
+
+For new CLI commands: add a module under `scripts/graphstack/`, register in `cli.py`, copy list in `installer.py`'s `PYTHON_PACKAGE_FILES`, and add tests in `scripts/graphstack/tests/`.
 
 ### 4. Add a demo
 
@@ -74,9 +76,10 @@ Consumer projects keep their handoff history; only this source repo resets.
 
 - **One PR per change.** Don't bundle unrelated edits.
 - **Explain the behavior change**, not just what you edited.
-- **Test the board script** if you touch `board.sh`: run through `new → claim → complete → status` and paste the output.
+- **Test the CLI** if you touch `scripts/graphstack/`: `pytest scripts/graphstack/tests -q`
+- **Test the board** if you touch board commands: run `new → claim → complete → status`
 - **Keep role files under 300 lines.** If yours is longer, it's doing too much.
-- **No new dependencies.** GraphStack requires only bash + python3 + git. Keep it that way.
+- **No new runtime dependencies.** The `graphstack` package uses only the Python stdlib. Optional: `graphifyy` for graph commands.
 
 ---
 

README.md

@@ -7,14 +7,37 @@ 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.3.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-v4.5.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.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).
+> **v4.5 highlights:** One-command bootstrap (`bootstrap.ps1` / `bootstrap.sh`), PyPI-ready packaging, `board reopen` / `list-done`. Plus v4.4 `graph query` + `init`, v4.3 gate. See [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## One command (Cursor terminal)
+
+Open your **project folder** in Cursor, open the integrated terminal, and run:
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/MertCapkin/GraphStack/main/scripts/bootstrap.ps1 | iex
+```
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/MertCapkin/GraphStack/main/scripts/bootstrap.sh | bash
+```
+
+**After [PyPI publish](docs/PYPI.md):**
+```bash
+pip install "graphstack[graphify]" && graphstack init . -y --install-deps
+```
+
+This installs GraphStack + Graphify, copies workflow files into **the current project**, refreshes the code graph, and runs `doctor`. Then describe your task in Cursor chat — rules load automatically.
 
 ---
 
@@ -71,6 +94,15 @@ python3 -m graphify --version
 
 GraphStack now works natively on Windows, macOS, and Linux. The installer runs through Python (which you already have for Graphify), so no shell-specific tooling is required.
 
+#### One command (recommended)
+
+```bash
+git clone https://github.com/MertCapkin/graphstack /path/to/graphstack
+cd /path/to/your-project
+/path/to/graphstack/install.ps1 .          # Windows
+# or: python -m graphstack init . -y       # any OS — install + graph refresh + doctor
+```
+
 #### macOS / Linux (bash / zsh)
 
 ```bash
@@ -306,7 +338,7 @@ GraphStack is a **workflow protocol** (markdown + handoff files), not a runtime
 
 | Topic | Reality |
 |-------|---------|
-| 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. |
+| 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. |
 | 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,24 +379,42 @@ Independent Python implementation (MIT) — inspired by common agent-tooling pat
 
 ---
 
+## Graph Queries (`graphstack graph`)
+
+Graph-first rules mean **query the graph before opening raw files**. v4.4 wraps Graphify's CLI so agents use one consistent command:
+
+```bash
+python -m graphstack graph query "who calls login"
+python -m graphstack graph query "blast radius of crypto.ts" --budget 1500
+python -m graphstack graph path src/auth/login.ts src/utils/crypto.ts
+python -m graphstack graph explain "login()"
+python -m graphstack graph update .     # AST-only refresh after code changes
+```
+
+Requires `graphify` on PATH (`pip install -r requirements.txt`). Agents should prefer `graph query` over reading full `GRAPH_REPORT.md` or grepping source for structural questions.
+
+---
+
 ## Process Gate (`graphstack gate`)
 
-v4.3 adds **mechanical enforcement** so Architect → Builder → Reviewer steps are harder to skip silently.
+v4.3+ adds **mechanical enforcement** so Architect → Builder → Reviewer steps are harder to skip silently. v4.4 extends Cursor with `preToolUse` blocking.
 
-| 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 |
+| 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`) | — |
 
 ```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)
+GRAPHSTACK_GATE=strict                   # fail-closed on hook internal 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). Hooks **fail open** if Python is missing — a crashing gate is worse than no gate.
+**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.
 
 > **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).
 

docs/PYPI.md

@@ -0,0 +1,48 @@
+# Publishing GraphStack to PyPI
+
+## One-time setup (maintainer)
+
+1. Create a [PyPI](https://pypi.org) account and project **`graphstack`** (check name availability first).
+2. Enable [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) on PyPI:
+   - GitHub repo: `MertCapkin/GraphStack`
+   - Workflow: `publish.yml`
+   - Environment name: `pypi`
+3. In GitHub → Settings → Environments → **pypi** → add protection rules if desired.
+
+## Release flow
+
+1. Bump version in `pyproject.toml` and `scripts/graphstack/__init__.py`.
+2. Update `CHANGELOG.md`.
+3. Sync bundled assets:
+   ```bash
+   python scripts/sync_assets.py
+   ```
+4. Commit, tag, and push:
+   ```bash
+   git tag v4.5.0
+   git push origin v4.5.0
+   ```
+5. Create a **GitHub Release** from the tag — this triggers `.github/workflows/publish.yml`.
+
+Or run **Publish to PyPI** workflow manually (`workflow_dispatch`).
+
+## Local dry-run (no upload)
+
+```bash
+python scripts/sync_assets.py
+python -m pip install build
+python -m build
+python -m pip install dist/graphstack-*.whl
+graphstack --version
+graphstack init /tmp/test-project -y --install-deps
+```
+
+## User install (after publish)
+
+```bash
+pip install "graphstack[graphify]"
+cd /path/to/your-project
+graphstack init . -y --install-deps
+```
+
+Workflow markdown files ship **inside the wheel** under `graphstack/assets/` — no git clone required.