# AI-native SDLC: how this repo adapts the handoff

`HANDOFF.md` is the generic playbook. This page records every place blu2green deviates from it and
why. If the two disagree, this page wins for this repo.

| Handoff says | This repo does | Why |
|---|---|---|
| GitHub, `.github/workflows/claude.yml`, `/install-github-app` (§5.12) | **AWS CodeCommit**. PR review by a **local LLM on the office GPU** via `tools/ai-review/review_pr.php`, plus a mandatory local `/code-review` | Remote is `git-codecommit.ap-south-1…/blu2green`; no GitHub App exists for CodeCommit. A local model keeps diffs inside the office |
| Hooks in bash + `jq` (§5.4–5.6) | Hooks in **PHP, no extensions or Composer** (`.claude/hooks/*.php`), written to parse on PHP 7.3+ | The team works in PHP, so they can read and own the guardrails. `jq` is not installed on dev machines. The hooks must parse on any XAMPP `php` on PATH: a hook that fails to parse does not block, so its protection would silently switch off. The tools (`evals/check.php`, `tools/ai-review/`, `tools/ai-usage/`) need PHP 8.2. Python is still needed for the CI guards (`ci/*.py`) |
| `src/<module>/CLAUDE.md` (§5.8) | One `CLAUDE.md` at the root of **each of the 18 services** in `ci/service-map.json` (e.g. `b2g_usermgmt/CLAUDE.md`, `docker/kong/CLAUDE.md`) | There is no `src/`. Each service folder is the module |
| PR template in `.github/` | `docs/ai-sdlc/PULL_REQUEST_TEMPLATE.md`, which you paste into the CodeCommit PR description | CodeCommit has no native PR templates |
| Branch protection "require PR + code-owner approval" | Already in place: IAM `DenyDirectPushToMain` + approval rule `b2g-require-one-approval` (see `ci/branch-gating/README.md`, `docs/codecommit-workflow.md` §3) | Nothing new needed. The authoring agent never approves |
| `production-gate.sh` matches `deploy` + `prod` | `production_gate.php` also blocks **any `git push` to `prelive` or `main`**, `ci/pipeline.py deploy`, `aws ecs update-service`, CodeCommit merges and `aws iam` | **`prelive` is ungated: a push deploys `b2g-demo` automatically.** A push is a deploy here |
| `protect-paths.sh` blocks `/generated/`, `/legacy/`, `*.lock` | `protect_paths.php` blocks `vendor/`, `node_modules/`, `dist/`, lockfiles, `.env`, Kong secrets, `ci/curl-timeout-baseline.txt`, formerly committed build output | These are the paths that have broken builds or leaked secrets here |
| "The developer commits" (§2 rule 1, a written rule only) | **Hook-enforced:** `production_gate.php` blocks Claude from `git commit`/`merge`/`rebase`/`cherry-pick`/`revert`/`am` and `pull` without `--ff-only`, even with `RELEASE_APPROVAL`. Claude does not draft commit messages; it reviews the developer's draft against the diff. `.gitmessage` + `.githooks/commit-msg` require a real subject and an `AI-Assisted: yes (model) | no` line | Writing the summary yourself proves you read and understood the change. The `AI-Assisted:` line replaces Claude's `Co-Authored-By` trailer in the usage report (`tools/ai-usage/`) |
| Test filter for `npm test`/`pytest`/… | `filter_test_output.php` handles `ng test`, `npm test`, `npm run lint`; forces `--watch=false`; **keeps the exit code** | Karma watches by default and would hang a session; the handoff's grep pipe hid pass/fail |
| `.mcp.json` with GitHub + DB | **`db` (read-only MySQL via DBHub)** and **`playwright`** | No GitHub. Jira not wired yet |
| Build / test / lint commands | `php -l`, `python ci/ns-case-check.py`, `python ci/curl-timeout-check.py`, `npx ng build --configuration=docker`, `npm run lint` (gMarket, nibe FE only) | No PHPUnit in CI; the static guards plus the container smoke test are the real gate |

## Read-only DB user for the `db` MCP server

Never point an agent at a read-write account. Ask a DBA to create a SELECT-only user once per
environment:

```sql
CREATE USER 'claude_ro'@'%' IDENTIFIED BY '<generated>';
GRANT SELECT ON `bgi_b2g_reg_dev`.*      TO 'claude_ro'@'%';
GRANT SELECT ON `bgi_b2g_master_dev`.*   TO 'claude_ro'@'%';
GRANT SELECT ON `bgi_b2g_cengex_dev`.*   TO 'claude_ro'@'%';
GRANT SELECT ON `bgi_b2g_digitall_dev`.* TO 'claude_ro'@'%';
GRANT SELECT ON `bgi_b2g_gmarket_dev`.*  TO 'claude_ro'@'%';
```

Then set it in **your own** environment, never in a committed file:

```bash
export DATABASE_URL_READONLY='mysql://claude_ro:<password>@127.0.0.1:3306/bgi_b2g_master_dev'
```

Use the dev databases only. Production data stays off developer machines (see `docs/db-access.md`).

## Getting started (per developer)

1. Pull this branch and open the repo in VS Code with the Claude Code extension.
2. Run `/hooks` and check you see three PreToolUse hooks. Run `php evals/check.php`; it should
   pass.
3. Turn on the commit template and message check (once per clone):
   `git config commit.template .gitmessage && git config core.hooksPath .githooks`.
   Claude cannot commit for you; you write every message, including the `AI-Assisted:` line.
4. Optional: set `DATABASE_URL_READONLY`, then run `/mcp` to check `db` and `playwright` connect.
5. Read `HANDOFF.md` §2 (the working agreement). It is mandatory.
6. For your next ticket, start at `intent/README.md`.