From c99575d330fd97141a7134199b5fee14694873f8 Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Sat, 18 Apr 2026 09:14:56 +0300 Subject: [PATCH 1/4] 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 --- .agent-plan.md | 2 +- CLAUDE.md | 14 ++++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.agent-plan.md b/.agent-plan.md index b065f4f..c228a07 100644 --- a/.agent-plan.md +++ b/.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 are locked in `CLAUDE.md` and enforced via `.git/hooks/pre-push`. --- diff --git a/CLAUDE.md b/CLAUDE.md index 4ee1b4f..2926532 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,19 @@ # 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 ` — 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. + +Never use `git push origin main`, `git push --force`, or any variant that targets `main` directly. + +--- + ## Project Identity - Package / repo / CLI: `leadforge` - License: MIT From 4c918e2fc5dcd4590b9344f1284c795909fb1904 Mon Sep 17 00:00:00 2001 From: Shay Palachy-Affek Date: Sat, 18 Apr 2026 09:30:17 +0300 Subject: [PATCH 2/4] 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 --- .agent-plan.md | 2 +- CLAUDE.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/.agent-plan.md b/.agent-plan.md index c228a07..01fd9da 100644 --- a/.agent-plan.md +++ b/.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. Branch/PR workflow rules are locked in `CLAUDE.md` and enforced via `.git/hooks/pre-push`. +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 enforced via `.git/hooks/pre-push`. GitHub labels and milestones (v0.1–v1.0) are created. --- diff --git a/CLAUDE.md b/CLAUDE.md index 2926532..a1470d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,9 +9,37 @@ 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`, or any variant that targets `main` directly. +### 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 From 8e20433bf8bbb4783dd1114585829753f2a2edee Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Sat, 18 Apr 2026 09:41:16 +0300 Subject: [PATCH 3/4] 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 --- .agent-plan.md | 2 +- .../workflows/pr-agent-context-refresh.yml | 54 +++++++++++++++++++ .github/workflows/pr-agent-context.yml | 31 +++++++++++ 3 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/pr-agent-context-refresh.yml create mode 100644 .github/workflows/pr-agent-context.yml diff --git a/.agent-plan.md b/.agent-plan.md index 01fd9da..1647b36 100644 --- a/.agent-plan.md +++ b/.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. Branch/PR workflow rules (including label taxonomy and milestone map) are locked in `CLAUDE.md` and enforced via `.git/hooks/pre-push`. GitHub labels and milestones (v0.1–v1.0) are created. +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 enforced via `.git/hooks/pre-push`. GitHub labels and milestones (v0.1–v1.0) are created. pr-agent-context CI and refresh workflows are live in `.github/workflows/`. --- diff --git a/.github/workflows/pr-agent-context-refresh.yml b/.github/workflows/pr-agent-context-refresh.yml new file mode 100644 index 0000000..e2e3e88 --- /dev/null +++ b/.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 diff --git a/.github/workflows/pr-agent-context.yml b/.github/workflows/pr-agent-context.yml new file mode 100644 index 0000000..6c26aa4 --- /dev/null +++ b/.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 From 270394b4d26bf28533e751aa2aa093c1991ff912 Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Sat, 18 Apr 2026 09:52:37 +0300 Subject: [PATCH 4/4] 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 --- .agent-plan.md | 2 +- CLAUDE.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.agent-plan.md b/.agent-plan.md index 1647b36..f8977c4 100644 --- a/.agent-plan.md +++ b/.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. Branch/PR workflow rules (including label taxonomy and milestone map) are locked in `CLAUDE.md` and enforced via `.git/hooks/pre-push`. GitHub labels and milestones (v0.1–v1.0) are created. pr-agent-context CI and refresh workflows are live in `.github/workflows/`. +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/`. --- diff --git a/CLAUDE.md b/CLAUDE.md index a1470d7..0a9a5dc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,9 @@ 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`, or any variant that targets `main` directly. +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