toga-ai 1.0.73 → 1.0.75

package/knowledge/1.0/apps/library/features/elite-freshservice-sync.md

@@ -164,3 +164,6 @@ Pass `true` for the dedup GET — errors must not silently empty the dedup array
 
 Each ticket sync is wrapped in `try/catch` — exceptions are sent to Sentry and the run
 continues with the next ticket. A single bad ticket does not abort the whole sync.
+
+## Change history
+- 2026-06-10 — Documented `App_Api_Toga2::syncWithTogadesk` orchestration (bidirectional TOGA 2 ↔ TOGaDesk ticket/note/file sync, watermarks, `ticketNoteFiles` gotcha).

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -105,6 +105,9 @@ attempted.
 - `createNetsuiteItemFulfillment` doesn't set carrier/method on the NS IF — it defaults
   (can show FedEx for a UPS shipment). Open item.
 
+## Change history
+- 2026-06-10 — Documented carrier shipping label mechanics (UPS/FedEx) + the authoritative GIF label-storage decision and NetSuite IF attachment. (mhammontree)
+
 ## Related docs
 
 - [Fulfill & Ship (toga2-supply)](../../toga2-supply/features/fulfill-and-ship.md) —

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

@@ -106,6 +106,9 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
 - **Performance:** every child write re-runs a full upstream walk (read-heavy, but each
   upstream record is written at most once — idempotent). Fine for normal fulfillment sizes.
 
+## Change history
+- 2026-06-08 — Documented the Recursive Item Fulfillments engine (interceptor-driven upstream fulfillment mirroring, bundle scaling, reconcile loop). (jcardinal)
+
 ## Related docs
 - `_underscore` architecture (interceptors, `internalApiRequest`, `_Model` layer).
 - `api2` architecture (V2 metadata engine that fires these interceptors; the

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -117,6 +117,9 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   `_underscore` + `api2` + `worker` + `library` together. Run the additions/migrations DB file first;
   run the companion `..._DROPS.sql` (and the Core deletes) only after the bridges + app are confirmed.
 
+## Change history
+- 2026-06-10 — Documented the tracking-number bridge migration: scalar FK columns → `*_TrackingNumbers` bridge tables across ASN/IF/IR, ASN unit table rename, packages-table consolidation. (jcardinal)
+
 ## Related docs
 - Recursive Item Fulfillment feature (the upstream-sync engine this migration reworked).
 - compass-usa: ASN→Item Fulfillment, and the Item Fulfillment tracking TableView.

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -110,3 +110,6 @@ None in the flow itself — but the NetSuite trait is composed into **client-spe
 model subclasses (e.g. `_Model_Growrk_ItemFulfillment uses _Trait_Netsuite_ItemFulfillment`),
 not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support was built
 for Compass and is not yet in prod.
+
+## Change history
+- 2026-06-10 — Documented the Fulfill & Ship flow (SO sync, label purchase, NetSuite IF creation, success gating, reprint). Driven green on beta for UPS/GroWrk; FedEx + prod verification pending. (mhammontree)

package/knowledge/2.0/apps/worker2/features/clickup-project-routing.md

@@ -117,6 +117,9 @@ Read-only actions (no writes), invoked via `curl -X POST https://worker.togahub.
 `DiagnoseOpportunity`, `DiagnoseAmTask` (routing verdicts), `DiscoverIds`, `DiscoverAmIds`
 (print constant declarations), `RegisterOpportunityWebhook` (one-time setup).
 
+## Change history
+- 2026-06-09 — Documented ClickUp secondary multi-list routing (hybrid native-automation + worker design, three space handlers, self-trigger guard). (jcardinal)
+
 ## Related docs
 
 - [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS.

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -133,3 +133,6 @@ Use realistic placeholder values, not empty strings/nulls.
 - If the action needs a client DB, register it in `initialize()` — it runs before the method.
 - See [architecture.md](../architecture.md) for the always-HTTP-200 rule and the
   commit-before-SQS transaction pattern that the worker relies on.
+
+## Change history
+- 2026-06-08 — Documented the worker-action contract (path→class/method convention, parameter typing, webhook/cron templates); replaces the former `/worker2-action` skill. (jcardinal)

package/knowledge/2.0/apps/worker2/features/elite-freshservice-sync.md

@@ -141,3 +141,7 @@ To test worker2 Elite code locally against production TOGA 2 and Freshservice:
 
 4. **PHP version** — worker2 vendor targets PHP >= 8.5. Local PHP 8.1 requires a
    temporary bypass in `vendor/composer/platform_check.php` — revert before committing.
+
+## Change history
+- 2026-06-11 — Redacted Elite credential constants from the doc; secret scanner added to `validate`.
+- 2026-06-10 — Documented `_Worker_Elite` Freshservice → TOGA 2 webhook sync (conversation/attachment handling, TOGA 2 API gotchas, local dev setup).

package/knowledge/2.0/apps/worker2/features/monitoring-framework.md

@@ -176,6 +176,9 @@ clients' data flows (Compass, Prudential, AIG, …) but live as separate child c
 - Slack / SMS / PagerDuty (email-only today) · `MonitorRuns` history table ·
   HTML email + dashboard deep-links · anti-flap on the alarm side.
 
+## Change history
+- 2026-06-10 — Documented the v1.0 monitoring framework (orchestrator, `Core.Monitors` table, recovery-side anti-flap state machine, child contract). First child monitor + staging/prod migration still pending. (mhammontree)
+
 ## Related docs
 
 - [worker2 architecture](../architecture.md) — cron/WorkerJobs pipeline the orchestrator rides on

package/knowledge/CONVENTIONS.md

@@ -113,6 +113,22 @@ standalone doc. Only a recurring/systemic failure class warrants its own record,
 _Elevated_ docs (architecture, standard) are senior-owned; `capture` flags any change
 to them with ⚠ so the developer knows what they're approving.
 
+## Required sections
+
+Every **feature**, **client-feature**, and **workflow** doc must include a
+**`## Change history`** section: newest-first, dated one-line entries recording notable
+behavior changes only (not a git log). Format:
+
+```markdown
+## Change history
+- YYYY-MM-DD — <what changed and why> (<author>)
+```
+
+`node knowledge.js validate` enforces this — a missing `## Change history` section in any of
+those three doc types fails the build (and therefore blocks `capture`'s publish). `profile`,
+`architecture`, and `standard` docs are exempt. Keep the list terse and cap it at ~10 entries,
+folding older ones away.
+
 ## INDEX.md files
 
 Never hand-edited. `node knowledge.js index` regenerates the master `INDEX.md`, each

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

@@ -2,7 +2,7 @@
 
 | 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, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql |
+| [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, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.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

@@ -5,12 +5,13 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-11
+updated: 2026-06-15
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
   - api2/Component/Api/Cxml/Cxml.php
   - dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql
+  - dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -36,16 +37,28 @@ unit level on both sides — not just on one unit.
   inherit `postPost` from `_Model_Compass_AdvanceShippingNotice` — edit the parent.
 
 ## How it works
+As of **2026-06-15** the handler **reconciles tracking onto whatever fulfillment exists** —
+it no longer only attaches tracking when it creates new fulfillment (see *Change history* and
+the gotcha about already-fulfilled orders). Flow:
+
 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 copy that ASN item's tracking numbers
-   (`AdvanceShippingNoticeItems_TrackingNumbers`) onto the IF item via
-   `POST /item-fulfillment-item-tracking-numbers` → `ItemFulfillmentItems_TrackingNumbers`.
-5. Per ASN unit: if it has a Unit (serialized) → POST an IFIU (carrying unit tracking); 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).
+2. Select **all** ASN items mapped to a SalesOrderItem (NO "unfulfilled only" filter), carrying
+   each SOI's `quantity` and already-`SUM`med fulfilled qty.
+3. Per ASN item, compute `remaining = SOI.quantity − fulfilled` (rounded to kill float dust):
+   - **`remaining > 0`** (create path, unchanged): reuse the SO-numbered IF or POST a new one,
+     POST an IFI; that new IFI is the tracking target. Additional SO-numbered IFs are acceptable.
+   - **`remaining <= 0`** (reconcile path, new): the tracking targets are the **existing IFIs**
+     for that SOI (resolved via `ItemFulfillmentItems.salesOrderItemId` → their `itemFulfillmentId`),
+     **not** an SO-number lookup — NetSuite/toga2-supply IFs are `F`-numbered, not SO-numbered.
+4. Copy the ASN item's tracking (`AdvanceShippingNoticeItems_TrackingNumbers`) onto each target
+   IFI via `POST /item-fulfillment-item-tracking-numbers` → `ItemFulfillmentItems_TrackingNumbers`
+   — **idempotent** (skipped if the bridge row already exists; ASNs get re-POSTed).
+5. Per ASN unit: serialized (has a Unit) → attach unit tracking to the matching IFIU
+   (`POST /item-fulfillment-item-unit-tracking-numbers`; create the IFIU only on the create path);
+   tracking-only (`unitId IS NULL`) → collect its tracking for an IF package.
+6. Create one IF package per unique tracking number (header-level merged with tracking-only
+   ASN-unit tracking, deduped by tracking-number **id**) on **each involved IF** — i.e. only the
+   IF(s) that received this ASN's tracking — all idempotent.
 
 ## Tracking number propagation
 The cXML translator maps each `ShipControl` block's tracking number to a line via its
@@ -62,7 +75,10 @@ The cXML translator maps each `ShipControl` block's tracking number to a line vi
 | `ItemFulfillmentItemUnits_TrackingNumbers` | `postPost` — **only when serialized units exist** |
 
 Fix-forward only (decided 2026-06-11): applies to new ShipNotices; existing records are not
-backfilled.
+backfilled (one-off backfills repair specific orders — e.g. `2026-06-15b` for SA132781).
+
+As of 2026-06-15 propagation also fires when the IF **already exists** (reconcile path), so the
+table above is populated even for SOs fulfilled out-of-band before the ASN arrived.
 
 ## Data model
 - `AdvanceShippingNoticeUnits.unitId` is nullable (tracking-only units have NULL).
@@ -80,6 +96,24 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
 (Core `ClientApiIdentities` identity `153531108`, clientId 2) holds roles 1 and 3.
 
 ## Gotchas / known issues
+- **ASN arriving AFTER the SO is already fulfilled (fixed 2026-06-15):** when an SO is fulfilled
+  out-of-band (NetSuite/toga2-supply creates `F`-numbered IFs) **before** its ASN arrives,
+  `postPost` previously found zero unfulfilled ASN items and skipped the **entire** propagation
+  block (the old `if ($asnItemsQuery->getRowCount())` gate wrapped even the header-package
+  creation) — so the ASN's tracking was lost at every level. Symptom: SO **SA132781** (id 105943)
+  had tracking on the ASN (header/item/unit) but none on its IFs (68063/68154). Fix: reconcile
+  onto existing fulfillment (see *How it works*). Forward-only; SA132781 repaired by the backfill
+  migration `2026-06-15b`.
+- **A NULL `AdvanceShippingNoticeItemUnits.unitId` is CORRECT — do NOT add a NOT NULL
+  constraint.** Office Depot (vendorId 1) ships via cXML and **never sends serial numbers**;
+  the cXML→JSON translator deliberately creates a tracking-only ASN unit (no `unit`, NULL
+  `unitId`) purely to carry the unit-level tracking number. Verified against the raw cXML
+  (`Logs_Compass.Api`) for SA132781. A NOT NULL constraint would reject the majority of Compass
+  ASN volume (~56k of ~101k units are tracking-only) and break tracking ingestion. A serialized
+  `Unit` seen on the IF side (e.g. created by NetSuite) is unrelated to the tracking-only ASN unit.
+- **Idempotency:** every tracking attach is guarded by a SELECT-before-POST on the bridge table,
+  so re-POSTing the same ASN does not duplicate `ItemFulfillment(s|Items|ItemUnits)_TrackingNumbers`
+  rows. New attach helpers depend on this — keep the guard if extending.
 - **Record 217 ACL gap (fixed 2026-06-11):** `AdvanceShippingNoticeItems_TrackingNumbers`
   (Record 217) had **zero** `AclRecordPermissions` and its `advanceShippingNoticeItemId`
   (RecordField 1440) / `trackingNumberId` (1441) fields had **zero** `AclFieldPermissions`,
@@ -101,5 +135,16 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
 - 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.
 
+## Change history
+Dated one-liners, newest first.
+- 2026-06-15 — `postPost` rewritten to reconcile ASN tracking onto **existing** fulfillment
+  (not just newly-created IFs), idempotently; fixes lost tracking when the SO was fulfilled
+  out-of-band before the ASN (e.g. SA132781). Confirmed NULL `unitId` is by-design for Office
+  Depot tracking-only units (no NOT NULL constraint). Backfill `2026-06-15b` repairs SA132781. (jcardinal)
+- 2026-06-11 — Record 217 ACL grant so ASN-item-level tracking POSTs succeed; cXML SQL-injection
+  hardening; tracking propagated across all ASN/IF granularities. (jcardinal)
+- 2026-06-08 — IFIU query switched to `LEFT OUTER JOIN Units`; tracking-only units routed to IF
+  packages (previously dropped by an INNER JOIN). (jcardinal)
+
 ## Related docs
 - Recursive Item Fulfillments (upstream mirroring) — the engine these IFs/packages feed.

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -186,6 +186,9 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 5. With no staging environment, verify with a standalone arithmetic simulation plus a read
    of the consumer query; `php -l` every touched file.
 
+## Change history
+- 2026-06-10 — Documented the NYC DOE ServiceNow/ASN integration (ticket mirror, dual ASN ingestion, NetSuite freeze pipeline, EDI surface, dedupeKey gotchas). (mhammontree)
+
 ## Related docs
 
 - [NYC DOE client profile](../profile.md)

package/knowledge.js

@@ -612,6 +612,14 @@ function cmdValidate() {
             if (!d.data[f]) { fail(`${d.rel}: missing frontmatter "${f}"`); ok = false; }
         }
         if (d.data.type && !DOC_TYPES.includes(d.data.type)) { fail(`${d.rel}: invalid type "${d.data.type}"`); ok = false; }
+        // feature/client-feature/workflow docs must carry a "## Change history" section so the
+        // doc records its own notable behavior changes over time (newest-first dated one-liners).
+        if (['feature', 'client-feature', 'workflow'].includes(d.data.type)) {
+            if (!/^##\s+Change history\s*$/m.test(fs.readFileSync(d.file, 'utf8'))) {
+                fail(`${d.rel}: missing required "## Change history" section`);
+                ok = false;
+            }
+        }
         const isClientDoc = d.rel.startsWith('clients/');
         if (isClientDoc) {
             if (!d.data.client || d.data.client === 'shared') { fail(`${d.rel}: client doc must set a real "client"`); ok = false; }

package/package.json

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