docs: add mandatory branch/PR workflow rules (#1)

* docs: add mandatory branch/PR workflow rules to CLAUDE.md

Locks the rule that no work goes directly to main. Every unit of work
must branch from latest main, commit there, update .agent-plan.md in
the same PR, and open a GitHub PR. Also installs a git pre-push hook
(.git/hooks/pre-push) that mechanically blocks any push targeting main.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add label taxonomy and milestone map to PR workflow (#2)

Extends the branch/PR workflow in CLAUDE.md with two required steps:
apply labels (type + layer taxonomy) and assign to a milestone. Adds
the full label taxonomy and a milestone map table to CLAUDE.md.

GitHub side: creates 22 labels across type/layer/status groups and
6 milestones (v0.1.0 through v1.0.0) matching the roadmap release gates.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* ci: add pr-agent-context CI and refresh workflows

Integrates shaypal5/pr-agent-context@v4 with two workflows:

- .github/workflows/pr-agent-context.yml
  Runs on pull_request (opened/synchronize/reopened). Calls the
  reusable workflow in ci mode with publish_mode=append and
  include_outdated_review_threads=true so stale-but-unresolved
  threads always appear in the generated agent context comment.
  Coverage artifacts are collected under the pr-agent-context-coverage
  prefix for use by the refresh flow via cross-run lookup.

- .github/workflows/pr-agent-context-refresh.yml
  Triggered by pull_request_review, pull_request_review_comment, and
  completed non-Actions check_run events. Runs in refresh mode with
  publish_mode=append (new comment per refresh, previous managed
  comments hidden), wait_for_reviews_to_settle=true, and
  enable_cross_run_coverage_lookup=true to reuse coverage artifacts
  from the CI run on the same head SHA.

Both workflows explicitly set include_outdated_review_threads=true
per project configuration.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: fix pre-push hook scope note and tighten force-push wording

- CLAUDE.md: scope the force-push prohibition to `main` explicitly
  (`git push --force origin main`) and add a note clarifying that the
  local pre-push hook is a personal convenience, not a versioned
  repo-wide enforcement; GitHub branch protection is the team-level guard
- .agent-plan.md: correct state description to say "local convenience hook
  (not versioned) and GitHub branch protection" instead of implying the
  hook is a reliable repo-wide mechanism

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: shaypal5

.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