toga-ai 1.0.27 → 1.0.29

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.27",
+  "version": "1.0.29",
   "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/skills/capture/SKILL.md

@@ -163,22 +163,45 @@ git -C "<TEAM_REPO>" status --short knowledge/
 ```
 If empty — report "No new knowledge to push" and exit cleanly.
 
-**Push:**
+**Commit:**
 ```bash
 git -C "<TEAM_REPO>" add knowledge/
 git -C "<TEAM_REPO>" diff --cached --quiet || \
   git -C "<TEAM_REPO>" commit -m "knowledge: <one-line summary>"
-git -C "<TEAM_REPO>" push origin HEAD:feature/ai-harness-improvements
 ```
 
 Never stage files outside `knowledge/`. If `git diff --cached` includes anything outside
 `knowledge/`, abort and warn before committing.
 
+**Sync, then push (rebase BEFORE pushing — this prevents the version-bump conflict):**
+
+Every push to this branch triggers a CI job that commits a `chore: bump version [skip ci]`
+back to the branch. So after *any* prior push (e.g. an earlier capture in the same session),
+your local branch is one commit behind the remote, and a naive push is rejected as a
+non-fast-forward. Rebase your fresh commit onto the remote **before** pushing — this pulls in
+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/_main
+git -C "<TEAM_REPO>" push origin HEAD:_main
+```
+
+> **Do NOT "pull after push" instead** — the bump commit for *this* push is created
+> asynchronously by CI a few seconds later, so pulling immediately afterward races CI and
+> usually grabs nothing. Rebasing *before* the push is what reliably avoids the conflict,
+> with zero dependency on npm build/publish timing.
+
+**If the push is still rejected** (a bump commit landed in the brief window between your
+rebase and push), simply repeat `fetch` → `rebase` → `push`, up to 2 more times. This is an
+expected occasional race, not an error — do not report it as a failure unless all retries are
+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