docs: add mandatory branch/PR workflow rules

.agent-plan.md

@@ -6,7 +6,7 @@
 
 ## Current System State
 
-Repository initialized. Codebase empty. Architecture, design, and roadmap documents are locked in `docs/`. Agent-context files (`CLAUDE.md`, `llms.txt`, `.agent-plan.md`) are initialized.
+Repository initialized. Codebase empty. Architecture, design, and roadmap documents are locked in `docs/`. Agent-context files (`CLAUDE.md`, `llms.txt`, `.agent-plan.md`) are initialized. Branch/PR workflow rules (including label taxonomy and milestone map) are locked in `CLAUDE.md` and backed by a local `.git/hooks/pre-push` convenience hook (not versioned) and GitHub branch protection. GitHub labels and milestones (v0.1–v1.0) are created. pr-agent-context CI and refresh workflows are live in `.github/workflows/`.
 
 ---
 

.github/workflows/pr-agent-context-refresh.yml

@@ -0,0 +1,54 @@
+name: PR agent context refresh
+
+on:
+  pull_request_review:
+    types: [submitted, edited, dismissed]
+  pull_request_review_comment:
+    types: [created, edited, deleted]
+  check_run:
+    types: [completed]
+
+concurrency:
+  group: >-
+    pr-agent-context-refresh-${{
+      github.event.pull_request.number ||
+      github.event.check_run.pull_requests[0].number ||
+      github.event.check_run.head_sha ||
+      github.sha
+    }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  actions: read
+  pull-requests: write
+
+jobs:
+  pr-agent-context-refresh:
+    name: PR agent context refresh
+    if: >-
+      (github.event_name == 'pull_request_review' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      (github.event_name == 'pull_request_review_comment' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      (github.event_name == 'check_run' &&
+       github.event.action == 'completed' &&
+       github.event.check_run.app.slug != 'github-actions' &&
+       toJson(github.event.check_run.pull_requests) != '[]' &&
+       github.event.check_run.pull_requests[0].head.repo.full_name == github.repository)
+    uses: shaypal5/pr-agent-context/.github/workflows/pr-agent-context.yml@v4
+    with:
+      tool_ref: v4
+      execution_mode: refresh
+      publish_mode: append
+      include_review_comments: true
+      include_outdated_review_threads: true
+      include_failing_checks: true
+      include_failed_step_output: true
+      include_patch_coverage: true
+      target_patch_coverage: "100"
+      coverage_artifact_prefix: pr-agent-context-coverage
+      enable_cross_run_coverage_lookup: true
+      wait_for_reviews_to_settle: true
+      publish_all_clear_comments_in_refresh: false
+      debug_artifacts: true

.github/workflows/pr-agent-context.yml

@@ -0,0 +1,31 @@
+name: PR agent context
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: pr-agent-context-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  pr-agent-context:
+    name: PR agent context
+    uses: shaypal5/pr-agent-context/.github/workflows/pr-agent-context.yml@v4
+    permissions:
+      contents: read
+      actions: read
+      pull-requests: write
+    with:
+      tool_ref: v4
+      execution_mode: ci
+      publish_mode: append
+      include_review_comments: true
+      include_outdated_review_threads: true
+      include_failing_checks: true
+      include_failed_step_output: true
+      include_patch_coverage: true
+      target_patch_coverage: "100"
+      coverage_artifact_prefix: pr-agent-context-coverage
+      enable_cross_run_coverage_lookup: true
+      debug_artifacts: true

CLAUDE.md

@@ -1,5 +1,49 @@
 # CLAUDE.md — leadforge
 
+## Branch & PR Workflow (mandatory)
+
+**Never push directly to `main`.** Every piece of work — feature, bugfix, doc update, plan update — follows this sequence:
+
+1. `git checkout main && git pull` — ensure main is up to date.
+2. `git checkout -b <descriptive-branch-name>` — branch from latest main.
+3. Do the work; commit to the branch.
+4. Update `.agent-plan.md` to reflect project state *after* the PR merges; commit that update to the same branch (same PR).
+5. Open a PR against `main` on GitHub with a detailed description.
+6. Apply the appropriate **labels** to the PR (create new ones if none fit — see label taxonomy below).
+7. Assign the PR to the appropriate **milestone** (create a new one on GitHub if none fits).
+
+Never use `git push origin main`, `git push --force origin main`, or any variant that targets `main` directly.
+
+> **Team enforcement:** The above is reinforced by GitHub branch protection on `main`. The local `.git/hooks/pre-push` hook installed in this repo is a personal convenience only — it is not versioned and will not be present for other contributors.
+
+### Label taxonomy
+
+**Type** (one required):
+`type: feature` · `type: bugfix` · `type: docs` · `type: test` · `type: refactor` · `type: ci` · `type: chore`
+
+**Layer** (one or more, when touching package code):
+`layer: core` · `layer: narrative` · `layer: schema` · `layer: structure` · `layer: mechanisms` · `layer: simulation` · `layer: render` · `layer: exposure` · `layer: validation` · `layer: cli` · `layer: api` · `layer: recipes`
+
+**Status** (optional):
+`status: in progress` · `status: needs review` · `status: blocked`
+
+Existing labels that predate this taxonomy: `bug` · `documentation` · `enhancement` · `good first issue` · `help wanted` · `foundation` — use when appropriate.
+
+### Milestone map
+
+| Milestone | Covers | Roadmap |
+|---|---|---|
+| v0.1.0 — Repo & CLI skeleton | M0 | Foundation, CI, package scaffold |
+| v0.2.0 — First end-to-end world | M1–M3 | Config/recipe, narrative, schema |
+| v0.3.0 — Motif variability + exposure modes | M4–M6 | Structure, mechanisms, exposure |
+| v0.4.0 — Polished relational output + task export | M7–M10 | Simulation, observation, render, task |
+| v0.5.0 — CLI-complete release candidate | M11–M13 | CLI, validation harness |
+| v1.0.0 — Polished OSS release | M14–M15 | Sample data, notebooks, docs polish |
+
+If work spans multiple milestones, assign to the earliest one it unblocks.
+
+---
+
 ## Project Identity
 - Package / repo / CLI: `leadforge`
 - License: MIT