From a2eeccfd9dd7f3611f06da1a979781ab24229aab Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Wed, 13 May 2026 07:52:29 +0200
Subject: [PATCH] docs(work): scaffold pre-commit-hooks-v1 epic + stories

---
 .../01-husky-install/_story.md                | 25 +++++++++++++++++++
 .../02-pre-commit-hook/_story.md              | 14 +++++++++++
 .../03-state-sync-guard/_story.md             | 16 ++++++++++++
 docs/work/pre-commit-hooks-v1/_epic.md        | 24 ++++++++++++++++++
 4 files changed, 79 insertions(+)
 create mode 100644 docs/work/pre-commit-hooks-v1/01-husky-install/_story.md
 create mode 100644 docs/work/pre-commit-hooks-v1/02-pre-commit-hook/_story.md
 create mode 100644 docs/work/pre-commit-hooks-v1/03-state-sync-guard/_story.md
 create mode 100644 docs/work/pre-commit-hooks-v1/_epic.md

diff --git a/docs/work/pre-commit-hooks-v1/01-husky-install/_story.md b/docs/work/pre-commit-hooks-v1/01-husky-install/_story.md
new file mode 100644
index 0000000..5a0fb48
--- /dev/null
+++ b/docs/work/pre-commit-hooks-v1/01-husky-install/_story.md
@@ -0,0 +1,25 @@
+---
+id: 01-husky-install
+epic: pre-commit-hooks-v1
+title: Install husky + lint-staged
+type: technical-story
+status: in-progress
+feature: tooling
+depends-on: []
+blocks: [02-pre-commit-hook]
+---
+
+## Goal
+husky + lint-staged are dependencies of the root workspace and the
+`prepare` script wires the hooks on `pnpm install`.
+
+## In scope
+- Add husky + lint-staged to root devDependencies
+- Add `prepare` script that runs `husky` (initialises `.husky/`)
+- Create `.husky/` directory + the husky shim
+- Add `lint-staged` config to root package.json
+
+## Tasks
+- [ ] Story scaffold
+- [ ] Install husky + lint-staged + add scripts/config
+- [ ] Verify `pnpm install` initialises `.husky/`
diff --git a/docs/work/pre-commit-hooks-v1/02-pre-commit-hook/_story.md b/docs/work/pre-commit-hooks-v1/02-pre-commit-hook/_story.md
new file mode 100644
index 0000000..f6779be
--- /dev/null
+++ b/docs/work/pre-commit-hooks-v1/02-pre-commit-hook/_story.md
@@ -0,0 +1,14 @@
+---
+id: 02-pre-commit-hook
+epic: pre-commit-hooks-v1
+title: Pre-commit hook script
+type: technical-story
+status: todo
+feature: tooling
+depends-on: [01-husky-install]
+blocks: [03-state-sync-guard]
+---
+
+## Tasks
+- [ ] `.husky/pre-commit` runs lint-staged
+- [ ] Pre-commit also regenerates _state.json when docs/work/ changes and re-stages it
diff --git a/docs/work/pre-commit-hooks-v1/03-state-sync-guard/_story.md b/docs/work/pre-commit-hooks-v1/03-state-sync-guard/_story.md
new file mode 100644
index 0000000..5bb6f1d
--- /dev/null
+++ b/docs/work/pre-commit-hooks-v1/03-state-sync-guard/_story.md
@@ -0,0 +1,16 @@
+---
+id: 03-state-sync-guard
+epic: pre-commit-hooks-v1
+title: State-sync guard + tests
+type: technical-story
+status: todo
+feature: tooling
+depends-on: [02-pre-commit-hook]
+blocks: []
+---
+
+## Tasks
+- [ ] `scripts/work/state-sync-guard.mjs` fails when _state.json differs from rebuild output
+- [ ] Tests
+- [ ] Wire into pre-commit
+- [ ] Final verification + closeout
diff --git a/docs/work/pre-commit-hooks-v1/_epic.md b/docs/work/pre-commit-hooks-v1/_epic.md
new file mode 100644
index 0000000..b645f08
--- /dev/null
+++ b/docs/work/pre-commit-hooks-v1/_epic.md
@@ -0,0 +1,24 @@
+---
+id: pre-commit-hooks-v1
+prd: null
+title: Pre-commit hooks v1 — husky + fast conformance gates on commit
+type: epic
+status: in-progress
+features: [tooling]
+created: 2026-05-13
+---
+
+## Goal
+Install husky and wire pre-commit hooks that catch the cheap drift classes
+before code leaves the developer's machine. Slow checks stay in CI.
+
+## Why
+Slip a manifest update without re-running `pnpm work rebuild-state` and
+the committed _state.json drifts from markdown reality. Forget to lint
+and a broken commit lands. Pre-commit hooks shrink the cycle from "wait
+for CI" to "wait one second".
+
+## Stories
+- [ ] [01 — Install husky + lint-staged](01-husky-install/_story.md)
+- [ ] [02 — Pre-commit hook: lint-staged + state-sync](02-pre-commit-hook/_story.md)
+- [ ] [03 — State-sync guard script + tests](03-state-sync-guard/_story.md)