toga-ai 1.0.293 → 1.0.295

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,12 +6,13 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-07
-owners: ["bala"]
+updated: 2026-07-09
+owners: ["bala", "mhammontree"]
 files:
   - api2/Component/Api/V2/V2.php
 related:
   - ../architecture.md
+  - ../../../clients/aig/features/entitlement-intake.md
 ---
 
 ## Summary
@@ -57,6 +58,37 @@ rows on every write.
 If you need to link by a business key (like an employee XID), **resolve that key to a uuid in your
 caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 
+## Per-API overrides (`Apis_RecordFields`)
+
+The base identifier flags above (`Core.RecordFields.isIdentifier`) can be **overridden per API**
+via rows in a tenant's `Apis_RecordFields` table, read by the V2 resolver's override block
+(`V2.php` ~6926–6936; child policy in `getChildPolicy()` ~8019–8041; loader ~8526–8538). Two
+columns matter:
+
+- **`overrideIsIdentifier`** — overrides whether the field is a searchable identifier for that API.
+- **`overrideChildPolicy`** — overrides link-vs-create for the nested record (e.g. `MATCH_CREATE`
+  = match an existing child by identifier, else create it).
+
+> **Trap: a `NULL` `overrideIsIdentifier` is read as "not an identifier", not "no opinion".**
+> The override block evaluates `!$row->overrideIsIdentifier`, so a `NULL` **unsets** the field
+> from the API's searchable identifiers even when the base `Core.RecordFields` row has
+> `isIdentifier=1`. Any `Apis_RecordFields` row created **only** to set a child policy
+> (leaving `overrideIsIdentifier` NULL) will silently strip that field as an identifier. The
+> nested object then has no searchable identifier and the write fails **EV-12 VALIDATION**
+> (`V2.php:7094`) — the `MATCH_CREATE` that should have saved it never runs on that path.
+> Correct the data with an explicit `overrideIsIdentifier = 1`, or (systemic fix, not yet done)
+> change the code so only an explicit `0` removes an identifier and `NULL` means "no override".
+
+**Build divergence warning.** The `Apis_RecordFields` override feature (reading
+`overrideIsIdentifier`/`overrideChildPolicy`) was introduced 2026-03-20 (api2 commit `624146d`
+"Cache custom fields and API override lookups"). Environments on **older** builds ignore the
+override and keep the base identifier, so a tenant with identical Core metadata + override rows +
+data can behave differently across environments purely by build version. A NULL-`overrideIsIdentifier`
+override row that works on prod (older build) will start throwing EV-12 once prod gets the newer
+build — audit such rows before/with the deploy. First seen in AIG (TRUE-79978): prod resolved,
+beta/QA threw EV-12 on the injected `entitlementFulfillmentType` — see
+[AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md).
+
 ## Gotcha
 
 - **Nested write with only a non-identifier field silently creates duplicates.** This is a
@@ -68,6 +100,11 @@ caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 
 ## Change history
 
+- 2026-07-09 — Documented the per-API `Apis_RecordFields` override layer (`overrideIsIdentifier`,
+  `overrideChildPolicy`) and the trap that a `NULL` `overrideIsIdentifier` is read as "not an
+  identifier" (`!$row->overrideIsIdentifier`) — an override row set only for a child policy
+  silently strips the field as an identifier → EV-12 at `V2.php:7094`. Added the build-divergence
+  warning (override feature added 2026-03-20, commit `624146d`). Surfaced by AIG TRUE-79978. (mhammontree)
 - 2026-07-07 — Documented that api2 nested-relationship writes match an existing child **only** by
   identifier (`uuid`); a non-unique custom field is not a match key and forces a new-record insert.
   Correct pattern is `contact: {uuid}` (resolve business keys to uuid in the caller). Surfaced by
@@ -78,3 +115,5 @@ caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 - [api2 architecture](../architecture.md) — the V2 CRUD engine (`processRoutePairs`).
 - [Prudential device import + contact linking](../../../clients/prudential/features/device-information-import-and-contact-linking.md)
   — the production incident that exposed this behavior.
+- [AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md) — the TRUE-79978
+  EV-12 that exposed the `Apis_RecordFields` NULL-`overrideIsIdentifier` trap + build divergence.

package/knowledge/clients/aig/features/entitlement-intake.md

@@ -5,12 +5,13 @@ project: API
 client: aig
 type: client-feature
 status: active
-updated: 2026-06-19
+updated: 2026-07-09
 owners: ["mhammontree"]
 files:
   - _underscore/Model/Aig/Entitlement.php
   - dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql
 related:
+  - 2.0/apps/api2/features/nested-relationship-writes.md
   - 2.0/apps/api2/architecture.md
   - 2.0/apps/dbchanges2/architecture.md
   - 2.0/apps/_underscore/architecture.md
@@ -42,7 +43,9 @@ the FK can't resolve and intake fails with **"Missing AIG item ID."** Keeping
    - reads `partNumber = payload->saleItem->partNumber` and runs
      `SELECT id FROM Items WHERE partNumber = '{partNumber}' LIMIT 1` to get `$itemId`;
    - uses `$itemId` to load fulfillment **types** (`Items_EntitlementFulfillmentTypes`) and
-     **methods** (`Items_EntitlementFulfillmentMethods`) and injects them into the payload.
+     **methods** (`Items_EntitlementFulfillmentMethods`) and injects them into the payload as
+     **name-only** related objects (e.g. `entitlementFulfillmentType: {name: "Repair"}`). AIG
+     never sends `entitlementFulfillmentType`; it is populated entirely by this interceptor.
 3. The V2 engine resolves `Entitlement.saleItemId` (FK → `_Model_Client_Item`) from that same
    `saleItem.partNumber`. **No matching `Items` row → unresolvable FK → "Missing AIG item ID".**
 4. `postPost` then emails the contact a Staples Protection Plan registration link
@@ -118,9 +121,28 @@ this interceptor or use this dual-purpose Items pattern.
   codes are **not** in the SaleItemID spreadsheet and must be sourced separately if missing.
 - **No unique key on `Items.partNumber`** — use an anti-join for idempotent loads, not
   `INSERT IGNORE`.
+- **An `entitlementFulfillmentType` EV-12 VALIDATION error is NOT a bad client payload —
+  it's this interceptor's injected field failing to resolve.** AIG never sends that field;
+  the interceptor injects it as `{name: "Repair"}`. The error means the V2 resolver could not
+  find a searchable identifier for the injected object. Root cause (TRUE-79978) was an
+  `Apis_RecordFields` override row that stripped `name` as an identifier — see
+  [api2 nested-relationship writes → Per-API overrides](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+- **Empty `saleItem.partNumber` silently resolves to the wrong item.** The lookup is
+  `WHERE partNumber = '{$partNumber}' LIMIT 1`; when `partNumber` is `""`, it matches item
+  `id=10` ("2YR Tablet") — the first row with an empty part number — which carries a "Repair"
+  fulfillment type. So a blank part number does not fail loudly; it injects a spurious
+  name-only fulfillment type. The interceptor should guard an empty/failed lookup before
+  injecting (not yet fixed).
 
 ## Change history
 
+- 2026-07-09 — TRUE-79978: root-caused an `entitlementFulfillmentType` EV-12 on beta/QA. The
+  field is injected (name-only) by `prePost`; the beta `Client_Aig.Apis_RecordFields` override
+  row (apiId=2, recordFieldId=1202) had `overrideIsIdentifier=NULL` + `overrideChildPolicy=MATCH_CREATE`,
+  which the newer V2 build reads as "not an identifier", stripping `name` → no searchable id →
+  EV-12. Unblocked with a manual one-row beta data fix (`SET overrideIsIdentifier=1`); prod runs
+  an older build without the override feature so it still resolves. See the api2 feature doc for
+  the shared resolver behavior. (mhammontree)
 - 2026-06-19 — Documented intake flow; loaded 2,200 new SaleItem codes (1,700 STS `ASI-*`/`SM-*`
   + 500 unique numeric `SA`) into `Client_Aig.Items` via TRUE-79534, fixing "Missing AIG item ID"
   on the new `ASI-*` scheme. Follow-up to TRUE-79441. (mhammontree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.293",
+  "version": "1.0.295",
   "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/work-ticket/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: work-ticket
-description: Work an APPROVED ClickUp ticket plan end-to-end. Invoke as `/work-ticket <TICKET-ID>` (e.g. `/work-ticket TRUE-79868`) AFTER `/plan-ticket` has pushed an approved plan to the ticket's Pseudocode field. Loads the plan from the ticket's Pseudocode field, primes framework context via /kickoff (self-answered), implements the plan phase-by-phase with TOGA reviewers, then per repo creates a bare ticket-ID branch, commits, pushes, opens a PR, and posts the PR links as a comment on the ticket. Stops after PRs are open for your review — never changes ClickUp ticket status. Trigger on "/work-ticket", "work the ticket", "execute the plan for <ticket>", "build and PR <ticket>", "ship <ticket>".
+description: Work an APPROVED ClickUp ticket plan end-to-end. Invoke as `/work-ticket <TICKET-ID>` (e.g. `/work-ticket TRUE-79868`) AFTER `/plan-ticket` has pushed an approved plan to the ticket's Pseudocode field. Loads the plan from the ticket's Pseudocode field, primes framework context via /kickoff (self-answered), per repo creates and checks out a bare ticket-ID branch from the fresh remote default BEFORE any edits, implements the plan phase-by-phase with TOGA reviewers, then commits, pushes, opens a PR, and posts the PR links as a comment on the ticket. Stops after PRs are open for your review — never changes ClickUp ticket status. Trigger on "/work-ticket", "work the ticket", "execute the plan for <ticket>", "build and PR <ticket>", "ship <ticket>".
 ---
 
-# work-ticket — approved plan → code → branch → commit → PR → ClickUp GitHub tab
+# work-ticket — approved plan → branch → code → commit → PR → ClickUp GitHub tab
 
 The downstream companion to **`/plan-ticket`**. Given a ticket whose plan has already been
 approved and pushed to its **📝 Pseudocode** field, this skill executes that plan: it primes
-context, writes the code, then for **each repo the plan touches** creates a branch named the
-**bare ticket id**, commits, pushes, opens a PR, and posts the PR links as a ticket comment.
+context, then for **each repo the plan touches** creates and checks out a branch named the
+**bare ticket id** (cut from the freshly-fetched remote default) **BEFORE writing any code**,
+writes the code on that branch, commits, pushes, opens a PR, and posts the PR links as a
+ticket comment.
 ClickUp's native GitHub integration *may* surface those PRs in the ticket's **GitHub tab** when
-the repo is connected in ClickUp's GitHub settings (see Step 5b — not guaranteed), because the
+the repo is connected in ClickUp's GitHub settings (see Step 6b — not guaranteed), because the
 ticket id is in the
 branch name (and PR title/body).
 
@@ -62,14 +64,52 @@ Pass them as the trailing argument so kickoff goes straight to preflight + primi
 /kickoff <framework> <layer>, repos: <repos>, client: <client> — execute <TICKET> <title>
 ```
 
-Carry the `context-primer` briefing (framework rules, gotchas, client variations) into Step 3 —
+Carry the `context-primer` briefing (framework rules, gotchas, client variations) into Step 4 —
 it directly informs how each phase is implemented. Only stop to ask the developer if a kickoff
 gate answer is genuinely ambiguous after reading the plan header.
 
-## Step 3 — Execute the plan, phase by phase
+## Step 3 — Per repo: create & checkout the ticket branch BEFORE any edits
+
+**Branch FIRST, edit SECOND — never write a single line while sitting on `_main`/`_production`
+or on another ticket's branch.** Two reasons this ordering is mandatory:
+
+1. **Safety** — if work-in-progress gets committed (by you, a hook, or the developer), it lands
+   on the ticket branch, never on a default branch that deploys to prod.
+2. **Fresh base** — edits are made against the CURRENT remote default, not a stale local
+   checkout. (Real incident: a local `_production` was 12 commits behind and the target file had
+   changed upstream — editing before branching would have based the PR on stale code and
+   silently reverted the upstream changes.)
+
+For **each repo in the plan's `Repos:` header**, run inside that repo's path:
+
+```bash
+# 0. Working tree must be clean before starting — surface any stray edits to the developer
+git -C "<repo-path>" status --porcelain
+# 1. Resolve the repo's REAL default branch (e.g. _production for app repos, _main for dbchanges2)
+DEFAULT=$(gh repo view <owner/repo> --json defaultBranchRef -q .defaultBranchRef.name)
+# 2. Fetch so the base is current
+git -C "<repo-path>" fetch origin --quiet
+# 3. Reuse an existing TRUE-XXXX branch if present; otherwise cut a fresh one from origin/<default>
+git -C "<repo-path>" rev-parse --verify TRUE-XXXX 2>/dev/null \
+  && git -C "<repo-path>" checkout TRUE-XXXX \
+  || git -C "<repo-path>" checkout -b TRUE-XXXX "origin/$DEFAULT"
+```
+
+- Branch name = **bare ticket id** (team convention; what ClickUp's GitHub integration links on).
+- If `git status` shows uncommitted changes from a prior task, **stop and ask the developer**
+  before touching that repo — do not stash someone's work silently.
+- If reusing an existing `TRUE-XXXX` branch, still fetch and consider rebasing onto
+  `origin/<default>` so the PR diff stays current.
+- **Never branch off / commit to `_main`/`_production` directly**, and **never force-push**
+  (per `git-workflow.md`).
+
+Only after every in-scope repo is sitting on its ticket branch do you start writing code.
+
+## Step 4 — Execute the plan, phase by phase
 
 Implement the plan against the **real repo paths** (resolve each from the `repo-path-<repo>`
-memory kickoff established; never guess paths). For non-trivial work drive it as implement →
+memory kickoff established; never guess paths) — each repo already checked out on its ticket
+branch from Step 3. For non-trivial work drive it as implement →
 verify with subagents so the conversation stays the conductor:
 
 1. For each **phase** in the plan, an implementer subagent writes that phase's code at the
@@ -94,34 +134,13 @@ verify with subagents so the conversation stays the conductor:
 
 Do **not** push anything to a remote or open a PR until the code is implemented and clean.
 
-## Step 4 — Per repo: branch (bare ticket id), commit, push
+## Step 5 — Per repo: commit & push
 
 For **each repo in the plan's `Repos:` header** that has changes, run inside that repo's path:
 
-1. **Branch — bare ticket id, based on the CURRENT remote default.** This matches the team
-   convention (existing branches are `TRUE-79142`, `TRUE-77219`) and is exactly what ClickUp's
-   GitHub integration auto-links on. **The branch MUST be cut from freshly-fetched
-   `origin/<default>` — never from whatever local branch the repo happens to be sitting on.** A
-   working checkout is frequently parked on a *different, unmerged ticket's branch* (or a stale
-   local default); branching off that silently bases your PR on someone else's unmerged work and
-   produces a wrong, conflict-prone diff. So always **fetch first, then branch off the remote
-   default**, carrying your uncommitted Step 3 changes onto the new branch:
-   ```bash
-   # Resolve the repo's REAL default branch (e.g. _production for app repos, _main for dbchanges2)
-   DEFAULT=$(gh repo view <owner/repo> --json defaultBranchRef -q .defaultBranchRef.name)
-   git -C "<repo-path>" fetch origin --quiet
-   # Reuse an existing TRUE-XXXX branch if present; otherwise cut a fresh one from origin/<default>.
-   git -C "<repo-path>" rev-parse --verify TRUE-XXXX 2>/dev/null \
-     && git -C "<repo-path>" checkout TRUE-XXXX \
-     || git -C "<repo-path>" checkout -b TRUE-XXXX "origin/$DEFAULT"
-   ```
-   `git checkout -b … origin/$DEFAULT` keeps your uncommitted working-tree edits and re-bases them
-   onto the latest remote default in one step. **First confirm `git status` shows only the files
-   your plan changed** (no stray edits from a prior ticket) before branching. If the checkout is
-   refused because a file you edited also changed on the default, `git stash` → `checkout -b … origin/$DEFAULT`
-   → `git stash pop` and resolve. **Never branch off / commit to `_main`/`_production` directly**,
-   and **never force-push** (per `git-workflow.md`). If already on the `TRUE-XXXX` branch, still
-   `git fetch` and consider rebasing onto `origin/<default>` so the PR diff stays current.
+1. **Verify the branch.** Confirm `git branch --show-current` is the `TRUE-XXXX` branch from
+   Step 3 — if the repo somehow ended up back on a default branch, go redo Step 3 for it before
+   committing anything.
 2. **Commit.** Stage only the files the plan changed. Message format `type: short description`
    (`feat`/`fix`/`refactor`/`docs`/`test`/`chore`, lowercase, present tense, ≤72 chars). Add a
    body paragraph for substantial changes. **Pre-commit check:** `php -l` passes on changed PHP,
@@ -130,7 +149,7 @@ For **each repo in the plan's `Repos:` header** that has changes, run inside tha
 
 Repeat for every in-scope repo — one branch per repo, all named the same bare ticket id.
 
-## Step 5 — Open a PR per repo (auto-links to the ClickUp GitHub tab)
+## Step 6 — Open a PR per repo (auto-links to the ClickUp GitHub tab)
 
 For each pushed repo, open a PR with `gh` from that repo's path:
 
@@ -158,7 +177,7 @@ gh pr create --repo <owner/repo> --base <DEFAULT-BRANCH> --head <TICKET> \
 - End the PR body with the standard footer:
   `🤖 Generated with [Claude Code](https://claude.com/claude-code)`.
 
-### Step 5b — Post the PR links as a ClickUp comment (the RELIABLE link — do NOT skip)
+### Step 6b — Post the PR links as a ClickUp comment (the RELIABLE link — do NOT skip)
 
 **The native GitHub↔ClickUp tab is NOT reliable in this workspace.** It only populates if each
 repo is connected under ClickUp → Settings → Integrations → GitHub (a one-time workspace OAuth
@@ -181,12 +200,12 @@ fetch("https://api.clickup.com/api/v2/task/<TICKET>/comment?custom_task_ids=true
 (A comment does NOT populate the GitHub *tab* — it lands in the ticket's activity/comments —
 but it is the dependable way for the developer to reach the PRs from the ticket.)
 
-## Step 6 — Report & stop (do NOT touch ClickUp status)
+## Step 7 — Report & stop (do NOT touch ClickUp status)
 
 Summarize for the developer:
 - Ticket title and the repos that got changes.
 - For each repo: the branch name (`<TICKET>`) and the **PR url** `gh` returned.
-- Confirm the Step 5b comment was posted (the reliable link). State plainly that the GitHub
+- Confirm the Step 6b comment was posted (the reliable link). State plainly that the GitHub
   **tab** populates only if the repos are connected in ClickUp's GitHub integration settings —
   do not claim it will appear automatically.
 - **Remind the developer the next step is theirs:** review/approve the PR(s), then **manually
@@ -207,7 +226,7 @@ Offer `/capture` if a durable, KB-worthy finding emerged while implementing.
 - **Linking is NOT automatic.** The native GitHub tab requires a per-repo connection in ClickUp's
   GitHub integration settings (workspace OAuth, not doable from `gh`). The branch name + bare-id
   PR title + `CU-<internalId>` in the body are necessary but **not sufficient** — if the repo
-  isn't connected, the tab stays empty. Step 5b's comment is the reliable link; always post it.
+  isn't connected, the tab stays empty. Step 6b's comment is the reliable link; always post it.
 - **Autonomy boundary:** autonomous through PR creation; stops there. Moving the ClickUp ticket
   is always a manual developer action.
 - Run AFTER `/plan-ticket` has produced and the developer has approved a plan. This skill does