toga-ai 1.0.0

package/rules/README.md

@@ -0,0 +1,53 @@
+# Rules Directory
+
+Rules are **always-follow guidelines** that are loaded automatically into every Claude Code session. Unlike skills (which are on-demand slash commands), rules are passive context — Claude reads them and applies them without being asked.
+
+## What belongs here
+
+Rules files contain direct imperatives: coding style, security requirements, git workflow, framework conventions. They do not contain architecture documentation (that goes in `knowledge/`) or how-to instructions (that goes in `skills/`).
+
+## Directory structure
+
+```
+rules/
+├── README.md                    ← this file
+├── common/                      ← apply to all repos and both frameworks
+│   ├── coding-style.md          ← language-agnostic style rules
+│   ├── git-workflow.md          ← branching, commit messages, PR rules
+│   ├── security.md              ← security rules (critical — always followed)
+│   └── testing.md               ← test requirements
+└── php/                         ← PHP-specific rules
+    ├── app-framework.md         ← 1.0 App_ framework rules
+    └── underscore-framework.md  ← 2.0 _underscore framework rules
+```
+
+## How to install
+
+Run from the team knowledge repo root:
+
+```sh
+node scripts/install.js
+```
+
+This copies all files from `rules/` into `.claude/rules/toga/` in the target project. Claude Code automatically loads rules from `.claude/rules/`.
+
+If you want to install into a specific project:
+
+```sh
+node scripts/install.js /path/to/project
+```
+
+## How to add new rules
+
+1. Create a new `.md` file in the appropriate subdirectory (`common/` or `php/`).
+2. Write direct imperatives — "Never do X", "Always do Y". No meta-commentary.
+3. Keep each file under 200 lines.
+4. Run `node scripts/install.js` to push the new rule to all installed projects.
+5. Commit the new rule file to this repo so it's available to the whole team.
+
+## Why rules instead of CLAUDE.md
+
+`CLAUDE.md` is project-specific context. Rules in `.claude/rules/` are team-wide always-on standards. Keeping them separate means:
+- Updating a rule updates it for the whole team on next install.
+- Project `CLAUDE.md` stays focused on project-specific context.
+- Rules can be audited separately from project docs.

package/rules/common/coding-style.md

@@ -0,0 +1,123 @@
+# Coding Style Rules
+
+These rules apply to all code in all TOGA Technology repos, regardless of language or framework.
+
+## Error handling
+
+Never use bare `catch` blocks. Never catch and silently ignore an exception.
+
+```php
+// WRONG
+try {
+    $result = $db->query($sql);
+} catch (Exception $e) {
+    // nothing here
+}
+
+// WRONG
+} catch (Exception $e) {}
+
+// CORRECT
+} catch (PDOException $e) {
+    error_log('DB query failed: ' . $e->getMessage());
+    throw $e; // or handle specifically
+}
+```
+
+Always catch the most specific exception type available. Catching `Exception` as a last resort is acceptable only if you log it and re-throw or return an error response.
+
+Never use `@` error suppression. Fix the underlying issue instead.
+
+## Dangerous functions
+
+Never use `eval()` on user input or on any string that contains user-controlled data.
+
+Never use `exec()`, `shell_exec()`, `system()`, `passthru()`, or `popen()` with user input. If shell execution is required, use an allowlist of commands and escape arguments with `escapeshellarg()`.
+
+## Function parameters
+
+Functions with 4 or more parameters must use an associative array argument or a named-parameters pattern. Do not define functions with 4+ positional parameters.
+
+```php
+// WRONG
+function createOrder($userId, $items, $addressId, $couponCode, $notes) { ... }
+
+// CORRECT
+function createOrder(array $params): Order {
+    // $params['user_id'], $params['items'], $params['address_id'], etc.
+}
+```
+
+## Return early
+
+Use guard clauses and return early. Do not nest the happy path inside conditionals.
+
+```php
+// WRONG
+function getUser(int $id): ?User {
+    if ($id > 0) {
+        $user = $this->db->find($id);
+        if ($user) {
+            return $user;
+        }
+    }
+    return null;
+}
+
+// CORRECT
+function getUser(int $id): ?User {
+    if ($id <= 0) return null;
+    return $this->db->find($id);
+}
+```
+
+## Dead code
+
+Never commit commented-out code. Delete it. If you need to preserve a previous approach, that is what git history is for.
+
+```php
+// WRONG
+// $result = $this->oldMethod($id);
+$result = $this->newMethod($id);
+```
+
+## Magic numbers
+
+Never use unexplained numeric or string literals. Define named constants.
+
+```php
+// WRONG
+if ($attempts > 3) { ... }
+sleep(86400);
+
+// CORRECT
+const MAX_LOGIN_ATTEMPTS = 3;
+const SECONDS_PER_DAY = 86400;
+
+if ($attempts > self::MAX_LOGIN_ATTEMPTS) { ... }
+sleep(self::SECONDS_PER_DAY);
+```
+
+## Single responsibility
+
+Each function does one thing. If a function's name requires "and" to describe it, split it.
+
+Functions longer than 40 lines are a signal to review for decomposition — not a hard rule, but a strong prompt to consider whether the function has grown beyond one responsibility.
+
+## Type declarations
+
+All public and protected methods must have return type declarations. Parameter types must be declared for all non-variadic parameters. Use PHP 7.4+ typed properties for class attributes.
+
+```php
+// WRONG
+public function process($data) {
+    ...
+}
+
+// CORRECT
+public function process(array $data): bool {
+    ...
+}
+```
+
+Use `?Type` for nullable. Use `void` for no return value. Do not omit the return type.

package/rules/common/git-workflow.md

@@ -0,0 +1,72 @@
+# Git Workflow Rules
+
+## Branch protection
+
+Never commit directly to `_main`. All changes go through feature branches and pull requests.
+
+Never force-push to `_main` under any circumstances.
+
+## Branch naming
+
+Use one of these prefixes followed by a short hyphenated description:
+
+- `feature/short-description` — new functionality
+- `fix/short-description` — bug fix
+- `hotfix/short-description` — urgent production fix
+- `refactor/short-description` — code restructuring with no behavior change
+- `docs/short-description` — documentation only
+
+Examples: `feature/batch-order-processing`, `fix/null-customer-email`, `hotfix/sqs-timeout`
+
+Keep the description short (3–5 words). Use hyphens, not underscores.
+
+## Commit messages
+
+Format: `type: short description`
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
+
+- `feat: add batch order processing worker`
+- `fix: null check on customer email before dispatch`
+- `refactor: extract order validation to dedicated class`
+- `docs: document recursive item fulfillment feature`
+- `test: add regression test for empty batch edge case`
+- `chore: update composer dependencies`
+
+The description is lowercase, present tense, under 72 characters. No period at the end.
+
+If a commit is substantial, add a blank line after the subject and a body paragraph explaining the why.
+
+## What never goes in commits
+
+Never commit secrets, API keys, passwords, database credentials, or access tokens — not even to a non-production branch. If a secret is accidentally committed, treat it as compromised and rotate it immediately.
+
+Never commit `.env` files. They are in `.gitignore` for a reason.
+
+Never commit absolute local paths (e.g. `C:\WWW\2.0\worker2`). These are machine-specific and tracked only in developer Claude memory.
+
+## Knowledge base changes
+
+Always run `node knowledge.js validate` before committing any changes to `knowledge/`. The pre-commit hook does this automatically in this repo. Do not bypass it with `--no-verify`.
+
+If validation fails, fix the errors before committing. Do not commit a broken knowledge base.
+
+## Pull requests
+
+PR title format: `[repo] brief description` — e.g. `[worker2] Add batch order processing`
+
+PR description must include:
+- Which repos or features are affected
+- How to test the change
+- Any migration steps (DB schema changes, config changes, queue registration)
+
+Link to the relevant knowledge doc if one exists or was created as part of the PR.
+
+## Pre-commit checklist
+
+Before creating a PR:
+- [ ] `node knowledge.js validate` passes (if knowledge/ was touched)
+- [ ] `php -l <changed files>` passes (no syntax errors)
+- [ ] No commented-out code
+- [ ] No hardcoded credentials or local paths
+- [ ] Branch name follows naming convention

package/rules/common/security.md

@@ -0,0 +1,118 @@
+# Security Rules
+
+These rules are critical. Violations create exploitable vulnerabilities. Follow them without exception.
+
+## SQL injection prevention
+
+Never build SQL strings by concatenating or interpolating user input.
+
+```php
+// CRITICAL VIOLATION — never do this
+$sql = "SELECT * FROM users WHERE id = " . $_GET['id'];
+$sql = "SELECT * FROM orders WHERE email = '$email'";
+
+// CORRECT — always use prepared statements
+$stmt = $pdo->prepare('SELECT * FROM users WHERE id = ?');
+$stmt->execute([$_GET['id']]);
+
+// CORRECT — framework parameterized query
+_Db::select('orders', ['email' => $email]);
+```
+
+This applies to every SQL operation: SELECT, INSERT, UPDATE, DELETE, and DDL. No exceptions for "internal" data or "trusted" sources — use parameterized queries everywhere.
+
+Integer casting (`(int) $_GET['id']`) reduces risk but is not a substitute for prepared statements. Use both.
+
+## XSS prevention
+
+Never output user-supplied data to HTML without escaping.
+
+```php
+// CRITICAL VIOLATION
+echo $_GET['name'];
+echo $user->bio; // if bio came from user input
+
+// CORRECT
+echo htmlspecialchars($_GET['name'], ENT_QUOTES, 'UTF-8');
+echo htmlspecialchars($user->bio, ENT_QUOTES, 'UTF-8');
+```
+
+`htmlspecialchars()` with `ENT_QUOTES` and `'UTF-8'` is the minimum. Use the framework's output escaping helper if one exists.
+
+JSON output is safe from XSS but must use `json_encode()` — never manually build JSON strings.
+
+JavaScript context requires additional escaping beyond `htmlspecialchars()`. Use `json_encode()` to pass server data to JS.
+
+## Password handling
+
+Never store passwords in plaintext.
+
+Never use MD5, SHA1, SHA256, or any fast hash for passwords. These are broken for password storage.
+
+Always use `password_hash($password, PASSWORD_BCRYPT)` or `PASSWORD_ARGON2ID` to hash passwords.
+
+Always use `password_verify($input, $hash)` to check passwords. Never compare hashes with `==` or `===`.
+
+## Sensitive data in logs
+
+Never log passwords, session tokens, credit card numbers, bank account numbers, social security numbers, or any PII.
+
+```php
+// VIOLATION
+error_log('Login attempt: user=' . $email . ' password=' . $password);
+
+// CORRECT
+error_log('Login attempt: user=' . $email);
+```
+
+Before adding any log statement, review what is being logged. When in doubt, log identifiers (user ID, order ID) not values.
+
+## Input validation
+
+Never trust `$_GET`, `$_POST`, `$_COOKIE`, or `$_REQUEST` directly. Always validate at the boundary.
+
+Validation means:
+1. **Type check**: Is this an integer, string, email, etc.?
+2. **Range/length check**: Is an integer within allowed range? Is a string within max length?
+3. **Format check**: Does a date match the expected format? Does an email pass `filter_var()`?
+4. **Allowlist check**: For values that must be one of a set, check against the set.
+
+```php
+// VIOLATION — no validation
+$page = $_GET['page'];
+
+// CORRECT
+$page = filter_input(INPUT_GET, 'page', FILTER_VALIDATE_INT, [
+    'options' => ['min_range' => 1, 'max_range' => 1000],
+    'flags' => FILTER_NULL_ON_FAILURE,
+]) ?? 1;
+```
+
+## File operations
+
+Never use user input directly in file paths.
+
+```php
+// CRITICAL VIOLATION
+include($_GET['page'] . '.php');
+file_get_contents('/var/uploads/' . $_GET['filename']);
+
+// CORRECT — allowlist approach
+$allowed = ['home', 'about', 'contact'];
+$page = in_array($_GET['page'], $allowed) ? $_GET['page'] : 'home';
+include($page . '.php');
+```
+
+## Session security
+
+Never put sensitive data in URLs (query strings are logged by web servers).
+
+Regenerate session IDs after login: `session_regenerate_id(true)`.
+
+Session cookies must be `HttpOnly` and `Secure` in production.
+
+## Cryptography
+
+Never implement your own encryption. Use PHP's `sodium_*` functions or a vetted library.
+
+Never use `rand()` or `mt_rand()` for security-sensitive random values. Use `random_bytes()` or `random_int()`.

package/rules/common/testing.md

@@ -0,0 +1,74 @@
+# Testing Rules
+
+## Coverage requirements
+
+Bug fixes require a regression test written before the fix is applied. The test must fail on the original code and pass after the fix.
+
+New features require tests. A feature is not complete until its tests pass.
+
+## Test naming
+
+Test names must describe the expected behavior, not just label the subject.
+
+```
+// WRONG
+test_get_user()
+test_order_2()
+test_process()
+
+// CORRECT
+test_returns_null_when_user_id_is_zero()
+test_returns_404_when_order_not_found()
+test_throws_when_required_param_missing()
+```
+
+Use snake_case for test names. Start with `test_`. The name should read as a sentence describing what the system does under specific conditions.
+
+## What to test
+
+Always test:
+- The happy path (valid input, expected output)
+- Empty input (empty string, empty array, zero)
+- Null input where null is a possible value
+- Boundary values (max int, max string length, empty collections)
+- Invalid types where the function accepts loose input
+
+For functions that interact with external systems (database, queue, HTTP):
+- Test with the external call mocked or stubbed
+- Test the error path: what happens when the external call fails?
+
+## Do not delete failing tests
+
+If a test is failing, fix the root cause. Do not:
+- Delete the test
+- Comment out the assertion
+- Change the test to match broken behavior
+- Add a special case in production code to make the test pass without fixing the real bug
+
+A failing test is information. Deleting it destroys information.
+
+## Test isolation
+
+Each test must be independent. Tests must not depend on execution order. Tests must not share mutable state.
+
+Reset any state modified by a test in a teardown method or by using transactions that are rolled back.
+
+## Framework-specific notes
+
+For PHP unit tests (PHPUnit):
+- Test class names end in `Test`: `OrderProcessorTest`
+- Test classes extend `PHPUnit\Framework\TestCase`
+- Use `setUp()` for per-test initialization, not class-level static state
+- Use data providers for parameterized tests over copy-paste test methods
+
+For integration tests that touch the database:
+- Wrap each test in a transaction and roll back in `tearDown()`
+- Never use the production database for tests
+
+## Regression tests
+
+When fixing a bug, the regression test:
+1. Reproduces the exact scenario that caused the bug
+2. Is named to describe the bug: `test_does_not_crash_when_customer_is_null`
+3. Is placed in the same test file as the class under test
+4. Must be committed in the same PR as the fix

package/rules/php/app-framework.md

@@ -0,0 +1,104 @@
+# Framework 1.0 (App_) Rules
+
+These rules apply to all repos under `C:\WWW\1.0`: `library` (core) and `worker` (app).
+
+## Class naming
+
+All classes must use the `App_` prefix. The prefix encodes the class type and path:
+
+- Controllers: `App_Controller_<Name>` — e.g. `App_Controller_Orders`, `App_Controller_Dashboard`
+- Models: `App_Model_<Name>` — e.g. `App_Model_User`, `App_Model_Order`
+- Helpers/utilities: `App_Helper_<Name>` — e.g. `App_Helper_Date`, `App_Helper_Currency`
+- Libraries/services: `App_Library_<Name>` or `App_Service_<Name>`
+
+Never create a class in a 1.0 repo without the `App_` prefix. No exceptions for "small utility classes" or anonymous helpers.
+
+## Inheritance
+
+Controllers must extend `App_Controller` (directly or through an intermediate base class that itself extends `App_Controller`).
+
+```php
+// CORRECT
+class App_Controller_Orders extends App_Controller { ... }
+class App_Controller_Api_Orders extends App_Controller_Api { ... } // where App_Controller_Api extends App_Controller
+```
+
+Models must extend `App_Model`.
+
+```php
+// CORRECT
+class App_Model_Order extends App_Model { ... }
+```
+
+Never extend a raw PHP base class (like `stdClass` or nothing) for controllers or models in 1.0 repos.
+
+## Model instantiation
+
+Never instantiate models directly in controllers using `new`.
+
+```php
+// VIOLATION
+$model = new App_Model_User();
+
+// CORRECT — use the registry or factory
+$model = App_Registry::get('User');
+// or the framework's designated factory method
+$model = $this->getModel('User');
+```
+
+The registry ensures models are singletons within a request and allows the framework to manage dependencies. Direct instantiation bypasses this and causes subtle bugs with shared state.
+
+## Method naming
+
+Public methods use `camelCase`.
+
+```php
+// CORRECT
+public function getOrdersByUser(int $userId): array { ... }
+public function processPayment(array $params): bool { ... }
+
+// VIOLATION — snake_case
+public function get_orders_by_user($userId) { ... }
+```
+
+Private and protected methods also use `camelCase`. No `snake_case` anywhere in 1.0 class method names.
+
+## File naming and location
+
+Class file names match the class name segment after the last underscore, placed in the directory corresponding to the type:
+
+- `App_Controller_Orders` → `controllers/Orders.php`
+- `App_Model_User` → `models/User.php`
+- `App_Helper_Date` → `helpers/Date.php`
+
+Before adding a new class, check `knowledge/1.0/apps/<repo>/architecture.md` to confirm the correct directory structure for that repo.
+
+## Adding new classes
+
+Before creating a new class in a 1.0 repo:
+
+1. Read `knowledge/1.0/apps/<repo>/architecture.md` — confirm the pattern used in that repo.
+2. Check if a similar class already exists — do not duplicate functionality.
+3. Follow the naming convention exactly, including the type segment.
+4. If you are adding a class to the `library` core repo, be aware it affects all 1.0 apps — review `knowledge/1.0/apps/library/architecture.md` first.
+
+## Error handling in controllers
+
+Controllers must not let exceptions bubble up to the framework unhandled. Catch specific exceptions, log them, and return an appropriate response.
+
+```php
+// CORRECT
+public function processOrder(): void {
+    try {
+        $result = $this->getModel('Order')->process($this->request->post);
+    } catch (App_Exception_Validation $e) {
+        $this->response->error($e->getMessage(), 400);
+        return;
+    } catch (App_Exception_Database $e) {
+        error_log('Order processing DB error: ' . $e->getMessage());
+        $this->response->error('Internal error', 500);
+        return;
+    }
+    $this->response->success($result);
+}
+```

package/rules/php/underscore-framework.md

@@ -0,0 +1,111 @@
+# Framework 2.0 (_underscore) Rules
+
+These rules apply to all repos under `C:\WWW\2.0`: `_underscore` (core), `worker2` (app), and `api2` (app).
+
+## Class naming
+
+All framework classes use a leading underscore prefix:
+
+- Controllers: `_Controller` base, subclasses `_Controller_<Name>`
+- Models: `_Model` base, subclasses `_Model_<Name>`
+- Workers: `_Worker` base, subclasses `_Worker_<Name>`
+- API handlers: `_Api` base or `_Api_<Name>`
+
+Application code in `worker2` and `api2` follows the same leading-underscore convention for framework-extending classes.
+
+## Worker contract
+
+Every worker class must extend `_Worker` and implement the `run()` method.
+
+```php
+// CORRECT
+class _Worker_BatchOrders extends _Worker {
+    public function run(): void {
+        // process the job payload from $this->payload
+    }
+}
+```
+
+The `run()` method has no parameters and returns void. Job data is accessed via `$this->payload` (or the framework's equivalent property). Do not add parameters to `run()`.
+
+## Worker dispatch — never call directly
+
+Workers must only be invoked via the queue dispatcher. Never call a worker's `run()` method directly from a controller, another worker, or any non-queue context.
+
+```php
+// CRITICAL VIOLATION — direct call
+$worker = new _Worker_BatchOrders($payload);
+$worker->run();
+
+// CORRECT — dispatch through queue
+_Queue::dispatch('_Worker_BatchOrders', $payload);
+// or the framework's equivalent dispatch method
+```
+
+Direct calls bypass retry logic, error handling, visibility timeout, and monitoring. Even in development or testing, use the sync queue adapter — do not call `run()` directly.
+
+## API response envelope (api2 only)
+
+Every action method in `api2` controllers must return an array with exactly these keys:
+
+```php
+return [
+    'success' => true,          // bool — true on success, false on error
+    'data'    => $result,       // mixed — the response payload (null on error)
+    'errors'  => [],            // array — list of error messages (empty on success)
+];
+```
+
+Never return a raw string, a bare array without these keys, or a nested different structure. The envelope is what clients depend on. Deviating from it breaks API consumers silently.
+
+For error responses:
+
+```php
+return [
+    'success' => false,
+    'data'    => null,
+    'errors'  => ['Order not found'],
+];
+```
+
+## Checking dependencies before touching shared code
+
+`dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):
+
+1. Read `knowledge/2.0/apps/_underscore/architecture.md`.
+2. Check which repos depend on the class you are modifying (search `dependsOn` in registry.json).
+3. Verify your change does not break the contract expected by dependent repos.
+
+Changing a `_Worker` base class method signature without checking `worker2` and `api2` is a common source of runtime failures.
+
+## Adding new worker action types
+
+Before adding a new worker class in `worker2`:
+
+1. Read `knowledge/2.0/apps/worker2/architecture.md` — check the existing action type registry.
+2. Register the new worker in the appropriate config or registry file (the architecture doc identifies where).
+3. Add a corresponding feature doc: `knowledge/2.0/apps/worker2/features/<action-name>.md`.
+
+Do not add a worker class without registering it. Unregistered workers cannot be dispatched.
+
+## Error handling in workers
+
+Workers must catch specific exceptions and handle them appropriately. A worker that throws an uncaught exception will be retried by the queue (up to the configured retry limit) and then dead-lettered.
+
+```php
+public function run(): void {
+    try {
+        $this->processOrder($this->payload['order_id']);
+    } catch (_Exception_OrderNotFound $e) {
+        // Do not retry — log and discard
+        error_log('Worker: order not found, discarding job: ' . $e->getMessage());
+        return;
+    } catch (_Exception_Database $e) {
+        // Retriable — re-throw so queue retries
+        error_log('Worker: DB error, will retry: ' . $e->getMessage());
+        throw $e;
+    }
+}
+```
+
+Distinguish between retriable errors (transient DB/network issues — re-throw) and non-retriable errors (bad data, missing record — log and return).