toga-ai 1.0.28 → 1.0.30

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -19,6 +19,7 @@ files:
 related:
   - ../architecture.md
   - ../../api2/architecture.md
+  - ../../../../clients/compass-usa/features/asn-to-item-fulfillment.md
 ---
 
 ## Summary

package/knowledge/INDEX.md

@@ -16,5 +16,6 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## Clients
 
-_No client knowledge captured yet._
+- **compass-canada** → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
+- **compass-usa** → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 

package/knowledge/clients/compass-canada/INDEX.md

@@ -0,0 +1,5 @@
+# Client: compass-canada
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |  |

package/knowledge/clients/compass-canada/profile.md

@@ -0,0 +1,33 @@
+---
+title: Compass Canada
+framework: "2.0"
+project: _Underscore
+client: compass-canada
+type: profile
+status: active
+updated: 2026-06-08
+owners: [jcardinal]
+files: []
+related:
+  - ../compass-usa/profile.md
+---
+
+## Summary
+Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related
+to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce/API platform
+(`_underscore`) and the **1.0** worker tier.
+
+## Platforms & data
+- **2.0:** `_underscore` backend, prod schema `Client_CompassCanada` (archive
+  `Archive_CompassCanada`, logs `Logs_CompassCanada`). Client-specific model overrides live
+  under `_underscore/Model/Compass/Canada/` (a sub-client of the Compass model tree).
+- **1.0:** worker crons under `worker/crons/toga2/compasscanada/`.
+
+## Vendors & integrations
+- Not yet captured. Confirm vendors / ASN ingestion paths before relying on them.
+
+## Notes
+- **Stub** — created alongside the Compass USA profile for disambiguation. The 2026-06-08 ASN
+  → ItemFulfillment work was for **Compass USA**, not Compass Canada. Expand this profile as
+  Compass Canada behavior is investigated.
+- Related: [Compass USA](../compass-usa/profile.md).

package/knowledge/clients/compass-usa/INDEX.md

@@ -0,0 +1,6 @@
+# Client: compass-usa
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php |
+| [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -0,0 +1,63 @@
+---
+title: Compass ASN → ItemFulfillment Auto-Creation
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-06-08
+owners: [jcardinal]
+files:
+  - _underscore/Model/Compass/AdvanceShippingNotice.php
+related:
+  - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
+---
+
+## Summary
+For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF)
+on the upstream SalesOrder. `_Model_Compass_AdvanceShippingNotice::postPost` walks PO → SO,
+then creates the IF (named after the SO number), one IFI per still-unfulfilled ASN item,
+IFIUs for serialized units, and IF packages for tracking. ASNs arrive two ways: Office Depot
+**cXML** (direct V2 API) and the worker email cron
+`3b_import_strategic_systems_advance_shipping_notices.php`.
+
+## Key files / entry points
+- `_underscore/Model/Compass/AdvanceShippingNotice.php` — `postPost(&$api, &$payload)`.
+- Fires only when the Compass ASN `ApiPayloadInterceptors` rows exist (interceptor is DB-driven).
+
+## How it works
+1. Read ASN → resolve PO → SO via `SalesOrders_PurchaseOrders`; skip if no SO.
+2. Select ASN items whose SOI still has unfulfilled qty (`SOI.quantity > SUM(IFI.quantity)`).
+3. Reuse the IF if one already exists with the SO number, else POST a new IF.
+4. Per ASN item: POST an IFI (qty = ASN item qty), then read its ASN units.
+5. Per ASN unit: if it has a Unit (serialized) → POST an IFIU; if it is tracking-only
+   (`unitId IS NULL`) → collect its tracking number for an IF package instead.
+6. Create one IF package per unique tracking number (header-level tracking merged with
+   tracking-only ASN-unit tracking, deduped by tracking-number uuid).
+
+## Data model
+- `AdvanceShippingNoticeUnits.unitId` is nullable (tracking-only units have NULL).
+- `ItemFulfillmentItemUnits.unitId` is **NOT NULL** — a tracking-only unit can never be an
+  IFIU; its tracking belongs on an `ItemFulfillmentPackage`.
+- Compass tracking lives in `ItemFulfillmentPackages` (header-level); IFIUs are only for
+  genuinely serialized units.
+
+## Client variations
+Compass USA handler (`Model/Compass/`), extending `_Model_Client_AdvanceShippingNotice`.
+Compass Canada (`Model/Compass/Canada/`) is a separate sub-client.
+
+## Gotchas / known issues
+- **Tracking-only ASN units (the majority — ~56k of ~101k in prod):** before 2026-06-08 the
+  IFIU query used `INNER JOIN Units`, silently dropping NULL-`unitId` rows, so cXML shipments
+  produced an IF + IFI with **no IFIU and no package — tracking was lost**. Fixed: `LEFT
+  OUTER JOIN Units` + route tracking-only units to IF packages. Historical records (e.g.
+  SO SA132502 / IF 66997) are **not backfilled** — fix-forward only; a one-time repair is
+  still an open decision.
+- Interceptor is **DB-driven**: `postPost` does nothing without the Compass
+  `ApiPayloadInterceptors` rows in that env.
+- The IF is named after the SO number; an already-existing IF with that number is reused.
+- Separate latent bug in the 1.0 worker: the Strategic Systems cron's no-serials branch
+  builds `$itemLevelTrackingNumbers` but never attaches it to the ASN payload.
+
+## Related docs
+- Recursive Item Fulfillments (upstream mirroring) — the engine these IFs/packages feed.

package/knowledge/clients/compass-usa/profile.md

@@ -0,0 +1,43 @@
+---
+title: Compass USA
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: profile
+status: active
+updated: 2026-06-08
+owners: [jcardinal]
+files: []
+related:
+  - features/asn-to-item-fulfillment.md
+---
+
+## Summary
+Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. Customer
+SalesOrders spawn PurchaseOrders to vendors; when vendors ship, AdvanceShippingNotices (ASNs)
+drive ItemFulfillment creation and (via the shared engine) upstream fulfillment mirroring.
+Compass USA spans both frameworks: the **2.0** commerce/API platform (`_underscore`, DB
+`Client_Compass`) and the **1.0** worker tier for scheduled integrations. Compass Canada is a
+separate, related client (see its own profile).
+
+## Platforms & data
+- **2.0:** `_underscore` backend, prod schema `Client_Compass` (worker link `db_compass`).
+  Client-specific model overrides live under `_underscore/Model/Compass/`.
+- **1.0:** worker crons under `worker/crons/toga2/compass/` handle email-based imports and
+  notifications.
+- Storefront: compass.togacommerce.com / compass.togahub.com.
+
+## Vendors & integrations
+- **Office Depot (ODP)** — vendor id 1. ASNs arrive via **cXML** (direct V2 API) and via the
+  email cron's ODP CSV format.
+- **Strategic Systems** — ASNs via the email cron's SS CSV format (serial numbers → Units).
+- ASN ingestion entry points: cXML to the V2 API (logged in `Logs_Compass.Api`) and
+  `worker/crons/toga2/compass/workflow/3b_import_strategic_systems_advance_shipping_notices.php`.
+
+## Key features (this client)
+- [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) — the
+  `_Model_Compass_AdvanceShippingNotice::postPost` handler.
+
+## Notes
+- Built on the shared 2.0 Recursive Item Fulfillments engine (upstream mirroring).
+- This profile is a starting point; expand as more Compass-specific behavior is captured.

package/knowledge.js

@@ -28,7 +28,7 @@ const path = require('path');
 const ROOT = path.join(__dirname, 'knowledge');
 const REGISTRY = path.join(ROOT, 'registry.json');
 const FRAMEWORKS = ['1.0', '2.0'];
-const DOC_TYPES = ['feature', 'client-feature', 'workflow', 'architecture', 'standard'];
+const DOC_TYPES = ['feature', 'client-feature', 'workflow', 'architecture', 'standard', 'profile'];
 const ELEVATED_TYPES = ['architecture', 'standard'];
 
 /* ------------------------------------------------------------------ */

package/package.json

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

package/rules/common/git-workflow.md

@@ -6,6 +6,13 @@ Never commit directly to `_main`. All changes go through feature branches and pu
 
 Never force-push to `_main` under any circumstances.
 
+> **Exception — the team knowledge/harness repo (`agilantsolutions/claude`, cloned to
+> `~/toga-tech`).** This rule governs the TOGA *application* repos (worker2, api2, library,
+> worker, _underscore). The knowledge repo's entire model is direct pushes to `_main` via the
+> `/capture` skill — that is intended and is not a violation. Direct commits to `_main` are
+> still **forbidden in all application repos**, and force-pushing `_main` is **never** allowed
+> in any repo, including the knowledge repo.
+
 ## Branch naming
 
 Use one of these prefixes followed by a short hyphenated description:

package/skills/capture/SKILL.md

@@ -183,8 +183,8 @@ commits that already exist (no waiting on CI), so the push fast-forwards cleanly
 
 ```bash
 git -C "<TEAM_REPO>" fetch origin
-git -C "<TEAM_REPO>" rebase origin/feature/ai-harness-improvements
-git -C "<TEAM_REPO>" push origin HEAD:feature/ai-harness-improvements
+git -C "<TEAM_REPO>" rebase origin/_main
+git -C "<TEAM_REPO>" push origin HEAD:_main
 ```
 
 > **Do NOT "pull after push" instead** — the bump commit for *this* push is created
@@ -198,10 +198,10 @@ expected occasional race, not an error — do not report it as a failure unless
 exhausted.
 
 **If push succeeds:**
-> "✓ Pushed to `feature/ai-harness-improvements` — CI publishes new npm version. Teammates get it on `npx toga-ai`."
+> "✓ Pushed to `_main` — CI publishes new npm version. Teammates get it on `npx toga-ai`."
 
 **If push fails** — show exact git error, then:
-> "⚠ Push failed: `<error>`. Run manually: `git -C <TEAM_REPO> push origin HEAD:feature/ai-harness-improvements`"
+> "⚠ Push failed: `<error>`. Run manually: `git -C <TEAM_REPO> push origin HEAD:_main`"
 
 ## Step 8 — Report