toga-ai 1.0.52 → 1.0.54

package/knowledge/CONVENTIONS.md

@@ -24,10 +24,10 @@ knowledge/
 ├── registry.json          # repo ↔ project ↔ framework ↔ role ↔ dependsOn
 ├── INDEX.md               # auto-generated master index
 ├── 1.0/
-│   ├── apps/<repo>/architecture.md + features/*.md
+│   ├── apps/<repo>/architecture.md + features/*.md + workflows/*.md
 │   └── standards/*.md     # 1.0 coding standards (App_)
 ├── 2.0/
-│   ├── apps/<repo>/architecture.md + features/*.md
+│   ├── apps/<repo>/architecture.md + features/*.md + workflows/*.md
 │   └── standards/*.md     # 2.0 coding standards (_underscore)
 └── clients/<client>/
     ├── profile.md
@@ -83,13 +83,33 @@ declares the files it covers, so the doc indexes into the code.
 
 ## Document types
 
+The knowledge base is organized by **subject** (a capability, a process, a component), never
+by session or ticket. `capture` assigns the type — **developers never classify.**
+
 - **architecture** — how a repo/framework works overall (one per repo). _Elevated._
-- **feature** — a discrete, shared capability or repeatable workflow within a repo.
-- **client-feature** — a client's customization/override of a shared feature; links
-  back to the shared `apps/<repo>/features/<base>.md`.
-- **workflow** — a client business process.
+- **feature** — a capability anchored to specific code in a repo (a model, a class, a set of
+  files). Its template carries a **How it works** section, so the *process* of a feature lives
+  inside the feature doc — most features contain a process, and that does not make them a
+  workflow. Lives in `apps/<repo>/features/`.
+- **workflow** — a standalone, multi-step process that **no single capability owns**; it spans
+  systems/actors/time. Two homes: operational/system processes in `apps/<repo>/workflows/`
+  (e.g. a deploy or reconciliation procedure), and client business processes in
+  `clients/<client>/workflows/`.
+- **client-feature** — a client's customization/override of a shared feature; links back to
+  the shared `apps/<repo>/features/<base>.md`.
 - **standard** — a coding standard for a framework. _Elevated._
 
+**Choosing the type (capture's rule — default to feature):**
+- "Can I point at one capability/model/class that *is* this?" → **feature** (its process goes
+  in the *How it works* section).
+- "Is this a sequence of steps spanning systems/actors that is a *procedure*, not a thing?" →
+  **workflow.**
+- When in doubt → **feature.** Defaulting prevents workflow-file sprawl.
+
+**Bugs are not a type.** A bug fix's durable lesson attaches as a **gotcha** (or a one-line
+*Change history* entry) on the feature/workflow doc that owns the affected code — never a
+standalone doc. Only a recurring/systemic failure class warrants its own record, case by case.
+
 _Elevated_ docs (architecture, standard) are senior-owned; `capture` flags any change
 to them with ⚠ so the developer knows what they're approving.
 

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

@@ -2,6 +2,6 @@
 
 | 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 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: Item Fulfillments for Sales Order Items TableView (tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in Client_Compass) was rebuilt as part of the tracking-number bridge migra | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql |
 | [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,10 +5,12 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-08
+updated: 2026-06-11
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - api2/Component/Api/Cxml/Cxml.php
+  - dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -21,41 +23,81 @@ IFIUs for serialized units, and IF packages for tracking. ASNs arrive two ways:
 **cXML** (direct V2 API) and the worker email cron
 `3b_import_strategic_systems_advance_shipping_notices.php`.
 
+Tracking numbers are propagated across **every** ASN and IF granularity (see *Tracking number
+propagation* below), so a single ShipNotice tracking number lands at the header, item, and
+unit level on both sides — not just on one unit.
+
 ## Key files / entry points
+- `api2/Component/Api/Cxml/Cxml.php` — the cXML `ShipNoticeRequest` translator that builds
+  the `/advance-shipping-notices` POST payload.
 - `_underscore/Model/Compass/AdvanceShippingNotice.php` — `postPost(&$api, &$payload)`.
 - Fires only when the Compass ASN `ApiPayloadInterceptors` rows exist (interceptor is DB-driven).
+- `Model/Compass/Usa/` and `Model/Compass/Canada/` ASN classes are **empty subclasses** that
+  inherit `postPost` from `_Model_Compass_AdvanceShippingNotice` — edit the parent.
 
 ## 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.
+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).
 
+## Tracking number propagation
+The cXML translator maps each `ShipControl` block's tracking number to a line via its
+`LineNumber` Extrinsic (it iterates **all** ShipControls and **all** ShipNoticeItems, not just
+`[0]`), then attaches the number at every level. End state for a cXML ShipNotice:
+
+| Table | Populated by |
+|---|---|
+| `AdvanceShippingNotices_TrackingNumbers` | cXML payload (ASN header) |
+| `AdvanceShippingNoticeItems_TrackingNumbers` | cXML payload (matched line's item) |
+| `AdvanceShippingNoticeItemUnits_TrackingNumbers` | cXML payload (tracking-only unit) |
+| `ItemFulfillments_TrackingNumbers` | `postPost` IF package |
+| `ItemFulfillmentItems_TrackingNumbers` | `postPost` (copies ASN-item tracking) |
+| `ItemFulfillmentItemUnits_TrackingNumbers` | `postPost` — **only when serialized units exist** |
+
+Fix-forward only (decided 2026-06-11): applies to new ShipNotices; existing records are not
+backfilled.
+
 ## 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.
+  IFIU; its tracking belongs on an `ItemFulfillmentPackage` / `ItemFulfillments_TrackingNumbers`.
+  So for a tracking-only ShipNotice (no serialized units, the Office Depot norm) the IFIU
+  bridge legitimately stays empty — there are no IF item units to attach to.
+- Tracking bridge Records (Core): ASN = 216 (unit) / 217 (item) / 218 (header);
+  IF = 317 (header) / 318 (item) / 319 (unit). All six are registered inherent children of
+  their parents, so the nested payload keys are accepted with no metadata migration.
 
 ## Client variations
 Compass USA handler (`Model/Compass/`), extending `_Model_Client_AdvanceShippingNotice`.
-Compass Canada (`Model/Compass/Canada/`) is a separate sub-client.
+Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass cXML API
+(Core `ClientApiIdentities` identity `153531108`, clientId 2) holds roles 1 and 3.
 
 ## Gotchas / known issues
+- **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`,
+  so ASN-item-level tracking POSTs were rejected (`EZ-1`). `dbchanges2/Client_Compass/2026-06-11
+  - AsnItemTrackingNumberAcl.sql` grants role 3 CRUD + role 7 read at the record level and
+  roles 1/3/4 writable at the field level, mirroring sibling Record 216. **This SQL must be
+  executed against the Compass DB before the cXML change works end-to-end.**
 - **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.
+  SO SA132502 / IF 66997) are **not backfilled** — fix-forward only.
 - 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.
+- **cXML SQL-injection hardening (2026-06-11):** the `ShipNoticeRequest` path interpolated the
+  cXML `Sender` Identity / SharedSecret and the OrderReference `orderID` (purchase order
+  number) straight into queries. These are now passed through `_Database::escape()`.
 - 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.52",
+  "version": "1.0.54",
   "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

@@ -1,6 +1,6 @@
 ---
 name: capture
-description: End-of-session knowledge writer for TOGA Technology projects. Run this at the END of a coding session to record what you worked on into the team `claude` knowledge base. It figures out what changed this session, matches it against existing knowledge, and proposes create/update/retire changes for one-tap approval — then writes them, keeping registry.json, frontmatter, and INDEX files consistent. Trigger whenever the user says "capture", "wrap up", "save my work to the knowledge base", "I'm done — record this", or finishes a feature and wants it documented.
+description: End-of-session knowledge writer for TOGA Technology projects. Run this at the END of a coding session to record what you worked on into the team `claude` knowledge base. It figures out what changed this session, matches it against existing knowledge, and proposes create/update/retire changes for one-tap approval — then writes them, keeping registry.json, frontmatter, and INDEX files consistent. Run at the END of EVERY session — not only for finished features but also for small bug fixes and "I just changed the way something works"; capture decides what is durable (usually a small UPDATE to an existing doc, sometimes a NO-OP). Trigger whenever the user says "capture", "wrap up", "save my work to the knowledge base", "I'm done — record this", or ends a session.
 ---
 
 # Capture — record this session's work into the team knowledge base
@@ -110,9 +110,38 @@ node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --file=<to
 node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --q=<keywords>
 ```
 
-Classify each item as **CREATE** (no doc yet), **UPDATE** (a doc exists and needs new
-content / a new `files:` entry / a gotcha), or **DEPRECATE/DELETE** (the doc describes
-something now removed or obsolete).
+Classify each item as **CREATE** (no doc yet), **UPDATE** (a doc exists and needs new content /
+a new `files:` entry / a gotcha / a *Change history* line), **DEPRECATE/DELETE** (the doc
+describes something now removed or obsolete), or **NO-OP** (nothing durable — see below).
+
+### Always run; capture decides what (if anything) is durable
+
+`/capture` runs at the end of **every** session — including small bug fixes and "I just changed
+the way something works," not only finished features. The KB is organized by **subject** (a
+capability, a process, a component), **not** by session or ticket, so capturing small work is
+safe: it almost always **UPDATES one existing subject doc**, and rarely creates one.
+
+**Guardrails against pollution (enforce these):**
+- **One doc per subject** — never one per change, bug, or ticket.
+- **Bias UPDATE over CREATE** — always search for an owning doc first; CREATE only when no
+  subject doc exists. A small "how it works" change UPDATES the feature's *How it works* section
+  and adds a dated one-line *Change history* entry, in place — it does not spawn a new file.
+- **Relevance test** — for every candidate write ask: *"Will a teammate six months from now act
+  differently because this is written?"* If no → **NO-OP**.
+- **NO-OP is a blessed, first-class outcome.** If nothing rises to durable knowledge (typo,
+  formatting, a fix obvious from the code), write nothing and report: "Nothing here is durable
+  team knowledge — KB unchanged." Never manufacture a doc to justify the run.
+
+**Type assignment (you assign it — developers never classify; default to feature):**
+- Anchored to one capability/model/class? → **feature** (its process → the *How it works* section).
+- A standalone multi-step process no single capability owns? → **workflow**
+  (`apps/<repo>/workflows/` for operational/system processes; `clients/<client>/workflows/` for
+  client business processes).
+- A client's override of a shared feature? → **client-feature**.
+- A reversible team-wide rule/decision? → **standard** (⚠ elevated).
+- A bug's durable lesson? → a **gotcha** or *Change history* line on the doc that owns the
+  affected code — **never its own doc.**
+- When in doubt → **feature.**
 
 ## Step 4 — Build the proposal (one-tap approval)
 
@@ -217,27 +246,36 @@ How behavior differs per client (or "none — uniform").
 ## Gotchas / known issues
 The non-obvious things future-you will trip on.
 
+## Change history
+Dated one-liners, newest first — notable behavior changes only. Keep it terse; this is not a
+git log. Cap at ~10 entries; fold older ones away.
+- YYYY-MM-DD — <what changed and why> (<author>)
+
 ## Related docs
 Links.
 ```
 
-### workflow (client business process)
+### workflow (a standalone process — operational OR client business)
+Two homes: `apps/<repo>/workflows/` for operational/system processes (set `repo`,
+`client: shared`); `clients/<client>/workflows/` for client business processes (set the
+`client` slug, omit `repo`).
 ```markdown
 ---
 title: <Workflow Name>
 framework: "<1.0|2.0>"
+repo: <repo>            # for apps/<repo>/workflows/; omit for a pure client workflow
 project: <Project>
-client: <client-slug>
+client: <shared|client-slug>
 type: workflow
 status: active
 updated: <YYYY-MM-DD>
 owners: ["<AUTHOR_USERNAME>"]   # from Step 1b — never empty
-files: []
+files: []               # source files the process touches, if any
 related: []
 ---
 
 ## Summary
-The business process and who it serves.
+The process, who/what it serves, and what triggers it.
 
 ## Steps
 1. …
@@ -247,6 +285,10 @@ Apps/repos, integrations, data.
 
 ## Edge cases & escalation
 What can go wrong and who handles it.
+
+## Change history
+Dated one-liners, newest first. Keep terse; cap at ~10.
+- YYYY-MM-DD — <what changed and why> (<author>)
 ```
 
 ### architecture (one per repo) — ⚠ ELEVATED