PROJECT_INSTRUCTIONS.md

@@ -19,6 +19,15 @@ If anything conflicts, follow **this** doc.
 - Dev/Prod share schema via migrations in: `packages/db/migrations`.
 - Active migration runbook: `docs/DB_MIGRATION_WORKFLOW.md` (active set + status commands).
 
+### Docker dev runtime
+- After backend/API code changes while using `docker-compose.dev.yml`, rebuild and restart only the backend service:
+  - `docker compose -f docker-compose.dev.yml up -d --build backend`
+- After backend env/CORS changes, recreate the backend service so `backend/.env` is reloaded:
+  - `docker compose -f docker-compose.dev.yml up -d --force-recreate --no-deps backend`
+- For the Docker frontend on port `3010`, `ALLOWED_ORIGINS` must include the exact browser origin, for example `http://localhost:3010` and `http://127.0.0.1:3010`.
+- Verify the restarted API with `GET http://127.0.0.1:5000/` and `GET http://127.0.0.1:5000/config`.
+- Do not print or commit real `.env` values while checking or updating local Docker env.
+
 ### No background jobs
 - **No cron/worker jobs**. Any fix must work without background tasks.
 
@@ -192,14 +201,87 @@ Usage rules:
 
 ---
 
-## 12) Commit Discipline (required)
+## 12) Git Intake, Branching, Commit, and PR Discipline (required)
+
+### Read-only intake before editing
+Before editing, run this read-only intake:
+- `git status --short --branch`
+- `git branch -vv`
+- `git log --oneline --decorate -8`
+- `git ls-files --others --exclude-standard`
+- Check current PR status when GitHub CLI is available.
+- Check open PRs for overlapping work before editing shared or collision-prone areas.
+
+### Branch suitability gate before editing
+- Continue on the current branch only when the requested work belongs to that branch or PR.
+- Start independent work from `main` after pulling latest.
+- Start stacked work from the current PR branch when the work intentionally builds on that PR.
+- If the current branch purpose does not match the request, stop before editing and switch or create the correct branch.
+- If either `main` or the current branch could be valid, ask whether the work is independent side work or required follow-on work.
+- Do not layer unrelated work on top of a dirty worktree.
+- If unrelated local changes exist, pause and ask how to separate them.
+
+### Branch creation and naming
+- Create a descriptive branch before writing code.
+- Preferred branch prefixes:
+  - `feature/<short-description>`
+  - `bugfix/<short-description>`
+  - `refactor/<short-description>`
+  - `chore/<short-description>`
+  - `spike/<short-description>`
+- Do not include tracker numbers in branch names.
+- Use standalone branches from `main` for independent work.
+- Use stacked branches from the parent PR branch for follow-on work.
+- Target standalone PRs at `main`.
+- Target stacked PRs at the parent PR branch.
+- Never push directly to `main`.
+
+### Commit discipline
 - Treat committing as a first-class part of the workflow: create frequent, verified checkpoint commits for completed work instead of accumulating large uncommitted changes.
+- Commit after each coherent logical unit of work.
 - Commit in small, logical slices (no broad mixed-purpose commits).
+- Before committing:
+  1. Run `git diff --stat`.
+  2. Run relevant tests or checks when practical.
+  3. Stage only files that belong to the logical unit.
+  4. Run `git diff --cached --stat`.
+  5. Commit with an imperative, present-tense subject at or below 72 characters.
 - Each commit must:
   - follow Conventional Commits style (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
   - include only related files for that slice
   - exclude secrets, credentials, and generated noise
+- Do not stage unrelated user or collaborator changes.
+- Do not start a second unrelated task while the first has uncommitted work.
+- If existing local changes are external/user changes, leave them untouched unless explicitly told otherwise.
+- If asked to commit and external changes already exist, commit those separately on the proper branch before starting new work.
 - Run verification before commit when applicable (lint/tests/build or targeted checks for touched areas).
 - Prefer frequent checkpoint commits during agentic work rather than one large end-state commit.
 - Before switching tasks or stopping after a completed change, check git status and either commit the finished slice or clearly document why it remains uncommitted.
 - If a rule or contract changes, commit docs first (or in the same atomic slice as enforcing code).
+
+### Push and PR coordination
+- Push the branch before opening a PR.
+- Open a draft PR early for non-trivial, collision-prone, or multi-agent work once the first coherent commit exists.
+- Use the PR body as the coordination record:
+  - `Owner:`
+  - `Status: proposed / in-progress / blocked / review / done`
+  - `Branch:`
+  - `Branch relationship: standalone from main / stacked on parent branch / continuing existing branch`
+  - `Likely modified areas:`
+  - `Actual modified files:`
+  - `Collision risk: low / medium / high`
+  - `Last meaningful update:`
+- Collision risk levels:
+  - Low: isolated docs, tests, or one leaf component.
+  - Medium: shared stores/types, panels/components, handlers, helpers.
+  - High: interface contracts, broad app flows, core registries, cross-cutting behavior.
+- If a branch already contains assigned feature work and has no current PR, stop before adding more feature commits. Push the branch and open a draft PR, or record the GitHub/auth blocker.
+- Before writing or updating the final PR body, inspect:
+  - `git log <base>..HEAD`
+  - `git diff --stat <base>..HEAD`
+- The PR should describe the cumulative branch diff against the target branch, not only the latest commit.
+- Include:
+  - Summary of functional changes.
+  - Tests run, or a clear reason tests were not run.
+  - For broad branches, organize the summary by subsystem, workflow, or behavior area.
+- Do not use auto-closing keywords such as `Closes`, `Fixes`, or `Resolves`.