🚀 release: promote dev to main

.githooks/commit-msg

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+
+set -eu
+
+subject=$(sed -n '1p' "$1")
+exec node scripts/check-commit-message.mjs "$subject"

.github/workflows/git-policy.yml

@@ -0,0 +1,76 @@
+# Git policy — enforces the Clean Flow branching model
+# (spec: https://github.com/wgtechlabs/clean-flow) and the Clean Commit
+# subject format (spec: https://github.com/wgtechlabs/clean-commit).
+# Both specs ship as documentation only; this workflow is the enforcement.
+name: Git policy
+
+on:
+  pull_request:
+    branches:
+      - dev
+      - main
+  push:
+    branches:
+      - dev
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate-pull-request:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+      - name: Validate Clean Flow branch direction
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          if [ "$BASE_REF" = "dev" ]; then
+            case "$HEAD_REF" in
+              feature/*|fix/*|docs/*|chore/*|test/*|refactor/*) ;;
+              *)
+                echo "PRs into dev must come from an approved short-lived work branch."
+                exit 1
+                ;;
+            esac
+          elif [ "$BASE_REF" = "main" ] && [ "$HEAD_REF" != "dev" ]; then
+            echo "Only dev may open a PR into main."
+            exit 1
+          fi
+      - name: Validate Clean Commit subjects in the pull request
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          if [ "$BASE_REF" = "dev" ]; then
+            git fetch origin "pull/$PR_NUMBER/head:refs/remotes/origin/pr-head"
+            git log --no-merges --format=%s "$BASE_SHA..origin/pr-head" | node scripts/check-commit-message.mjs
+          else
+            node scripts/check-commit-message.mjs "$PR_TITLE"
+          fi
+
+  validate-protected-push:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Validate Clean Commit subjects pushed to protected branches
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+          AFTER_SHA: ${{ github.sha }}
+        run: |
+          if [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            git log --no-merges --format=%s -1 "$AFTER_SHA" | node scripts/check-commit-message.mjs
+          else
+            git log --no-merges --format=%s "$BEFORE_SHA..$AFTER_SHA" | node scripts/check-commit-message.mjs
+          fi

.gitignore

@@ -0,0 +1,10 @@
+# macOS
+.DS_Store
+
+# Node
+node_modules/
+*.log
+
+# Environment
+.env
+.env.*

AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+This file is the entry point for AI agents working on this repository. Humans: start at `book/README.md`.
+
+## Project overview
+
+<!-- Replace this paragraph in your project: what it is, who it's for, in two sentences. -->
+
+This project runs on the **BoCode workflow**: `code/` holds the source, `book/` holds the documentation stream and knowledge base. The highest architecture guidance lives inside the repository: long-term boundaries and hard constraints in `book/guidelines/architecture.md`, implementation snapshots in `book/docs/architecture/`. Internal documents never defer to external docs for authority.
+
+## Repository layout
+
+```
+<project>/
+├── code/       # source code
+└── book/       # documentation stream and knowledge base
+```
+
+**code and book are the project's two half-brains — neither is optional.** The relationship runs both ways:
+
+- **book → code**: plans drive implementation; guidelines provide the baseline; learn entries supply experience to consult before coding; issues provide direction for later iterations.
+- **code → book**: after code changes, check whether book needs syncing; when a feature completes, write its summary / learn / issue back into book.
+
+**Core principle: the more complete the book, the more reference value for humans and agents.** Summaries are written for humans as reports; learn entries are written as searchable knowledge for both.
+
+**Book entry point: `book/README.md` — the master index, script-generated. Read it before reading anything else in book.** After any book change run `cd code && npm run book:index` to refresh it; every new document must carry a frontmatter `description` (one plain-language line about the content).
+
+## Workflow
+
+Feature development strictly follows the six-phase gate workflow — see `book/guidelines/workflow.md`.
+
+Git commits and branching strictly follow `book/guidelines/git-workflow.md`: every non-merge commit uses the Clean Commit format; independent big features branch from `dev`; small verified fixes may commit to `dev` directly; PRs serve multi-contributor work and the `dev → main` release, which only ever merges. Never commit or push directly to `main`.
+
+## Document routing
+
+| Output | Location | Audience |
+|--------|----------|----------|
+| Feature report | `book/notes/summary/YYYY-MM/` | Humans first |
+| Experience & knowledge | `book/notes/learn/YYYY-MM/` | Humans + agents |
+| Potential problems | `book/notes/issue/YYYY-MM/` | Humans + agents |
+| Task tracking | `book/notes/task/` | Humans + agents |
+| Architecture decisions | `book/docs/decisions/` | Humans first |
+| Implementation plans | `book/plans/` | Agents first |
+| Change log | `book/changelogs/YYYY-MM/` | Humans first |
+
+**Writing style**: everything in book is written plain — see `book/guidelines/writing-style.md`.
+
+## code ↔ book interaction rules
+
+1. **Before coding**: read `book/guidelines/` for the baseline; search `book/notes/learn/YYYY-MM/` for related experience.
+2. **While coding**: new experience or pitfalls go straight into the current month's `book/notes/learn/YYYY-MM/`.
+3. **After coding**: check the book — is the plan's status updated, is a summary needed, do new issues exist?
+4. **Plans drive code**: `book/plans/` documents are the input to implementation. Read the plan, build in `code/`, write back to `book/`.
+5. **Issues feed code**: `book/notes/issue/` entries are the direction of later improvements.
+
+`changelogs/` and `notes/{summary,learn,issue}/` archive under `YYYY-MM/`; the month is a physical grouping, retrieval happens through `book/README.md`, frontmatter, and links. `book/` opens directly as an Obsidian vault.
+
+## Hard constraints
+
+- Step 0 (the structured requirements brief) is required before any code
+- No skipping between phases
+- Phase 2 designs proceed only after user approval
+- Problems found in Phase 5 / Phase 6 are **recorded, never fixed**
+- Feature work touches no code outside its scope: no opportunistic refactors, no new abstractions
+
+## Tooling
+
+- `cd code && npm run book:index` — regenerate `book/README.md` after any book change (do not edit by hand; missing frontmatter `description` warns and exits 1)
+- `node scripts/check-commit-message.mjs "<subject>"` — validate a commit subject against Clean Commit

CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+Read [AGENTS.md](AGENTS.md) — it is the single entry point for AI agents on this repository. Everything there applies in full: the six-phase gate workflow, the code↔book interaction rules, and the hard constraints.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Focus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.