fullstack-critic 1.0.0

package/README.md

@@ -0,0 +1,227 @@
+# Full-Stack Critic
+
+A free, universal senior engineering critic for any software project.
+Install it as a package or drop it into any repository, and it reviews **100% of your
+resources — every source file, package, and dependency** across 12 dimensions, finds real
+issues with exact evidence, and returns a detailed report with a prioritised action plan
+grouped into **FIX · OPTIMIZE · DELETE · ADD**.
+
+**No account. No paid service. Zero runtime dependencies.**
+Install with npm / pnpm / yarn / npx, or use it as an AI rubric with Composio,
+Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qoder, Antigravity, or any assistant.
+
+---
+
+## Install & run (no AI required)
+
+> **Status: not yet on the public npm registry.** `npx fullstack-critic` and
+> `npm i -g fullstack-critic` will `404` until this repo is published (`npm publish`).
+> Until then, install **from this folder** — the commands below are tested and work.
+
+```bash
+# From inside this folder — install the CLI globally so `critic` works in any project:
+npm install -g .            # or:  npm link
+# or install by path from anywhere:
+npm install -g C:\path\to\fullstack-critic
+
+# No install at all — run straight from the folder:
+node bin\fullstack-critic.js review .          # Windows
+node bin/fullstack-critic.js review .          # macOS / Linux
+npx --yes /path/to/fullstack-critic review .   # npx against a local folder/git
+```
+
+```bash
+critic review .                 # one-shot review of code + packages + dependencies, with verdict
+critic watch .                  # attach to an in-progress workflow: continuous feedback as you edit
+critic init .                   # attach the AI rubric (.critic/ + .critic-memory/ + PROJECT_REVIEW.md)
+critic audit .                  # run each detected package manager's own audit (npm audit, pip-audit…)
+critic review . --md report.md --fail-on high   # write a full report; fail CI on HIGH+
+```
+
+`critic watch` re-analyses a few hundred ms after every change and prints only what
+appeared (`+ NEW`) or was fixed (`- FIXED`), keeping a live `.critic-report.md`. It ignores
+`node_modules`, build output, `.git`, and its own outputs. Full guide: [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
+
+---
+
+## Use it as an AI rubric instead
+
+```bash
+# Recommended: git submodule (keeps your working tree clean)
+git submodule add https://github.com/amansingh79033-ship-it/fullstack-critic .critic
+
+# Or a plain clone into a subfolder, or run `critic init .` to do this for you
+git clone https://github.com/amansingh79033-ship-it/fullstack-critic .critic
+```
+
+Then tell your AI:
+
+```
+Read .critic/CRITIC.md and do a full review of this project.
+```
+
+The critic attaches passively. REVIEW mode is read-only — it never touches your source files,
+starts no processes, and does not affect any running dev server, CI job, or coding session.
+FIX mode only changes files you explicitly ask it to fix.
+
+**Minimum required files** (if you only want to copy, not clone):
+- `CRITIC.md` — the core rubric
+- `layers/manifest.md` — layer selection guide
+
+---
+
+## What it reviews — 12 dimensions, every project
+
+| # | Dimension | What gets checked |
+|---|-----------|-------------------|
+| 1 | **Correctness** | Logic errors, race conditions, null handling, boundary cases, error propagation |
+| 2 | **Security** | Injection, broken auth, IDOR, XSS/CSRF/SSRF, secrets, CVEs, data exposure |
+| 3 | **Architecture** | Separation of concerns, coupling, patterns, config discipline, dead abstractions |
+| 4 | **API design** | HTTP semantics, versioning, validation, error shapes, rate limiting |
+| 5 | **Backend** | Blocking I/O, timeouts, retry logic, connection pools, graceful shutdown |
+| 6 | **Database** | Missing indexes, N+1 queries, unbounded queries, transactions, migrations |
+| 7 | **Frontend** | Bundle size, code splitting, render performance, Core Web Vitals, accessibility |
+| 8 | **Performance** | Bottlenecks, cache strategy, horizontal scaling blockers, resource leaks |
+| 9 | **Code quality** | Dead code, duplication, magic values, naming, complexity, stale comments |
+| 10 | **Testing** | Coverage gaps, test quality, missing test types, logging, metrics, alerting |
+| 11 | **Infrastructure** | Environment parity, secrets management, rollback, CI pipeline completeness |
+| 12 | **Enterprise practices** | Idempotency, audit trails, multi-tenancy isolation, pagination, documentation |
+
+---
+
+## Modes
+
+| Mode | Command to your AI | What happens |
+|------|--------------------|--------------|
+| `REVIEW` | `"Review this project"` | Full read-only assessment — no file changes |
+| `FIX` | `"Fix the issues you found"` | Targeted fixes for confirmed issues — minimal diffs |
+| `OPTIMIZE` | `"Optimize performance"` | Performance, bundle, query, and resource improvements |
+| `CLEAN` | `"Clean dead code"` | Remove unused code, debug logs, stale TODOs |
+| `VERIFY` | `"Verify the fixes"` | Tests and checks that confirm fixes work |
+| `FULL` | `"Full review and fix"` | All modes in sequence — report after each phase |
+
+---
+
+## Quick start
+
+**Composio** (native — full autonomous GitHub read/write)
+```
+Read .critic/CRITIC.md and .critic/agent/fullstack-critic-agent.md.
+Connect GitHub via COMPOSIO_MANAGE_CONNECTIONS.
+Run a FULL review of [repository name].
+```
+
+**Claude Code**
+```
+Read .critic/CRITIC.md. Use Glob to map the project.
+Use Grep before opening any file. Use TodoWrite for each finding.
+Do a REVIEW of this project — do not modify any files.
+```
+
+**Gemini CLI**
+```
+@.critic/CRITIC.md
+Review this project. Load layers from .critic/layers/manifest.md.
+Use grep before reading files. Summarise before switching layers.
+```
+
+**Any IDE AI (Copilot, Cursor, Qoder, Antigravity)**
+```
+Read .critic/CRITIC.md then do a full REVIEW of this project.
+Cover all 12 dimensions. Cite exact file and line for every finding.
+Do not modify any files.
+```
+
+---
+
+## Optional: give the AI context about your project
+
+Copy `PROJECT_REVIEW.md` into your project root (not `.critic/`) and fill it in.
+The AI reads it first and calibrates the review to your stack, scale target, and known risks.
+
+```bash
+cp .critic/PROJECT_REVIEW.md ./PROJECT_REVIEW.md
+# Edit the file, then run your review
+```
+
+---
+
+## File structure
+
+```
+package.json                  ← npm/pnpm package — bin: critic / fullstack-critic (zero deps)
+bin/
+  fullstack-critic.js         ← CLI entry point
+src/
+  cli.js                      ← review / watch / init / audit router
+  analyzer.js  rules.js       ← 12-dimension code analysis engine
+  deps.js                     ← package & dependency analysis (every ecosystem)
+  report.js                   ← markdown report + FIX/OPTIMIZE/DELETE/ADD action plan
+  watcher.js                  ← continuous background review
+  init.js  util.js  index.js  ← attach-to-project, fs walk, programmatic API
+CRITIC.md                     ← Core rubric — always read first
+CLAUDE.md                     ← Claude Code and claude.ai specifics
+GEMINI.md                     ← Gemini CLI specifics
+AGENTS.md                     ← Universal entry point — any AI, any IDE
+PROJECT_REVIEW.md             ← Template: copy into your project root
+agent/
+  fullstack-critic-agent.md   ← Composio agent contract
+layers/
+  manifest.md                 ← Layer selection table and dependency rules
+  transactional-domain.md     ← Domain layer: payments, orders, inventory, state machines
+memory/
+  templates/                  ← Bootstrap templates for .critic-memory/ on first run
+    PROJECT_PROFILE.md  DECISIONS.md  REVIEW_HISTORY.md  RUN_STATE.md
+prompts/
+  composio-upgrade-agent.md   ← Composio prompt that upgrades this repo itself
+docs/
+  GETTING_STARTED.md          ← Install + CLI + watch guide
+tests/
+  critic.test.js              ← zero-dependency self-tests (node --test)
+```
+
+---
+
+## Session memory
+
+On first run in a project, the AI creates `.critic-memory/` in your project root
+using the templates in `memory/templates/`. This records what the AI learned about
+your project — architecture, past decisions, review history — so future sessions
+start with context instead of re-discovering everything.
+
+Add `.critic-memory/` to your `.gitignore`, or commit it — your choice.
+**Never store credentials, API keys, tokens, or PII in memory files.**
+
+---
+
+## Composio native setup
+
+The Composio agent reads and writes your GitHub repository directly using
+Composio's GitHub toolkit — no local git operations required.
+
+```
+1. Open or create a Composio workspace
+2. Load agent/fullstack-critic-agent.md as the agent system prompt
+3. Connect GitHub via COMPOSIO_MANAGE_CONNECTIONS
+4. Pass the repository to review
+5. Run a request from the "Quick start" section above
+```
+
+See `docs/GETTING_STARTED.md` for full Composio setup instructions.
+
+---
+
+## Contributing
+
+Pull requests welcome. If you add a new domain layer (e.g. `ml-pipeline.md`,
+`mobile.md`, `embedded.md`, `data-pipeline.md`), follow the format in
+`layers/transactional-domain.md`. Every check must be universal — no assumptions
+about a specific framework, language, cloud provider, or business domain.
+
+To run the upgrade agent on this repo itself, see `prompts/composio-upgrade-agent.md`.
+
+---
+
+## License
+
+MIT — free to use, modify, and distribute.

package/agent/fullstack-critic-agent.md

@@ -0,0 +1,125 @@
+# Full-Stack Critic — Composio Agent Contract
+
+You are a senior full-stack engineering agent operating inside a Composio workspace.
+Read `CRITIC.md` fully before doing anything else. It defines every check, every mode,
+and every output format. This file only adds Composio-specific tool guidance on top.
+
+---
+
+## Attaching to a project — zero impact on running sessions
+
+The critic attaches passively. It reads; it does not write unless you explicitly run
+FIX, CLEAN, or FULL mode. No running process, CI job, or active coding session is
+affected by attaching or running a REVIEW.
+
+To connect the critic to a repository in Composio:
+1. Open or create a Composio workspace.
+2. Load this agent contract (`agent/fullstack-critic-agent.md`) as the agent system prompt.
+3. Ensure GitHub is connected via `COMPOSIO_MANAGE_CONNECTIONS`.
+4. Select or pass the repository to review.
+5. Run a request using the mode commands in `AGENTS.md`.
+
+---
+
+## Composio tool discipline
+
+**Discovery**
+```
+COMPOSIO_SEARCH_TOOLS  →  find GITHUB_* tools needed for this task
+GITHUB_GET_REPOSITORY  →  confirm access and read repo metadata
+GITHUB_LIST_REPO_CONTENTS  →  map directory structure before reading files
+```
+
+**Reading files (always fetch SHA — required for updates)**
+```
+GITHUB_GET_FILE_CONTENTS  →  read a file and capture its SHA
+```
+Never read `node_modules`, `dist`, `.next`, `build`, `.git`, `coverage`, or vendor directories.
+Use `COMPOSIO_REMOTE_WORKBENCH` with Python `grep`/`glob` to locate symbols before reading whole files.
+
+**Layer discipline**
+- Load one primary layer at a time using `layers/manifest.md`.
+- Maximum 15 files per active layer.
+- Summarise findings in the workbench before switching layers.
+- State the evidence that justifies loading a second layer.
+
+**Validation (before every write)**
+Run in `COMPOSIO_REMOTE_WORKBENCH`:
+```python
+# Check markdown validity — no unclosed fences, no broken tables
+# Check CRITIC.md contains all 12 dimension headings
+# Check no file contains domain-specific terms that make it non-universal
+# Report any failure before proceeding to write
+```
+
+**Writing files (FIX and FULL modes only)**
+```
+GITHUB_CREATE_OR_UPDATE_FILE_CONTENTS  →  write file (requires SHA from prior GET)
+```
+Every write must:
+- Use the SHA captured from `GITHUB_GET_FILE_CONTENTS` of the same file
+- Contain the minimum change that fixes the confirmed issue
+- Be followed by a verification step recorded in `.critic-memory/DECISIONS.md`
+
+**Committing**
+```
+GITHUB_CREATE_COMMIT  →  single commit per session with a descriptive message
+```
+Never use force push, branch deletion, or rebase without explicit instruction.
+
+---
+
+## Agent workflow
+
+```
+READ CRITIC.md
+READ PROJECT_REVIEW.md (if present)
+SELECT primary layer from layers/manifest.md
+IMPORT files for that layer (GITHUB_GET_FILE_CONTENTS × N)
+WORK through CRITIC.md checks for the active layer
+STAGE findings in COMPOSIO_REMOTE_WORKBENCH scratchpad
+SUMMARISE findings before layer switch
+DISCARD active file context
+REPEAT for required dependent layers
+EXPORT final report
+UPDATE .critic-memory/ files
+```
+
+---
+
+## Example requests
+
+**REVIEW**
+```
+Read .critic/CRITIC.md. Review the checkout API in this repository.
+Start with the api layer. Load only the route, schema, middleware, and focused tests.
+Load backend or database chunks only when evidence requires it.
+Summarise and discard each layer before switching.
+Do not modify any files. Return findings with exact file and line references.
+```
+
+**FIX**
+```
+Read .critic/CRITIC.md. Fix the BLOCKER and CRITICAL issues from the last review.
+Use GITHUB_GET_FILE_CONTENTS to read each file and capture its SHA before writing.
+Make the smallest change that fixes each issue. Record every fix in DECISIONS.md.
+Run verification checks in COMPOSIO_REMOTE_WORKBENCH before committing.
+```
+
+**FULL**
+```
+Read .critic/CRITIC.md. Run a FULL review and fix of this repository.
+Phase 1: REVIEW all 12 dimensions. Report with exact evidence.
+Phase 2: FIX all BLOCKERs and CRITICALs. Record diffs and verification steps.
+Phase 3: CLEAN dead code and debug logs. Minimal changes only.
+Phase 4: VERIFY by describing the exact test, lint, and type check for each fix.
+Commit all changes with a descriptive message. Update .critic-memory/ at session end.
+```
+
+---
+
+## Performance target
+
+Assess realistic capacity and identify the primary bottleneck.
+Never state that a system supports a specific throughput target without
+load-test evidence recorded in `PROJECT_REVIEW.md` or `.critic-memory/REVIEW_HISTORY.md`.

package/bin/fullstack-critic.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+const code = require('../src/cli').run(process.argv.slice(2));
+process.exitCode = Number.isFinite(code) ? code : 0;

package/docs/GETTING_STARTED.md

@@ -0,0 +1,145 @@
+# Getting Started — Full-Stack Critic
+
+Full-Stack Critic reviews **100% of a project's resources** — every source file, every
+package, and every dependency — across the 12 engineering dimensions in
+[`CRITIC.md`](./CRITIC.md), then produces a detailed report with a prioritised action plan
+grouped into **FIX · OPTIMIZE · DELETE · ADD**.
+
+It ships two ways to use it:
+
+1. **As a CLI package** (this guide) — run a one-shot `review`, or a continuous `watch`
+   that keeps giving feedback as you code, no AI assistant required.
+2. **As an AI rubric** — clone it next to your project and tell any AI assistant
+   (`Claude Code`, `Gemini CLI`, `Cursor`, `Copilot`, `Qoder`, …) to read `CRITIC.md`.
+   See the [README](../README.md) for the AI flow.
+
+---
+
+## Install
+
+The CLI is a zero-dependency Node package (Node ≥ 18).
+
+> **Not published to the public npm registry yet.** So `npx fullstack-critic` and
+> `npm i -g fullstack-critic` return **404** until this repo is published with `npm publish`.
+> Use one of the tested local methods below instead.
+
+```bash
+# A) Global install from this folder — makes `critic` available in every project:
+cd fullstack-critic
+npm install -g .          # equivalent: npm link
+
+# B) Install by absolute path from anywhere:
+npm install -g C:\path\to\fullstack-critic
+
+# C) No install — run straight from the folder:
+node bin/fullstack-critic.js review .
+
+# D) pnpm / yarn equivalents:
+pnpm add -g ./fullstack-critic
+yarn global add file:./fullstack-critic
+```
+
+> To make `npx fullstack-critic` / `npm i -g fullstack-critic` work for everyone,
+> a maintainer must run `npm publish` from this folder first (see “Publishing”).
+
+Once installed it provides the `critic` (and `fullstack-critic`) command.
+
+---
+
+## Commands
+
+```bash
+critic review [path]     # one-shot full review across all 12 dimensions
+critic watch  [path]     # attach to an in-progress workflow; continuous feedback on every change
+critic init   [path]     # attach the AI rubric: copies .critic/ + scaffolds .critic-memory/ + PROJECT_REVIEW.md
+critic audit  [path]     # run each detected package manager's native audit (npm audit, pip-audit, govulncheck, …)
+```
+
+### One-shot review
+
+```bash
+cd your-project
+critic review .                      # console summary + verdict
+critic review . --md report.md       # also write the full markdown report
+critic review . --json findings.json # machine-readable findings
+critic review . --fail-on high       # exit code 1 if any HIGH+ (use in CI)
+```
+
+### Watch mode — feedback while you code
+
+```bash
+critic watch ./src
+```
+
+Watches every file, and a few hundred ms after each edit it re-runs the analysis and
+prints only what **appeared** (`+ NEW …`) or got **fixed** (`- FIXED …`), and keeps a live
+report at `.critic-report.md`. New directories are picked up automatically; it ignores
+`node_modules`, build output, `.git`, and its own report files. Ctrl+C to stop.
+
+Run it in the background alongside your dev server so it "keeps interacting in the backend":
+
+```bash
+critic watch . --md CRITIC_REPORT.md &      # unix
+start /b critic watch .                      # windows
+```
+
+---
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--md <path>` | write the full markdown report (watch default: `.critic-report.md`) |
+| `--json <path>` | emit machine-readable findings |
+| `--fail-on <level>` | `blocker\|critical\|high\|medium\|low\|never` — exit 1 at that severity (default `critical`) |
+| `--no-code` | skip code line-scanning (dependencies + structure only) |
+| `--debounce <ms>` | watch settle time (default 400) |
+| `--quiet` | print only the summary line |
+
+---
+
+## What "100% of resources" means here
+
+Every run prints a **Coverage** block that accounts for every resource it touched:
+
+- every non-ignored source file is line-scanned (and the count is reported);
+- every skipped resource (dependency dirs, build output, binaries, oversized files, VCS)
+  is **counted with a reason** — nothing is dropped silently;
+- every dependency manifest found (npm, pip, poetry, pipenv, Go, Cargo, Composer, Bundler,
+  Maven, Gradle) is parsed for declared packages, lock files, and unpinned versions;
+- any of the 12 dimensions with no automated signal is named explicitly so you know the
+  AI/manual pass from `CRITIC.md` is still required for it.
+
+---
+
+## Suppress a false positive
+
+Add `// critic-ignore` at the end of a line, or `/* critic-ignore-file */` in the first two
+lines of a file (useful for files that *define* detection patterns).
+
+---
+
+## Publishing (to enable `npx fullstack-critic`)
+
+The package is intentionally **not** on the public registry until a maintainer publishes it.
+Once you want `npm i -g fullstack-critic` / `npx fullstack-critic` to work for everyone:
+
+npm **requires two-factor authentication to publish**. 2FA-bypass access tokens are
+being deprecated by npm, so `npm publish` fails with `E403 ... Two-factor authentication`
+unless 2FA is active on the account. Do this once:
+
+```bash
+npm login
+# enable 2FA (authenticator app) at https://www.npmjs.com/settings/~/two-factor
+npm publish --access public --otp=123456   # live 6-digit code from your app
+```
+
+After that, the registry-install commands in “Install” above become valid as written.
+Until then, use the local `npm install -g .` / `npm link` / `node bin/...` methods.
+
+Troubleshooting:
+- `E403 … Two-factor authentication … required` → 2FA not active, or the `--otp`
+  code expired; generate a fresh code and retry.
+- `E401`/`E404` right after a bad `npm config set //registry.npmjs.org/:_authToken=…`
+  → the login token was overwritten; run
+  `npm config delete //registry.npmjs.org/:_authToken` then `npm login` again.

package/layers/manifest.md

@@ -0,0 +1,68 @@
+# Semantic Layer Manifest
+
+Load only the smallest context that answers the current question.
+A layer is a temporary working set — not the whole codebase.
+Record the active layer in `.critic-memory/RUN_STATE.md` before loading.
+
+---
+
+## Layer table
+
+| Layer            | Load when reviewing                                              | What to load |
+|------------------|------------------------------------------------------------------|--------------|
+| `discovery`      | Unknown project — mapping structure and architecture             | README, package.json / go.mod / requirements.txt / Cargo.toml, main entrypoints, directory tree, deployment config |
+| `api`            | Routes, endpoints, request/response contracts, middleware        | Route files, controllers, request schemas, response serialisers, middleware chain, API tests, OpenAPI spec |
+| `backend`        | Business logic, service layer, workers, concurrency              | Service classes, handlers, queue consumers, background jobs, external API clients, focused unit tests |
+| `database`       | Queries, indexes, migrations, transactions, ORM models           | Repository layer, ORM models, raw SQL files, migration files, query tests |
+| `cache-queue`    | Caching, message queues, background job scheduling               | Cache adapters, Redis/Memcached config, producers, consumers, retry config, dead-letter setup |
+| `frontend`       | UI components, state management, rendering, browser performance  | Affected components, custom hooks, stores, API client wrappers, CSS critical path, frontend tests |
+| `api-client`     | How a frontend or service calls an API                           | Fetch/axios wrappers, SDK usage, request interceptors, error handling, retry logic on client side |
+| `auth`           | Authentication, authorisation, sessions, tokens, permissions     | Auth middleware, guards/decorators, policy files, token generation and validation, session config, auth tests |
+| `security`       | Full threat surface: injection, secrets, trust boundaries        | Validators, sanitisers, auth middleware, secret config, dependency manifests (package-lock, Pipfile.lock) |
+| `infra`          | Deployment, scaling, CI/CD, networking, observability            | Dockerfile, docker-compose, Kubernetes manifests, Terraform/Pulumi, CI config, alert rules, dashboards |
+| `testing`        | Test strategy, coverage quality, missing test types              | Unit, integration, e2e, load test files directly relevant to the current finding |
+| `performance`    | Latency, throughput, memory, profiling, bundle size              | Hot path code, benchmark scripts, query explain plans, bundle analyser output, metrics config |
+| `architecture`   | System design, module boundaries, dependency graph               | Entrypoints, module index files, DI container config, interface definitions, ADRs |
+| `transactional`  | Orders, payments, reservations, inventory, state machines        | See `layers/transactional-domain.md` for full chunk list |
+
+---
+
+## Loading algorithm
+
+```
+1. Classify the request → pick the primary layer
+2. Use glob/find/grep to locate the specific files — never guess paths
+3. Load symbols and line ranges rather than whole files where possible
+4. Record active files in .critic-memory/RUN_STATE.md
+5. Find evidence → follow it to a second layer only when required
+6. Summarise confirmed findings before switching
+7. Discard the previous layer's file context
+8. Load the next layer → repeat until task complete
+```
+
+---
+
+## Layer dependency rules
+
+Follow a dependency only when you have specific evidence from the primary layer.
+State the evidence explicitly before loading the dependent layer.
+
+| Primary layer | Evidence type | Then load |
+|---|---|---|
+| `api` | Service call found in route | → `backend` |
+| `api` | DB query or ORM call found | → `database` |
+| `api` | Auth decision point found | → `auth` |
+| `backend` | Persistence call found | → `database` |
+| `backend` | Cache read/write found | → `cache-queue` |
+| `frontend` | API contract mismatch suspected | → `api-client` → `api` |
+| `performance` | Slow query identified | → `database` |
+| `performance` | Large bundle identified | → `frontend` |
+| `security` | Injection vector in route | → `api` |
+| `security` | Secret in config or env | → `infra` |
+| `transactional` | Persistence concern | → `database` |
+| `transactional` | Queue/retry concern | → `cache-queue` |
+| `auth` | Permission enforced in route | → `api` |
+| `auth` | Session stored in DB | → `database` |
+
+Do not load `infra`, `testing`, or `architecture` unless the finding explicitly requires them.
+Do not load more than two layers concurrently without justification in the run state.

package/layers/transactional-domain.md

@@ -0,0 +1,88 @@
+# Transactional Domain Layer
+
+Load when the project involves: orders, payments, reservations, bookings, subscriptions,
+inventory management, cart/checkout, refunds, cancellations, or any state machine where
+a write failure has real-world financial or resource consequences.
+
+Universal layer — applies to e-commerce, SaaS billing, ticketing, booking, marketplaces,
+financial tools, and any system where committed resources cannot simply be discarded.
+
+---
+
+## Chunks to load
+
+Load only the chunks relevant to the current finding, not all at once.
+
+| Chunk | What to include |
+|-------|-----------------|
+| Order / reservation service | Creation, confirmation, hold, expiry handlers |
+| Payment client | Authorisation, capture, webhook handler, reconciliation job |
+| Refund / cancellation flow | Cancel handler, refund trigger, partial refund logic |
+| Inventory / capacity service | Availability query, decrement, lock, release, overbooking guard |
+| State machine | Status definitions, transition guards, terminal states |
+| Background jobs | Hold expiry, refund retry, reconciliation, notification dispatch |
+| Focused tests | Tests for the above only — no unrelated files |
+
+---
+
+## Checks
+
+### Idempotency
+- Is order/reservation creation idempotent on retry? What is the idempotency key?
+- If the payment provider webhook fires twice, is the order confirmed once or twice?
+- Is the cancel/refund endpoint safe to call more than once without double-refunding?
+- Are background jobs safe to run concurrently on two worker processes?
+
+### Atomicity and race conditions
+- Is inventory decrement and order creation in a single DB transaction?
+- Can two concurrent requests claim the last unit of stock?
+- Is there a DB-level lock (`SELECT FOR UPDATE`, unique constraint, optimistic version) — not just application-level logic?
+- If a hold is created but payment fails, is the hold guaranteed to release regardless of how payment fails?
+
+### Payment flow
+- Is authorisation separated from capture? At what point does capture fire?
+- If capture fails after inventory is committed, what is the exact recovery path?
+- Are payment provider webhooks verified by HMAC/signature before any state change?
+- Is the refund amount recomputed server-side, or trusted from the incoming webhook or client request?
+- Are partial captures handled correctly (group orders, multi-item baskets)?
+
+### State machine integrity
+- List every possible status value. Are all terminal states explicitly defined?
+- Are invalid transitions guarded? Can a `cancelled` order be `confirmed`?
+- Is every transition logged with timestamp, actor identity, and reason?
+- If a state write fails mid-transition, is there a compensating transaction or a recovery job?
+
+### Inventory and capacity
+- Does availability check query the DB on every request, or is it cached?
+- If cached: what is the TTL, what invalidates it, can a cache stampede oversell inventory?
+- Is the overbooking guard at the DB level (constraint) or only application level?
+- What happens to in-flight transactions during a DB failover or primary/replica lag?
+
+### Cancellation and refunds
+- Are cancellation fee rules (time windows, penalties) enforced server-side only?
+- Is the refund triggered synchronously, or queued? What happens if the queue is down?
+- Is there a reconciliation job that detects queued refunds that never executed?
+- Is there a time-lock preventing cancellation after a point of no return (e.g. after dispatch)?
+
+### Notifications and side effects
+- Are emails, webhooks, and push notifications sent after the DB transaction commits — never before?
+- If a notification send fails, does it roll back the transaction, or is it retried independently?
+- Can duplicate notifications be sent on retry (duplicate email on order confirm)?
+
+---
+
+## Extra report sections when this layer is active
+
+Append these sections after the standard Findings block:
+
+### Transactional Integrity Review
+Atomicity, idempotency, and race condition findings with exact file:line references.
+
+### Payment Flow Review
+Authorisation, capture, webhook verification, and refund logic findings.
+
+### Inventory and Capacity Review
+Availability query strategy, cache risk, overbooking exposure, estimated failure rate at peak load.
+
+### State Machine Review
+State graph completeness, invalid transition risks, audit trail sufficiency.

package/memory/templates/DECISIONS.md

@@ -0,0 +1,20 @@
+# Decisions
+
+<!-- One entry per confirmed and applied fix. Written by the AI in FIX or FULL mode. -->
+<!-- Never store credentials, tokens, API keys, PII, passwords, or raw log data here. -->
+
+## Entry format
+
+```
+### YYYY-MM-DD — Short title
+
+- **Decision:** What was changed and why.
+- **Location:** path/to/file:line
+- **Rationale:** Why this approach over alternatives.
+- **Trade-offs:** What was accepted, deferred, or out of scope.
+- **Verified by:** test name, lint output, type check, or manual step description.
+```
+
+---
+
+<!-- AI writes entries below this line -->