From b71f0154457e4c2de5edb67db367382226c09a07 Mon Sep 17 00:00:00 2001 From: Martin Stransky Date: Mon, 2 Mar 2026 18:49:18 +0100 Subject: [PATCH 1/5] fix: Strengthen QSP enforcement with pre-flight sync and prominence - Move QSP classification to first section in CLAUDE.md so it is read before anything else - Add pre-flight checklist (git sync + classify) that applies to all paths before any work begins - Remove redundant git fetch from S.3 (now handled by pre-flight) Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 8 ++++---- docs/DEVELOPMENT_PROCESS.md | 11 ++++++++++- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 29e8c87..f3fc2d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,9 @@ # CLAUDE.md +## Development Process (QSP classification) + +Before starting ANY task, classify it as **Q** (Quick), **S** (Standard), or **P** (Project) and follow the corresponding path in `docs/DEVELOPMENT_PROCESS.md`. This classification is mandatory -- do not skip it. + ## Security - **Real-time scanning**: The `security-guidance` plugin runs automatically during code editing, warning about command injection, eval/exec, pickle deserialization, XSS, and os.system() usage @@ -37,7 +41,3 @@ uv run pyright # Type check ## Version Management All packages maintain synchronized MAJOR.MINOR versions. Patch versions can differ. Check with `python scripts/check_versions.py`. - -## Development Process - -Before starting any task, classify it as **Q** (Quick), **S** (Standard), or **P** (Project) and follow the corresponding path in `docs/DEVELOPMENT_PROCESS.md`. This classification is mandatory -- do not skip it. diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md index d5a5875..4bf12ec 100644 --- a/docs/DEVELOPMENT_PROCESS.md +++ b/docs/DEVELOPMENT_PROCESS.md @@ -29,6 +29,15 @@ Task complexity determines process depth. Classify each task, then follow the ma --- +## Pre-flight (all paths) + +Before making any changes: + +1. **Sync** -- `git fetch origin && git status` to confirm you are on the correct branch and up to date with remote +2. **Classify** -- state the QSP classification to the user before proceeding + +--- + ## Q. Quick Path 1. **Fix it** -- make the change @@ -48,7 +57,7 @@ If the fix fails twice, reveals unexpected complexity, or CI fails, promote to * **S.2 Plan** -- Read `docs/DECISIONS.md`. Check for conflicts with prior decisions; if a conflict is found, present the contradiction to the user before proceeding. Design approach. Identify files to modify. Log the feature request and any user decisions. -**S.3 Setup** -- Create feature branch (`fix/...`, `feat/...`, `refactor/...`). Run `git fetch origin` and sync with base branch. +**S.3 Setup** -- Create feature branch from the base branch (`fix/...`, `feat/...`, `refactor/...`). **S.4 Build (TDD cycle)** 1. Create code structure (interfaces, types) From efe628ef3bd819774d94a1a6f83b494159efe3f2 Mon Sep 17 00:00:00 2001 From: Martin Stransky Date: Mon, 2 Mar 2026 18:56:13 +0100 Subject: [PATCH 2/5] docs: Update changelog and decisions for QSP enforcement changes Co-Authored-By: Claude Opus 4.6 --- docs/CHANGELOG.md | 4 ++++ docs/DECISIONS.md | 9 +++++++++ 2 files changed, 13 insertions(+) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 7a7b439..0715b6a 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -43,6 +43,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- Quick (Q) path now ships changes to production -- previously ended at local commit with no push or CI verification, so fixes never reached the remote +- QSP task classification is now the first section in CLAUDE.md -- previously buried at the bottom where it was easily skipped +- All development paths (Q, S, P) now require a pre-flight git sync before starting work -- prevents push rejections from stale local branches + - Setup script now correctly renames package names inside pyproject.toml and __init__.py files when customizing packages beyond the defaults - Additional packages created by setup script now get correct project-prefixed names instead of inheriting the template source package name (e.g., vizier-engine instead of vizier-core when adding engine package) - Root pyproject.toml no longer includes a [build-system] section that caused hatchling build failures in workspace mode diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 71c3a81..578a62f 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -78,3 +78,12 @@ When a decision is superseded or obsolete, delete it (git history preserves the - Review rules have no `paths:` frontmatter (apply globally) and stay under 80 lines -- loaded into every context window - CLAUDE.md kept compact per ETH Zurich paper decision; detailed hooks/commands/rules tables added to DEVELOPMENT_PROCESS.md instead - CI review workflow uses claude-sonnet-4-6 with read-only tools (Read, Glob, Grep) -- security principle of least privilege + +## 2026-03-02: QSP Enforcement and Pre-flight Sync + +**Request**: Fix three process failures: QSP classification ignored until reminded, no git sync before work (caused push rejection), no branch confirmation. + +**Decisions**: +- QSP classification moved to first section in CLAUDE.md -- being last made it easy to skip +- New "Pre-flight (all paths)" section in DEVELOPMENT_PROCESS.md with mandatory git sync and explicit classification -- applies before Q, S, or P begins +- Redundant `git fetch` removed from S.3 -- now centralized in pre-flight From e661c65a0023a9bf73fd3f39d9bbff8c2d5d35c5 Mon Sep 17 00:00:00 2001 From: Martin Stransky Date: Mon, 2 Mar 2026 18:56:53 +0100 Subject: [PATCH 3/5] fix: Add no-unnecessary-cd rule and fix typo in CLAUDE.md Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index f3fc2d7..1ae792f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,6 +31,8 @@ uv run ruff format . # Format uv run pyright # Type check ``` +Do not use unnecessary cd like `cd /path/to/cwd && git log`. + ## Code Style - **Docstrings**: reStructuredText format, PEP 257 From 8c4263daf64acda1283ecc9ab4524137bdd0ffdb Mon Sep 17 00:00:00 2001 From: Martin Stransky Date: Mon, 2 Mar 2026 18:58:52 +0100 Subject: [PATCH 4/5] fix: Address CodeRabbit review feedback - Add rebase guidance to pre-flight sync step for out-of-sync branches - Clarify "base branch" means main/master at first usage in Q path Co-Authored-By: Claude Opus 4.6 --- docs/DEVELOPMENT_PROCESS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md index 4bf12ec..d7112fd 100644 --- a/docs/DEVELOPMENT_PROCESS.md +++ b/docs/DEVELOPMENT_PROCESS.md @@ -33,7 +33,7 @@ Task complexity determines process depth. Classify each task, then follow the ma Before making any changes: -1. **Sync** -- `git fetch origin && git status` to confirm you are on the correct branch and up to date with remote +1. **Sync** -- `git fetch origin && git status` to confirm you are on the correct branch and up to date with remote. If behind, pull or rebase before proceeding 2. **Classify** -- state the QSP classification to the user before proceeding --- @@ -42,7 +42,7 @@ Before making any changes: 1. **Fix it** -- make the change 2. **Validate** -- run `uv run ruff check . && uv run ruff format --check . && uv run pytest` -3. **Commit and push** -- push directly to the base branch +3. **Commit and push** -- push directly to the base branch (`main`/`master`) 4. **Verify CI** -- run `gh run watch` to confirm the triggered run passes If branch protection is enabled: after step 2, push to a short-lived branch, run `gh pr create --fill && gh pr checks --watch`, merge, and delete the branch. From 135107168741ca01f72f476963c29ed4e1d376a2 Mon Sep 17 00:00:00 2001 From: Martin Stransky Date: Mon, 2 Mar 2026 19:01:21 +0100 Subject: [PATCH 5/5] fix: Split S.6 review into sequential automated then manual steps S.6.4 combined automated and manual review with "or" wording, making it easy to skip CodeRabbit. Now S.6.4 waits for automated reviewer and S.6.5 runs manual code review, enforcing the correct order. Co-Authored-By: Claude Opus 4.6 --- docs/DEVELOPMENT_PROCESS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md index d7112fd..687c862 100644 --- a/docs/DEVELOPMENT_PROCESS.md +++ b/docs/DEVELOPMENT_PROCESS.md @@ -81,7 +81,8 @@ All agents use `subagent_type: "general-purpose"`. Do NOT use `feature-dev:code- 1. Commit and push 2. Create PR (use `.claude/agents/pr-writer.md` agent to generate description) 3. Verify CI with `gh pr checks` -4. Code review: use `.claude/agents/code-reviewer.md` agent, or `.claude/agents/review-responder.md` if an automated reviewer (e.g., CodeRabbit) is configured. Fix Critical issues before merge. +4. Wait for automated reviewer (e.g., CodeRabbit). When comments arrive, use `.claude/agents/review-responder.md` to triage and fix. Push fixes before proceeding. +5. Code review: use `.claude/agents/code-reviewer.md` agent. Fix Critical issues before merge. **S.7 Document** -- Update `docs/CHANGELOG.md` with user-facing changes and `docs/DECISIONS.md` with decisions made. Use `.claude/agents/docs-updater.md` to verify. @@ -132,8 +133,8 @@ All custom agents are in `.claude/agents/` and use `subagent_type: "general-purp | S.5 | `code-quality-validator.md` | Lint, format, type check | | S.5 | `test-coverage-validator.md` | Tests and coverage | | S.6.2 | `pr-writer.md` | Generate PR description | -| S.6.4 | `code-reviewer.md` | Independent code review | | S.6.4 | `review-responder.md` | Handle automated reviewer comments | +| S.6.5 | `code-reviewer.md` | Independent code review | | S.7 | `docs-updater.md` | Verify and update documentation | | P.3.2 | `acceptance-criteria-validator.md` | Verify acceptance criteria | | P.3.3 | `implementation-tracker.md` | Verify plan matches reality |