nalalangan/grocery-app
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: document workflow guardrails

Browse Source
This commit is contained in:
Nico 2026-05-26 00:37:33 -07:00
parent a2c08aff45
commit 905f7256fa
1 changed files with 83 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
PROJECT_INSTRUCTIONS.md
View File

@ -19,6 +19,15 @@ If anything conflicts, follow **this** doc.
- Dev/Prod share schema via migrations in: `packages/db/migrations`. - Dev/Prod share schema via migrations in: `packages/db/migrations`.
- Active migration runbook: `docs/DB_MIGRATION_WORKFLOW.md` (active set + status commands). - 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 background jobs
- **No cron/worker jobs**. Any fix must work without background tasks. - **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. - 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). - 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: - Each commit must:
- follow Conventional Commits style (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`) - follow Conventional Commits style (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
- include only related files for that slice - include only related files for that slice
- exclude secrets, credentials, and generated noise - 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). - 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. - 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. - 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). - 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`.