gdc_cmod/AGENTS.md

# AGENTS.md
Guidance for coding agents working in `D:\data\www\gdc_cmod`.

## 1) Repository Summary
- Stack: CodeIgniter 4 + PHP 8.1+.
- Package manager: Composer.
- Test framework: PHPUnit 10 (`phpunit.xml.dist`).
- App domain: laboratory workflow (requests, samples, validation, reporting).
- Auth: session-based, route filters (`role`, `guest`).
- Data sources: SQL Server (`GDC_CMOD.dbo`) + legacy Firebird integration.
- Frontend: PHP views with Tailwind/DaisyUI/Alpine assets from `public/`.

## 2) Rule Files Check
- Cursor rules: not found (`.cursor/rules/` and `.cursorrules` absent).
- Copilot rules: not found (`.github/copilot-instructions.md` absent).
- If these files are later added, treat them as high-priority instructions.

## 2.1) Codebase-Memory MCP Workflow (Default)
- This repository is indexed in `codebase-memory-mcp` (session project `D-data-www-gdc_cmod`).
- Before broad architecture analysis, run:
  - `index_status` (confirm graph is ready)
  - `get_architecture` for `languages`, `packages`, `layers`, `file_tree`
- Prefer `search_graph` + `get_code_snippet` + `trace_call_path` for impact/call-chain questions.
- For change impact before commits, use `detect_changes(scope='all'|'branch')`.
- Important: results can be noisy due to minified vendor assets in `public/js/*.min.js`.
- When querying routes/hotspots, scope to app PHP files (`file_pattern='app/**/*.php'`) where possible.

## 3) Core Commands
```bash
# install deps
composer install

# run dev server
php spark serve

# list spark commands
php spark

# list routes (preferred)
php spark routes

# alternate command used in this repo
php spark list
```

## 4) Test Commands (Use These)
```bash
# full suite
composer test

# full suite (direct)
./vendor/bin/phpunit

# windows direct
vendor\bin\phpunit

# single test file
./vendor/bin/phpunit tests/unit/ReportTest.php

# single test class
./vendor/bin/phpunit --filter ReportTest

# single test method
./vendor/bin/phpunit tests/unit/HealthTest.php --filter testIsDefinedAppPath

# single test directory
./vendor/bin/phpunit tests/unit
```

## 5) Lint / Static Analysis
- No dedicated linter/formatter configs were found (`phpcs`, `php-cs-fixer`, `pint`).
- No static analysis configs were found (`phpstan`, `psalm`).
- Use syntax lint for changed PHP files:
```bash
php -l app/Controllers/RequestsController.php
php -l app/Config/Routes.php
```
- If you add QA tooling, update this file with exact commands.

## 6) Code Organization
- Controllers: `app/Controllers` and `app/Controllers/Pages`.
- Filters: `app/Filters`, aliases in `app/Config/Filters.php`.
- Routes: `app/Config/Routes.php`.
- Views: `app/Views/...`.
- Tests: `tests/unit`, `tests/database`, `tests/session`, `tests/_support`.
- Most DB access uses raw SQL (`\Config\Database::connect()`), not CI models.

## 7) Style Rules (PHP)

### Imports and namespaces
- Keep valid namespace per folder.
- Use `use` imports for frequently referenced classes.
- Remove unused imports.
- Keep one class per file.

### Formatting
- Prefer 4 spaces in new/edited code.
- Existing files may contain mixed tabs/spaces; avoid full-file reformat churn.
- Keep methods small; extract helpers for complex branching.
- Keep comments sparse; only explain non-obvious logic.

### Types
- Add parameter and return types in new/modified methods when practical.
- Prefer explicit casts for session/DB values used in role or numeric logic.
- Prefer strict comparisons (`===`, `!==`) over loose comparisons.

### Naming
- Classes: `PascalCase`.
- Methods/variables: `camelCase`.
- Constants: `UPPER_SNAKE_CASE` (`ROLE_NAMES`).
- SQL identifiers follow existing DB naming (often uppercase).
- Views use existing naming conventions (lowercase/underscores).

## 8) Imports, Responses, and Controller Patterns
- API endpoints commonly use `CodeIgniter\API\ResponseTrait`.
- JSON responses: `$this->response->setJSON([...])` or `$this->respond([...])`.
- HTML responses: `return view('path/to/view', $data);`.
- Inputs: `getGet()`, `getPost()`, `getJSON(true)` based on content type.
- Validate required inputs early and return errors promptly.

## 9) SQL and Data Safety
- Prefer parameterized queries for all user/session-controlled values.
  - Good: `$db->query('... WHERE ACCESSNUMBER = ?', [$accessNumber]);`
  - Avoid: SQL string interpolation with raw request/session data.
- Use transactions for multi-step writes that must be atomic.
- Preserve dual-validation behavior (`ISVAL1/ISVAL2`, two distinct users).
- Keep audit logging writes (`AUDIT_EVENTS`, `AUDIT_REQUESTS`) intact when changing flows.

## 10) Error Handling and Logging
- Return consistent JSON shape for API failures (`status`, `message`).
- For external HTTP/cURL calls, check HTTP code and handle failures explicitly.
- Use `log_message('error', ...)` for operational failures.
- Do not expose secrets, stack traces, or sensitive internals to clients.

## 11) Security Requirements
- Escape user-facing output in views with `esc()`.
- Enforce auth + role checks through route filters and session state.
- Use `password_hash()` and `password_verify()` for credentials.
- Never commit `.env` or secrets.

## 12) Role and Routing Conventions
- Role IDs:
  - `0` Superuser
  - `1` Admin
  - `2` Lab
  - `3` Phlebo
  - `4` CS
- Route filter examples:
  - Single role: `['filter' => 'role:1']`
  - Multiple roles: `['filter' => 'role:0,1,2']`

## 13) Agent Change Checklist
- Make minimal, targeted changes.
- Do not revert unrelated local modifications.
- Keep backward compatibility for response payloads unless asked otherwise.
- Run at least one relevant test file after code changes.
- If no tests exist for a changed behavior, add focused tests when feasible.
- Update this file when commands/conventions/tooling change.