diff --git a/PROJECT_INSTRUCTIONS.md b/PROJECT_INSTRUCTIONS.md index 4b75b70..4b31bb0 100644 --- a/PROJECT_INSTRUCTIONS.md +++ b/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/` + - `bugfix/` + - `refactor/` + - `chore/` + - `spike/` +- 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 ..HEAD` + - `git diff --stat ..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`.