patchmemory · patchmemory · Jan 13, 2026 · Jan 12, 2026 · Jan 13, 2026 · Jan 13, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,42 +1,24 @@
-Title: E2E foundation, contracts, and CI
-
-Summary
-- Implements Playwright E2E scaffold with smoke + core flow specs (browse, scan)
-- Adds minimal API contracts for /api/scan, /api/scans/<id>/status, /api/directories
-- Aligns Dev CLI timestamps to timezone-aware ISO8601
-- Adds stable data-testid hooks to UI templates
-- Wires CI for pytest and strict E2E smoke
-- Updates docs/testing.md with quickstarts and CI notes
-
-Related
-- Story: story:e2e-testing
-- Phase: 02–03
-- Task(s):
-  - task:e2e:02-playwright-scaffold (Done)
-  - task:e2e:03-core-flows (partially addressed by initial specs; remaining flows in next branch)
-
-Local verification
-- Python tests: python -m pytest -q → green
-- Playwright E2E: npm install && npx playwright install --with-deps && npm run e2e → green
-
-CI
-- GitHub Actions workflow runs:
-  - Python tests (3.11)
-  - E2E smoke (Node 18) — strict, SCIDK_PROVIDERS=local_fs
-
-How to run locally
-- API contracts: python -m pytest tests/contracts/test_api_contracts.py -q
-- E2E: npm run e2e (uses e2e/global-setup.ts to boot the Flask server)
-
-Risk assessment
-- Low risk. Mostly additive tests/config/docs. UI changes limited to data-testid attributes.
-
-Merge checklist
-- [x] pytest green locally
-- [x] E2E green locally
-- [x] CI expected to pass (strict E2E)
-- [x] task:e2e:02-playwright-scaffold marked Done with completed_at
-- [ ] Reviewer sanity pass on docs/testing.md and CI workflow
-
-Post-merge (follow-up branch)
-- Expand Phase 03 core flows E2E and refine contracts as needed.
+# PR Title
+
+## Summary
+- Short description of the change and why.
+
+## Linked Work
+- Story/Phase: <!-- e.g., story:e2e-testing / phase:e2e-testing/01-smoke-baseline -->
+- Task: <!-- e.g., task:e2e:01-smoke-baseline -->
+
+## Checklist
+- [ ] Single active branch: This PR represents my current active branch (exceptions justified below).
+- [ ] CI green: Unit tests and smoke checks pass (or expected failures explained).
+- [ ] Scope focused: PR covers a single topic and is sized for quick review.
+- [ ] Docs updated: README/docs touched if behavior/workflow changed.
+- [ ] Tests: Added/updated tests or rationale why not needed.
+- [ ] Merge strategy: Prefer rebase onto main; no local merges from other feature branches.
+
+## Demo Steps (if UI/API visible)
+1. 
+2. 
+3. 
+
+## Exceptions / Notes
+- If working on multiple branches concurrently, document why and link related PRs.
diff --git a/README.md b/README.md
@@ -57,6 +57,9 @@ Note: The scanner prefers NCDU for fast filesystem enumeration when available. I
 - Editable install error (Multiple top-level packages discovered): We ship setuptools config to include only the scidk package. If you previously had this error, pull latest and try again: `pip install -e .`.
 - Shell errors when initializing env: Use the script matching your shell (`init_env.sh` for bash/zsh, `init_env.fish` for fish). Avoid running `sh scripts/init_env.sh`; instead, source it.
 
+## Branching & CI Policy
+To keep CI reliable and PRs easy to review, we follow a simple workflow: one active feature branch per contributor, open small PRs early, and let CI be the gate before merge. See docs/branching-and-ci.md for details and a PR checklist.
+
 ## End-to-End (E2E) tests
 
 These tests run in a real browser using Playwright and pytest. The test suite automatically starts the Flask app on port 5001 with safe defaults and no external Neo4j connection.

diff --git a/docs/branching-and-ci.md b/docs/branching-and-ci.md
@@ -0,0 +1,38 @@
+# Branching and CI Policy
+
+Goal: Keep the development flow simple and reliable by working on one active branch at a time and relying on CI to validate changes before merge.
+
+## Principles
+- One active feature branch at a time per contributor.
+- Open a Pull Request early and keep it small and focused.
+- Let CI be the gate: do not merge locally; wait for required checks to pass.
+- Prefer incremental PRs (fast review, fast CI) over large multi‑day PRs.
+- If you must work on a second branch, document the reason in the PR description and link to the primary branch/PR.
+
+## Recommended Flow
+1) Create a branch from the default base (main):
+   - `git switch -c chore/<short-topic>`
+2) Push and open a PR as soon as there is a coherent change:
+   - `git push -u origin HEAD`
+3) Keep commits small; push frequently. Let CI run.
+4) If CI fails, fix forward on the same branch; avoid force‑push unless rebasing noise.
+5) Rebase/update with main when green to reduce drift:
+   - `git fetch origin && git rebase origin/main`
+6) Merge via the PR when required checks pass.
+
+## PR Checklist
+- [ ] The PR covers a single topic; scope is clear in the title/description.
+- [ ] Linked story/task and acceptance criteria listed.
+- [ ] Tests added/updated; CI is green or expected failures are explained.
+- [ ] Docs updated (README or docs/*) if behavior or workflow changed.
+- [ ] Justification added if working on multiple branches concurrently.
+
+## CI Expectations
+- Unit tests and smoke checks run on every PR.
+- E2E smoke (where applicable) runs within a few minutes (<5s/spec target).
+- Required checks must be green before merge.
+
+## Tips
+- Use `python -m dev.cli ready-queue` to confirm current priorities.
+- Avoid local merges between feature branches; rebase onto main instead.
+- If a PR is taking too long, split it into smaller, independently shippable parts.
diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md
@@ -32,6 +32,8 @@ Notes:
 - Show prioritized Ready Queue: `python -m dev.cli ready-queue`
 - Validate a task file: `python -m dev.cli validate task:e2e:01-smoke-baseline`
 - Start working on the top task: `python -m dev.cli start`
+- Branch hygiene (non-blocking): `python -m dev.cli branch-guard` (add --json for machine-readable)
+- Finish the git (stage, commit, push, print PR link): `python -m dev.cli git-finish -m "chore: update docs"` (add --json for structured output)
 
 ## Active Story & Phase
 - See `dev/cycles.md` for the current Active Story/Phase pointer.
@@ -44,3 +46,6 @@ Notes:
 - If running headless in CI, confirm browsers are installed (`playwright install`).
 - If optional deps (openpyxl/pyarrow) are not installed, related export tests will be skipped or should target CSV-only paths.
 - Check server logs for endpoint errors during tests (`/api/interpreters*`, `/api/scans/<id>/interpret`).
+
+## Process note
+- We keep one active branch per contributor and rely on CI as the gate. See docs/branching-and-ci.md for details and a short PR checklist.