# Dinex Project

## Permissions & Behavior

- Do not ask for confirmation on routine file edits, migrations, or model changes.
- Proceed autonomously with standard Laravel tasks (migrations, model updates, controller changes, route edits).
- Only ask before destructive or irreversible operations (dropping tables with data, force-pushing, deleting untracked files).

## Knowledge Base Maintenance

Business logic is documented per-module under `docs/kb/`. **The 11 module files (`00-…` to `10-…`) are the only files anyone edits.** `docs/kb/BUSINESS_KNOWLEDGE_BASE.md` is **generated** by `scripts/build-kb.sh` (concatenates the module files with a "generated, do not edit" banner) — it's the combined copy used for search (e.g. uploaded to the Claude project); never hand-edit it. See `docs/kb/README.md` for the full file index and `KB_CHANGELOG.md` for dated history.

| File | Module |
|---|---|
| `docs/kb/00-system-context.md` | System overview |
| `docs/kb/01-authentication.md` | Auth, roles & permissions |
| `docs/kb/02-branches.md` | Branches & branch settings |
| `docs/kb/03-menu-catalog.md` | Categories, items, attributes, ingredients |
| `docs/kb/04-order-management.md` | POS order core (pricing, payments, status) |
| `docs/kb/05-external-platform-orders.md` | Mobile app / platform order integration |
| `docs/kb/06-day-close-dsr.md` | Day close & Daily Sales Report |
| `docs/kb/07-reports-charts-settings.md` | Head-office reports, charts, settings |
| `docs/kb/08-noon-delivery.md` | Noon delivery integration |
| `docs/kb/09-commercial-config.md` | Payment types, order types, promo codes |
| `docs/kb/10-cross-cutting-reference.md` | Glossary, constants, config, consolidated TODOs/risks/open questions |

Each file starts with a standard header:
```
> **KB version:** 2.0 · **Code baseline:** <short commit at HEAD> · **Last reviewed:** <YYYY-MM-DD>
> **Epic:** EP-N · **Status:** Reviewed | Pending PO review
> **Pending PO review:** <bullets, or "none">
> **Related flags:** AB-xx, … · **Open decisions:** OD-xx, …
```

**Module files describe what the system does now, in present tense — no inline history.** Don't write `🚩 SPRINT 1`, `~~strikethrough~~`, "fixed 2026-…", "previously … now …", etc. into a rule. A rule that came from an unreviewed/unconfirmed change is still written as a plain, timeless rule — mark it unreviewed only in that file's header `**Pending PO review:**` bullet list, not inline in the prose. All dated/historical framing goes in `KB_CHANGELOG.md` instead.

**Whenever a code change alters business behavior** (pricing/tax rules, status transitions, validation, a new endpoint, a fixed bug that changes documented behavior, a new business rule) — not routine refactors or comment-only changes:

1. Identify which module file(s) the change actually affects. A change can touch more than one (e.g. a Noon webhook change usually touches both `08-noon-delivery.md` and `05-external-platform-orders.md`).
2. Update **only those files** — don't touch unrelated module files, and don't regenerate the whole set from scratch.
3. Write the change as a timeless rule in the relevant section (Business Rules / Hidden Rules / Decision Tree / Database Understanding / State Machine / APIs / Edge Cases — keep the 13-heading template, `## Evidence` last). Bump that file's header: `Code baseline` to the current commit, `Last reviewed` to today, and add the rule to `Pending PO review:` if it hasn't been confirmed by the PO yet (set `Status: Pending PO review` if it wasn't already).
4. Add a dated entry to `KB_CHANGELOG.md` (newest section on top; create a new date heading if needed) describing what changed and why — this is where the "history" lives now, not in the module file.
5. If replacing/contradicting an existing documented rule, don't delete the old rule silently — note the change in `KB_CHANGELOG.md` so the "why did this change" trail survives.
6. **If a single piece of work touches 2+ module files, update them with separate parallel subagents (one agent per affected file, dispatched together), not sequentially in the main conversation.** This keeps the update fast and keeps the coordinating session's own context small — each subagent reads only its target file plus the specific code diff relevant to it, makes the edit, and reports back a one-line summary. For a change touching only one file, just edit it directly — spawning an agent for a single-file, single-fact update is unnecessary overhead.
7. Never invent business rules or decisions — if something is genuinely unclear from the code, add it under that file's "Open Questions" section (reference an `OD-xx` id if one exists) instead of guessing.
8. After editing, run `./scripts/build-kb.sh` to regenerate the combined file, and `./scripts/check-kb.sh` to confirm it's in sync before committing.