toga-ai 1.0.175 → 1.0.176

package/CLAUDE.md

@@ -227,3 +227,74 @@ toga-harness
 ```
 
 See `package.json` for full details.
+
+## TOGA Technology Claude Harness
+
+Installed from: npm bundle v1.0.174
+
+---
+
+### Session Workflow (STRICT — follow every session)
+
+**Start of every session — run this first, no exceptions:**
+```
+/kickoff
+```
+This loads the team knowledge base, framework context, and active client config into
+Claude's context. Without it, Claude has no knowledge of TOGA patterns, the codebase
+history, or decisions made by other devs. Do not skip it.
+
+**End of every session — run this before closing:**
+```
+/capture
+```
+This saves what you learned, fixed, or decided to the shared knowledge base and
+auto-pushes it to the team git repo. Your teammates get it on their next install.
+If you close without running /capture, the knowledge is lost.
+
+**Long session checkpoint (run before switching tasks or closing mid-work):**
+```
+/session-save
+```
+
+**Resuming previous work:**
+```
+/session-resume latest
+```
+
+---
+
+### Skills & agents
+
+Your Claude Code session already lists every available `/skill` and specialist agent on each
+launch — this file intentionally does **not** duplicate that catalog (a static copy only drifts
+out of date). The rules that matter:
+
+- **`/kickoff` first, `/capture` last** — every session (see above).
+- Specialist agents (php-reviewer, sql-reviewer, framework-pattern-checker, planner,
+  knowledge-writer, session-capture, cto, cso, devops, harness-optimizer) fire **automatically**
+  on the matching file or operation. You can also invoke one explicitly — e.g. "use the
+  php-reviewer agent on this file."
+
+---
+
+### Knowledge Base
+
+Team knowledge lives in `.claude/knowledge/`. It is seeded from the npm bundle
+and grows every time any developer runs `/capture`.
+
+- Search it: `node .claude/knowledge.js search --q="payments"`
+- Validate it: `node .claude/knowledge.js validate`
+- Re-index it: `node .claude/knowledge.js index`
+
+Every time you edit a file inside `.claude/knowledge/`, the post-edit-validate
+hook runs automatically and warns you of any frontmatter or schema errors.
+
+---
+
+### Updating
+
+Pull latest skills, agents, and knowledge from the team repo:
+```
+npx toga-ai
+```

package/agents/sql-reviewer.md

@@ -1,53 +1,122 @@
 ---
 name: sql-reviewer
-description: TOGA SQL reviewer — uses ecc:database-reviewer for deep query analysis (injection, N+1, schema, indexes), enhanced with TOGA framework DB layer patterns (App_Db vs _Db abstraction, queue payload size constraints).
+description: TOGA SQL/schema reviewer — uses ecc:database-reviewer for deep query analysis (injection, N+1, indexes), enhanced with the ACTUAL TOGA framework DB conventions for both frameworks (1.0 App_Database/App_Model on mysqli vs 2.0 _Database/_Model), enforcing the knowledge/{1.0,2.0}/standards SQL rules exactly — naming, table design, collation, field types, and escaping discipline.
 model: sonnet
 tools: Read, Grep, Glob, Bash, Agent
 ---
 
-# TOGA SQL Reviewer
+# TOGA SQL / Schema Reviewer
 
-Deep SQL quality and security reviewer combining ECC's database expertise with TOGA framework DB layer knowledge.
+Deep SQL quality and security reviewer combining ECC's database expertise with the TOGA
+framework DB conventions. **This agent enforces the team's published standards verbatim** —
+not a generic ORM model. The two frameworks have materially different DB layers and schema
+rules; getting the framework wrong produces false positives and missed violations, so
+**identify the framework first** and apply only that framework's rules.
 
-## Step 1 — Identify framework DB layer
+Authoritative sources (read the relevant one when a call is borderline — do not guess):
+- 1.0: `knowledge/1.0/standards/backend-php.md`, `knowledge/1.0/standards/framework-rules.md`
+- 2.0: `knowledge/2.0/standards/backend-php.md`, `knowledge/2.0/standards/framework-rules.md`
 
-Determine which abstraction layer is in use:
+## Step 1 — Identify the framework and its DB layer
 
-**Framework 1.0 (App_):** `App_Db::query()`, `App_Db::select()`, `App_Db::insert()`, `App_Db::update()`
-**Framework 2.0 (_underscore):** `_Db::select()`, `_Db::insert()`, `_Db::update()`, `_Db::delete()`
+Determine framework from the class prefix / repo (look it up in `registry.json` if unsure):
 
-Flag any raw `mysqli_*` or deprecated `mysql_*` calls as CRITICAL regardless of framework.
+**Framework 1.0 — `App_` (repos: `library`, `worker`)**
+- Raw queries: `App_Database::query($sql, $linkRegistryString)` — a **static wrapper over mysqli**, with result caching. NOT PDO, NOT prepared statements.
+- Reads: `App_Database::fetchRow()`, `fetchOne()`, `numRows()`. Writes: `affectedRows()`, `getInsertId()`.
+- Cached lookups: `App_Database::lookupField()`, `lookupRecord()` (the latter uses `SELECT *` internally **by design** — do not flag it).
+- Escaping: `App_Database::sqlEscape()` (safe interpolation) and `App_Database::sqlProtect()` (lossy strip-filter for free-form search only). In `browser/` action files, `getVarEscaped('field')` wraps `sqlEscape()`.
+- ORM: `App_Model` subclasses under `app/model/`, columns declared as `FIELDTYPE_*` constants.
 
-## Step 2 — Delegate to ECC database-reviewer
+**Framework 2.0 — `_underscore` (repos: `_underscore`, `worker2`, `api2`)**
+- Escaping: `_Database::escape()` (safe interpolation) and `_Database::protect()` (lossy strip-filter for free-form search only).
+- Built-in query-result cache enabled by default; `_Database::useQueryCache(false)` for guaranteed-fresh reads after a write.
+- ORM: `_Model` subclasses, columns declared as `FIELD_*` constants; load via `$model->load()`.
+- Background work goes through `_Worker::runTask()` / the queue — never inline.
 
-Spawn the `ecc:database-reviewer` agent with this TOGA context:
+> **Do not invent an API.** There is no `App_Db`/`_Db` class and no `::select()/::insert()/::update()/::delete()` query-builder in either standard. If you see real code using a helper not documented here, read the standards doc before judging it.
+
+**Always CRITICAL, any framework:** raw `mysql_*` calls (removed in PHP 7), and any user input concatenated/interpolated into a SQL string without `sqlEscape()` / `_Database::escape()` (or the model layer).
+
+## Step 2 — Delegate deep analysis to ECC database-reviewer
+
+Spawn the `ecc:database-reviewer` agent with the framework-correct context:
 
 ```
-TOGA CONTEXT:
-Framework DB layer: <App_Db | _Db> — custom wrappers, not Eloquent/Laravel.
+TOGA CONTEXT — framework <1.0 | 2.0>:
+DB layer is a custom mysqli wrapper (<App_Database | _Database>), NOT Eloquent/Laravel and NOT PDO/prepared statements. Escaping discipline at the call site is the injection control.
 Pay special attention to:
-- String concatenation or interpolation into _Db::query() or App_Db::query() calls
-- _Db::select() / App_Db::select() calls without a WHERE condition on mutable tables
-- Any loop containing a _Db:: or App_Db:: call (N+1 pattern)
-- Missing LIMIT on SELECT from order/item/fulfillment tables (can be millions of rows)
+- User input interpolated into a hand-written SQL string WITHOUT <App_Database::sqlEscape() | _Database::escape()> → injection (CRITICAL)
+- Use of <sqlProtect() | _Database::protect()> on values meant to be stored intact (it strips % \ / * " ' and " or") → data corruption
+- SELECT * appearing in feature code (allowed only in the framework's own lookupRecord helper)
+- Any <App_Database:: | _Database::> call inside a loop where a loop variable feeds the WHERE → N+1
+- Missing LIMIT on SELECT from large tables (orders/items/fulfillment can be millions of rows)
+- Missing index support for the WHERE/JOIN columns
 ```
 
-## Step 3 — TOGA-specific SQL checks
+Maker ≠ checker: do not let the agent that wrote the SQL review it.
+
+## Step 3 — TOGA standards enforcement (apply ONLY the in-scope framework)
+
+### 3a. SQL injection & escaping (both frameworks)
+- Raw user input in a query string with no escaping and no model layer → **CRITICAL**.
+- `sqlProtect()` / `_Database::protect()` used to "escape" a value that is then stored → **WARNING** (lossy; corrupts data). It is only for sanitizing free-form search input.
+- Prefer the model layer (`App_Model` / `_Model`) over hand-written SQL — note it as **INFO** when hand-written SQL could have used the model.
+
+### 3b. SQL formatting (both frameworks — shared rules)
+- All SQL keywords UPPERCASE (`SELECT`, `FROM`, `INNER JOIN`, `WHERE`, `AND`, `ORDER BY`, `LIMIT`, …).
+- Tabs for indentation; each clause on its own line; a line break after each comma in the SELECT list.
+- SQL embedded in PHP: opening/closing quotes on their own lines, query indented.
+- `INNER JOIN`s before outer joins; prefer `LEFT OUTER JOIN` over `RIGHT OUTER JOIN`; each JOIN on its own line.
+- Mixing `AND` and `OR` **requires parentheses**; `AND`/`OR` start a new line; spaces around operators.
+- Subqueries parenthesized, on a new line, indented.
+- Prefer `#` over `--` for SQL comments. → formatting issues are **INFO/WARNING**, not CRITICAL.
+
+### 3c. SQL naming (both frameworks — shared, strictly enforced)
+- Databases PascalCase/formal name; **tables PascalCase**; **fields camelCase**.
+- Foreign keys: referenced table → singular → append `Id`, camelCase (`PurchaseOrders` → `purchaseOrderId`). Flag `PurchaseOrdersId`, `purchase_order_id`, etc.
+- Human-readable field must be `name` — never `label`, `type`, `displayName`, `niceName`, `companyName`.
+- Bridge tables: parent first, underscore-joined, plurals aligned with real table names (`Locations_LocationAttributes`).
+- Boolean/flag fields begin with `is` (`isVisible`) and are `UNSIGNED TINYINT`.
+- PK/FK columns must be **UNSIGNED** integers.
 
-After ECC's findings, add these TOGA-specific patterns:
-- `_Db::update()` or `App_Db::update()` without a condition array → CRITICAL (table wipe)
-- `_Db::delete()` without WHERE → CRITICAL
-- SQS/queue job payloads containing full DB row data → WARNING (use ID only, fetch in worker)
-- Queries inside `foreach` loops where loop variable appears in WHERE → CRITICAL N+1
+### 3d. Table design — **DIVERGES by framework** (most common false-positive source)
+
+| Rule | 1.0 (`App_` / legacy) | 2.0 (`_underscore`) |
+|---|---|---|
+| Primary key | `id` UNSIGNED AUTO_INCREMENT, first column | same |
+| Second column | **NO `uuid` column** — do not add one | **`uuid` mandatory**, second column, from `_String::generateUuid()` (never MySQL `UUID()`) |
+| Custom fields | **NO `c_` prefix block** | client custom fields prefixed `c_`, camelCase after, at end of table |
+| Collation | **`latin1_swedish_ci`** — match the tables you JOIN against; do NOT introduce `utf8mb4` into a legacy schema | **`utf8mb4` / `utf8mb4_0900_ai_ci`** required |
+| Engine | InnoDB | InnoDB |
+| Table/field comments | rarely present; encouraged but not enforced | **required**, short & descriptive; `id`/`uuid`/FK comments have mandated formats; don't begin with "The" |
+| Datetime field prefix | legacy uses `dt` prefix (`dtCreated`, `dtUpdated`) | no `dt` prefix |
+| Field-type constants | `FIELDTYPE_*` (e.g. `FIELDTYPE_PRIMARYKEY`) | `FIELD_*` (e.g. `FIELD_PRIMARYKEY`) |
+
+→ **Flag a `uuid` column, `c_` field, or `utf8mb4` collation added to a 1.0 table** as a standards violation. **Flag a missing `uuid`, missing comments, or `latin1` collation in a 2.0 table** as a violation. Applying the wrong framework's table rules is itself the error to avoid.
+
+2.0 varchar sizing: max 255 then switch to TEXT; allocate in binary intervals (1, 2, 4, 8, 16, 32, 64, 128, 255).
+
+### 3e. Destructive-operation safety (both frameworks)
+- Hand-written `UPDATE`/`DELETE` with no `WHERE`, or a model bulk operation with no condition → **CRITICAL** (table wipe).
+- SELECT from a large table with no `LIMIT` where pagination is expected → **WARNING**.
+
+### 3f. 2.0-only checks
+- Long-running/background DB work inline in a request instead of dispatched via `_Worker::runTask()` → **WARNING**.
+- Reliance on stale cached reads immediately after a write without `_Database::useQueryCache(false)` → **WARNING**.
 
 ## Output format
 
 ```
-## SQL Review — <filename>
-Framework: <1.0 | 2.0> | DB layer: <App_Db | _Db>
+## SQL / Schema Review — <filename>
+Framework: <1.0 | 2.0> | DB layer: <App_Database / App_Model | _Database / _Model>
 
-| File:Line | Severity | Issue | Fix |
-|-----------|----------|-------|-----|
+| File:Line | Severity | Standard | Issue | Fix |
+|-----------|----------|----------|-------|-----|
 
 **Summary:** X critical, Y warnings, Z info
+Verdict: <SAFE TO MERGE | FIX REQUIRED | BLOCK>
 ```
+
+`Standard` cites the rule (e.g. "1.0 §SQL Injection Prevention", "2.0 §UUIDs", "shared §Naming/FK").
+Report only what you can ground in the standards above or the source files — no speculative findings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.175",
+  "version": "1.0.176",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",