toga-ai 1.0.225 → 1.0.227

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php |
 | [ClickUp Connectivity Watchdog](features/clickup-connectivity-watchdog.md) | A cron watchdog that emails when the ClickUp integration looks disconnected during business hours. | worker2/Worker/Clickup/Health.php, worker2/Database/ClickupHealthWatchdog.sql |
+| [ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming](features/clickup-github-autolink.md) | How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch / PR-title naming convention that triggers it. |  |
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [ClickUp Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |

package/knowledge/2.0/apps/worker2/features/clickup-github-autolink.md

@@ -0,0 +1,44 @@
+---
+title: ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [dfranks]
+files: []
+related:
+  - ../workflows/ticket-to-pseudocode-planning.md
+---
+
+## Summary
+
+How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch /
+PR-title naming convention that triggers it. This is the linkage the `/work-ticket` skill
+depends on when it ships PRs for a planned ticket.
+
+## How it works
+
+- ClickUp's **native GitHub integration** automatically surfaces a branch, PR, or commit in a
+  ticket's GitHub tab **whenever the ticket id appears in the branch name and/or the PR
+  title/body**. The match is on the textual ticket id (e.g. `TRUE-79868`).
+- **There is no ClickUp API call to create this link.** The `plan-ticket/scripts/clickup.js`
+  helper exposes only `get` and `push` (the latter writes the `📝 Pseudocode` field). Linking
+  is purely a side effect of the ticket id appearing in Git metadata.
+- Therefore the durable rule for ticket work: name the **git branch as the BARE ticket id**
+  (e.g. `TRUE-79868`), **one branch per repo**, and include the ticket id in the PR body.
+  PRs default to base branch **`_main`**.
+
+## Branch naming overrides the generic git-workflow rule
+
+⚠ This intentionally **overrides** the generic `feature/<short-description>` type-prefix rule
+in `.claude/rules/toga/common/git-workflow.md` **for ticket-driven work**. The bare ticket-id
+branch name is exactly what ClickUp's native GitHub integration auto-links on, so a
+`feature/…` prefix would break the auto-link. Confirmed against live repos already on
+`TRUE-79142` (worker) and `TRUE-77219` (api2).
+
+## Change history
+
+- 2026-06-29 — Initial doc: ClickUp native GitHub integration auto-links any branch/PR carrying the ticket id (no API call; clickup.js exposes only get/push); convention is bare-ticket-id branch name (one per repo) + ticket id in PR body, base `_main`. Bare-id naming intentionally overrides git-workflow.md's feature/ prefix for ticket work, confirmed from live TRUE-79142 (worker) and TRUE-77219 (api2) branches (dfranks)

package/knowledge/2.0/apps/worker2/workflows/ticket-to-pseudocode-planning.md

@@ -6,13 +6,14 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-06-26
+updated: 2026-06-29
 owners: [dfranks]
 files:
   - test/@dave/clickup_md2delta.js
 related:
   - ../features/clickup-richtext-api.md
   - ../features/talos-meeting-notes-integration.md
+  - ../features/clickup-github-autolink.md
 ---
 
 ## Summary
@@ -55,6 +56,34 @@ under `test/@dave/approach/`):
   **Architecture decision** · **Phases** (each with file paths + pseudocode) · **Testing** ·
   **Risks** · **Owners / open questions** · **Key files**.
 
+## Downstream: plan → work pipeline
+
+Planning is the **first half** of a two-skill pipeline. Once the plan is approved and pushed
+to the ticket's `📝 Pseudocode` field, the **downstream `/work-ticket <TICKET-ID>` skill**
+(also a local skill, not in the team repo) implements it:
+
+1. **Loads the approved plan FROM the ticket's `📝 Pseudocode` field** — the field is the
+   source of truth, not the local `approach/<TICKET>.md`. It reads via
+   `plan-ticket/scripts/clickup.js get <TICKET>`, which returns JSON
+   `{id, custom_id, name, status, description, pseudocodeFieldId, url, fields:{…}}` where
+   `fields` is the non-empty custom fields keyed by display name. The plan is the `fields`
+   entry whose key contains "Pseudocode" (case-insensitive), as plain text. **Stops if empty.**
+2. **Primes framework context** (self-answered `/kickoff`) from the plan's
+   **Repos / Framework / Client** header line.
+3. **Implements phase-by-phase** with implementer subagents (worktree-isolated for independent
+   repos) + TOGA reviewers (php-reviewer / sql-reviewer) looping until clean.
+4. **Per repo in the plan's Repos header:** branch → commit → push, then opens **one PR per
+   repo** with `gh` (default base branch `_main`).
+5. **Reports and STOPS.**
+
+**Autonomy boundary (decided):** `/work-ticket` runs autonomously through PR creation, then
+stops. It **never changes the ClickUp ticket status** — advancing the ticket for approval is
+always a manual developer action, because the developer must review the PR(s) first.
+
+See [ClickUp GitHub-tab auto-linking & ticket-id branch naming](../features/clickup-github-autolink.md)
+for the branch/PR naming convention `/work-ticket` relies on.
+
 ## Change history
 
+- 2026-06-29 — Added the downstream half: `/plan-ticket` → `/work-ticket` pipeline. Records how `/work-ticket` loads the approved plan from the `📝 Pseudocode` field (clickup.js `get` JSON shape, "Pseudocode"-keyed plain-text value), implements phase-by-phase with reviewer loops, branches/commits/PRs per repo, and STOPS at PR creation — never touching ClickUp status (manual gate) (dfranks)
 - 2026-06-26 — Initial doc: ticket→pseudocode planning procedure (ClickUp read → codebase investigation → Talos DevCore grounding → phased plan → approval gate → guarded richtext push); records the shape, not the local skill source (dfranks)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 17 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 20 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 21 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -5,7 +5,7 @@ project: Worker
 client: tow-foundation
 type: client-feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-29
 owners: ["rgirish"]
 files:
   - worker2/Worker/Client/TowFoundation.php
@@ -60,7 +60,7 @@ Credit Card Receipts/
    - **`.docx` files bypass Talos** and route to `extractDocxData()` (Talos returns HTTP 500 on a `.docx` MIME type — it only accepts PDF/image). That method opens the docx as a ZIP, extracts `word/document.xml`, strips tags, and regex-parses `MM/DD/YY: description` lines into `line_items[]`
    - All other types POST to Talos AI `/api/ai/generate` → structured `{vendor_name, invoice_date, total, payment_memo, category, ...}`
    - **Year guard on AI dates** — if Talos returns an `invoice_date` whose year is more than 1 year from the current year (AI hallucination on two-digit year inputs, e.g. `5/13/76` → 1976, `5/28/28` → 2028), the year is clamped to the current year while month/day are preserved
-   - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with statement description
+   - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with the statement description. The statement memo is the **authoritative source for activity-purpose headings** (Grantee meeting, Peer meeting, Grantee event, etc.); the AI memo is good for location/detail but defaults to a bare `"Transportation:"` heading on ride-share/taxi receipts even when the receipt has handwritten activity notes. The override now fires when **either** the AI `payment_memo` is empty **or** it is a bare transportation memo — `isBareTranportationMemo()` returns true when the memo (left-trimmed) starts with `"Transportation:"`. Previously the override only fired on an empty AI memo, so a wrong `"Transportation:"` heading was never corrected.
    - **Zero-total fallback** — if the extracted/docx total is 0, `lookupStatementTotalByVendor()` derives the amount from the billing statement (see *Statement structure* below)
    - Build base filename (no suffix yet) and store in `$pendingRenames`
    - On extract failure → move to `Archive/exception/` immediately
@@ -157,6 +157,25 @@ the valid category names; keep them in sync with the map keys.
 to their QuickBooks Class and Payment Account strings. Ryan Farrell uses Bank of America
 Mastercard; all others use AMEX Open Credit Card.
 
+### MoveBack action (restore archived receipts for reprocessing)
+`MoveBack(string $person, string $billingCycle, ?string $year = null): string` is a public
+static action that walks the `Archive/` folder under a person's year directory and moves all
+receipt files (**excluding** `.xlsx`/`.xls`) back into the specified billing-cycle folder,
+creating the target folder if it does not exist. It is the supported way to restore receipts
+after a bad run (wrong memos, duplicate rows, etc.) so they can be reprocessed — it replaces
+the old one-shot `/tmp/tow_restore_archives.php` CLI script.
+
+```json
+{
+  "action": "Client/TowFoundation/ProcessReceipts/MoveBack",
+  "parameters": { "person": "Emily Tow", "billingCycle": "Amex ending in 06-03-2026" }
+}
+```
+
+`collectFilesRecursiveRaw(string $accessToken, string $driveId, string $parentId, array &$accumulator): void`
+walks all subfolders of `Archive/` (both the processed root and `exception/`) and collects
+every non-folder item into a flat accumulator array.
+
 ## Email routing
 
 Defined as constants in `TowFoundation.php`:
@@ -212,10 +231,12 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 - **Duplicate detection is within-run only** — if the same receipt was processed in a prior run and archived, it won't be caught. The dedup only covers receipts present in the current run's `$pendingRenames`.
 - **Unmapped AI categories pass through** — if the AI returns a category string not in `TowFoundationCategories.php`, `mapCategory()` logs a warning and writes the raw AI string to the Excel. Check error logs after a run if the Category column looks odd; add the new value to the map file to fix it.
 - **Short vendor acronyms (< 4 chars) require whole-word match** — the substring pass uses a word-boundary regex for needles under 4 chars to avoid false positives (e.g. `"UPS"` inside `"USPS"`). If a short vendor name is not matching, check that the QB vendor list entry starts or ends with the acronym as a whole word.
-- **Archive restore script** — a one-shot CLI script `/tmp/tow_restore_archives.php` was written 2026-06-23 to move archived files back to their billing-cycle folders for reprocessing. It is not committed; re-create from the session transcript if needed. It uses the production credentials from `Config/production.ini`.
+- **Restoring archived receipts** — use the committed `MoveBack` action (see *MoveBack action* above), not a one-shot CLI script. It moves all non-Excel receipt files from a person's `Archive/` back into the named billing-cycle folder. (The earlier throwaway `/tmp/tow_restore_archives.php` script is obsolete.)
+- **Mixed-cycle receipts can collect in Archive** — receipts from a prior run can linger in a person's `Archive/` under a different billing cycle (e.g. January receipts found alongside May during an Emily Tow restore). `MoveBack` moves **everything** in `Archive/` back, so after a restore, verify the receipts belong to the cycle you intend to reprocess; stray off-cycle files should be moved (via Graph API) to their own billing-cycle folder so they are not reprocessed with the wrong cycle.
 
 ## Change history
 
+- 2026-06-29 — `payment_memo` override now also fires on a **bare** `"Transportation:"` AI memo, not just an empty one: new `isBareTranportationMemo()` lets the cardholder's statement Excel (the authoritative source for activity-purpose headings like "Peer meeting:", "Grantee event:") override the AI's generic transportation heading. Fixes wrong headings on Emily Tow May 2026 transit rows. Added the committed `MoveBack` action (+ `collectFilesRecursiveRaw()`) to restore a person's archived receipts into a billing-cycle folder for reprocessing, replacing the throwaway `/tmp/tow_restore_archives.php` script. (rgirish)
 - 2026-06-25 — Statement parsing hardened for Emily Tow's May 2026 Amex xlsx: `loadStatementExcel()` now iterates `getAllSheets()` (4 weekly-period sheets) instead of `getActiveSheet()` and captures the `Receipt` column; `lookupStatementTotalByVendor()` now **sums** all receipt-label-matched rows (14 × $3.00 "Subway Rides" = $42.00) before falling back to description-keyword match — fixes subway totals reading $0/$9.00. Added `extractDocxData()` so `.docx` receipts bypass Talos (Talos 500s on docx), parsing `MM/DD/YY: description` line items into per-entry Excel rows. Added a year guard clamping AI-hallucinated `invoice_date` years (e.g. 1976, 2028) to the current year. Fixed archive-path bug: SharePoint move now uses the actual folder name (`"Emily Tow CC receipts"`) not the normalized name, fixing 404 on archive moves. 5 more vendors found missing from the QB vendor list (client action). (rgirish)
 - 2026-06-23 — `TowFoundationCategories.php` added: AI category values now mapped to exact QB account strings via `mapCategory()`; `"Transportation"` → `"6610 Travel expense"` etc. (19 mappings). QB vendor substring match minimum lowered from 4 to 3 chars with whole-word boundary guard for short needles — fixes `"CVS"` → `"CVS Pharmacy"`, `"MTA"` → `"MTA Metro card"`, prevents `"UPS"` → `"USPS"` false positive. (rgirish)
 - 2026-06-18 — QB vendor matching via local fuzzy match against `TowFoundationVendors.php` (2,994 vendors); AI category prompt updated to return specific types (Dining, Travel, etc.); duplicate receipt detection added (person+date+vendor+amount dedup); `billingCycle` filter parameter added (suffix-match — card-type agnostic); person folder ` CC receipts` suffix stripped so CLASS_MAP/PAYMENT_ACCOUNT_MAP resolve correctly (rgirish)

package/package.json

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