toga-ai 1.0.967 → 1.0.969

package/.claude/settings.json

@@ -18,6 +18,15 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/session-files.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PreToolUse": [
@@ -182,6 +191,16 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/session-files.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "SessionStart": [

package/knowledge/1.0/apps/library/INDEX.md

@@ -12,6 +12,7 @@
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | TOGa Refresh 2026 "View Recommended Services" routing — per-device diagnostic `resultCode` decides serviceselection vs techsupport; open when touching that rout |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | Elite bidirectional ticket/attachment sync between TOGA 2 and TOGaDesk (`App_Api_Toga2::syncWithTogadesk`); open for the sync mechanics, watermarks, and Elite-s |
 | [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | 1.0 `App_Email` queued sending + attachment embedding via `Common.EmailsQueued`; open when a queued email loses attachments or when deploying worker/togadesk to |
+| [App_Email SES Sender Identity (every From address must be verified in SES first)](features/email-ses-sender-identity.md) | 1.0 `App_Email` sends through Amazon SES SMTP; any new From address must be a verified SES identity first or SES rejects the send. |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | Branded HTML email base class `App_Email_Template` (header/body/footer); open when building or fixing a 1.0 branded email or its Outlook rendering. |
 | [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | 1.0 `App_Email::send()` side effects (log/queue writes, test-mode recipient rewrite) and how to send a genuinely write-free test; open before writing any 1.0 dr |
 | [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | 1.0 error-reporting into the shared 2.0 Logs DB (`App_Error_Capture::captureException`), mirroring 2.0's Issue/Event; open when adding a 1.0 capture path or deb |

package/knowledge/1.0/apps/library/features/email-ses-sender-identity.md

@@ -0,0 +1,42 @@
+---
+title: App_Email SES Sender Identity (every From address must be verified in SES first)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-10-07
+owners: ["bala"]
+files:
+  - library/app/email.php
+related:
+  - ./email-queue-attachments.md
+  - ./email-test-mode-and-write-free-sends.md
+  - ../../tools/features/legacy-email-notifier.md
+  - ../../test/features/goagilant-to-togatech-email-migration.md
+  - ../../../../clients/compass-canada/profile.md
+---
+
+1.0 `App_Email` sends through Amazon SES SMTP; any new From address must be a verified SES identity first or SES rejects the send. Open before changing a `sendFromEmailAddress` / `fromEmailAddress` to a new address or a customer domain.
+
+## Summary
+
+`App_Email` (`library/app/email.php`) sends via PHPMailer to SES SMTP at `email-smtp.us-west-2.amazonaws.com`, in the **toga-legacy** AWS account, region **us-west-2** (not us-east-1). SES only accepts a From address that is a verified identity in that account and region. The account is out of the SES sandbox, so To/CC recipients need no verification. Only the sender does.
+
+## How it works
+
+- **Domain identity:** `togatech.com` is verified as a whole domain, so any `@togatech.com` From works.
+- **Customer-domain addresses are single EMAIL_ADDRESS identities**, not domains. Verified so far: `techhub@compass-usa.com`, `Techhub.Canada@compass-canada.com`.
+- **Verifying one address:** SES mails a link from `no-reply-aws@amazon.com`, subject "Amazon Web Services – Email Address Verification Request in region US West (Oregon)". The customer's mailbox owner must click it within **24h**. Until then the identity is pending and sends fail.
+- **Alternative:** a domain identity for the customer domain. Needs the customer's IT to add DKIM DNS records. Use it when several addresses on that domain will send.
+- **Order of work:** verify the identity in SES, confirm it shows verified, *then* run the SQL that switches `EmailTemplates.sendFromEmailAddress` / `IntegrationsEmail.fromEmailAddress`. Flipping the data first breaks every send from those templates.
+
+## Gotchas
+
+- **The AWS verification email often lands in the customer's quarantine or spam.** Tell the mailbox owner to look there, and to release it within the 24h window. If it expires, re-send the verification.
+- **A verified customer address is not proof it is used as a sender.** Compass USA vendor PO emails send from `compasssupport@togatech.com` (`Client_Compass.IntegrationsEmail`, 6 rows). `techhub@compass-usa.com` appears there only as To/CC.
+- Apps that cannot run `App_Email::send()` (the tools app) still hit SES with the same rule. See [legacy email notifier](../../tools/features/legacy-email-notifier.md).
+
+## Change history
+- 2026-10-07 — Documented the SES sender-identity rule and customer-address verification flow, after moving the Compass Canada TechHub sender to `Techhub.Canada@compass-canada.com` (bala)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 32 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 33 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 42 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/compass-canada/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-10-05
+updated: 2026-10-07
 owners: [jcardinal, bala, tcox, apeterson, ajean, mhammontree, rgirish]
 files: []
 related:
@@ -43,6 +43,7 @@ related:
   - ../compass-usa/features/saml-sso.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md
+  - ../../1.0/apps/library/features/email-ses-sender-identity.md
 ---
 
 ## Summary
@@ -81,6 +82,19 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   CXML). Prod `Vendors` 4 COMPASS CANADA and 5 AGILANT SOLUTIONS INC have no integration, and the 1.0
   constants for them (`'2'`, `'3'`) do not match prod. PO transmit cron quirks and the OneUptime monitor
   (cron 87): [PO-to-vendor monitor](features/oneuptime-po-transmissions-to-vendors-monitor.md).
+- **TechHub sender address is `Techhub.Canada@compass-canada.com` (prod, 2026-10-07).** Was
+  `TechHubCanada@togatech.com`. Changed on 28 `EmailTemplates.sendFromEmailAddress` rows (EN+FR
+  order / approval / transit / delivered / reminder / auto-cancel) and `IntegrationsEmail` id 1
+  (integration 2, "Grand & Toy - Email") by
+  `dbchanges2/Client_CompassCanada/2026-10-07a - TechHubCanadaFromEmail.sql`. Kept on togatech.com
+  on purpose: Request Submitted (`compasssupport@`), Get Support (`donotreply@`), Forgot Password x2
+  (`noreply@`). It is a single verified SES identity, so any new sender needs SES verification
+  first: [SES sender identity](../../1.0/apps/library/features/email-ses-sender-identity.md).
+  The hardcoded TechHub CC in 4 worker crons had a typo (`TechHub@compass-canada.com`, missing
+  `.Canada`); now `Techhub.Canada@compass-canada.com` in `workflow/2_transmit_mits_purchase_orders_to_vendors.php`
+  (G&T PO email CC), `workflow_beta/2_…`, `compass_email_reminders.php` and
+  `compass_cancel_pending_approval_orders.php` (all under `worker/crons/toga2/compasscanada/`).
+  **Not yet deployed.**
 - **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
   back ASNs. ASN ingestion (email CSV + the auto-created ItemFulfillment chain + bilingual
   in-transit email) is documented in [Grand & Toy ASN Import](features/grand-and-toy-asn-import.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.967",
+  "version": "1.0.969",
   "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/rules/common/git-workflow.md

@@ -113,20 +113,24 @@ Keep the description short (3–5 words). Use hyphens, not underscores.
 
 ## Commit messages
 
-Format: `type: short description`
+Format: `<TICKET>: <Subject>` — the same in every repo. It matches api2's CI check.
 
-Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
+- `TRUE-79868: Use client default tax code when invoice tax code is blank`
+- `TRUE-80112: Add retry limit to NetSuite item sync`
 
-- `feat: add batch order processing worker`
-- `fix: null check on customer email before dispatch`
-- `refactor: extract order validation to dedicated class`
-- `docs: document recursive item fulfillment feature`
-- `test: add regression test for empty batch edge case`
-- `chore: update composer dependencies`
+Rules:
 
-The description is lowercase, present tense, under 72 characters. No period at the end.
+1. **Ticket prefix from the branch name.** ClickUp names the branch (e.g. `TRUE-79868`); the
+   ticket id matches `^[A-Z]+-\d+`. If the branch has no ticket id, ask the developer.
+2. **Subject starts with a capital letter.**
+3. **Imperative mood** — "Use", "Add", "Fix". Not past tense ("Used", "Added", "Fixed", "Updated").
+4. **80 characters max** for the whole subject line.
+5. **No period at the end.**
+6. **Not a single word** — the subject says what the commit does.
 
-If a commit is substantial, add a blank line after the subject and a body paragraph explaining the why.
+If a commit is substantial, add a blank line after the subject and a body explaining the why.
+
+Claude's work is committed with `/commit`, which commits only the files this session changed and writes the session notes into the message body (`Claude-Notes: v1`). Changes made by hand outside Claude may be committed the normal way.
 
 ## What never goes in commits
 

package/scripts/ci/pr-risk.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pr-risk.js — deterministic PR risk score for the TOGA PR summary reviewer.
+ *
+ * The model must NOT pick the risk level. This script does, from git facts only.
+ *
+ * Usage:
+ *   node pr-risk.js --base <sha> --head <sha> --repo <owner/name> [--out risk.json]
+ *
+ * Output JSON:
+ *   { level, reasons[], stats{...}, readFirstCandidates[], manualCommitList[] }
+ *
+ * No dependencies. Read-only git commands only.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+// ---- Thresholds -------------------------------------------------------------
+const HIGH_LINES_THRESHOLD = 800;
+const MEDIUM_LINES_THRESHOLD = 300;
+const MEDIUM_FILES_THRESHOLD = 15;
+const READ_FIRST_LIMIT = 8;
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+
+// ---- Repo / path rules ------------------------------------------------------
+const DB_REPOS = ['dbchanges2', 'dbchanges'];
+const CORE_REPOS = ['_underscore', 'library'];
+// Whole words only (after splitting camelCase and non-letters), so "author" does not match.
+const SENSITIVE_WORDS = new Set([
+    'acl', 'acls', 'auth', 'authn', 'authz', 'authentication', 'authorization', 'authorize',
+    'login', 'logout', 'token', 'tokens', 'saml', 'permission', 'permissions', 'oauth', 'sso',
+    'password', 'credential', 'credentials',
+]);
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+const SQL_FILE_RE = /\.sql$/i;
+const TEST_PATH_RE = /(^|\/)(test|tests|__tests__|spec)(\/|$)|\.(test|spec)\.[^/]+$/i;
+const LOCKFILE_RE = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|composer\.lock|bun\.lockb)$/i;
+const GENERATED_RE = /(^|\/)(dist|build)\/|\.min\.[^/]+$|\.map$|(^|\/)INVENTORY\.md$/i;
+const PACKAGE_MANIFEST_RE = /(^|\/)(package\.json|composer\.json)$/i;
+const CORE_DB_REF_RE = /\b(Core|Forecast|Team)`?\.`?\w/;
+const CLIENT_DB_REF_RE = /\bClient_\w/;
+const NOTES_TRAILER_RE = /^Claude-Notes:\s*v1\s*$/m;
+
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const key = argv[i];
+        if (!key.startsWith('--')) continue;
+        const name = key.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            args[name] = true;
+            continue;
+        }
+        args[name] = next;
+        i++;
+    }
+    return args;
+}
+
+function git(args) {
+    // core.quotePath=false: non-ASCII paths come back as-is, not octal-quoted.
+    return execFileSync('git', ['-c', 'core.quotePath=false'].concat(args), {
+        encoding: 'utf8',
+        maxBuffer: GIT_MAX_BUFFER,
+    });
+}
+
+/** Split a path into lowercase words: camelCase, digits and any non-letter are breaks. */
+function pathWords(path) {
+    return path
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .split(/[^A-Za-z]+/)
+        .filter(Boolean)
+        .map((w) => w.toLowerCase());
+}
+
+function isSensitivePath(path) {
+    return pathWords(path).some((w) => SENSITIVE_WORDS.has(w));
+}
+
+function isTest(path) {
+    return TEST_PATH_RE.test(path);
+}
+
+function isGenerated(path) {
+    return LOCKFILE_RE.test(path) || GENERATED_RE.test(path);
+}
+
+/** Resolve rename notation like "dir/{old => new}/file" or "old => new" to the new path. */
+function resolveRenamePath(raw) {
+    if (!raw.includes('=>')) return raw;
+    const braced = raw.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
+    if (braced) return (braced[1] + braced[3] + braced[4]).replace(/\/\//g, '/');
+    return raw.split(' => ').pop();
+}
+
+/** Per-file line counts. ignoreWhitespace=true uses -w, so CRLF/LF or re-indent churn is not counted. */
+function readFileStats(range, ignoreWhitespace) {
+    const flags = ignoreWhitespace ? ['--numstat', '-M', '-w'] : ['--numstat', '-M'];
+    const out = git(['diff'].concat(flags, [range]));
+    const files = [];
+    for (const line of out.split('\n')) {
+        if (!line.trim()) continue;
+        const [added, deleted, ...rest] = line.split('\t');
+        const path = resolveRenamePath(rest.join('\t'));
+        const isBinary = added === '-' || deleted === '-';
+        const lines = isBinary ? 0 : Number(added) + Number(deleted);
+        files.push({ path, lines });
+    }
+    return files;
+}
+
+function readDeletedPaths(range) {
+    const out = git(['diff', '--name-only', '--diff-filter=D', range]);
+    return out.split('\n').filter(Boolean);
+}
+
+function readAddedLines(range) {
+    const out = git(['diff', '-U0', '-w', '--no-color', range]);
+    return out
+        .split('\n')
+        .filter((line) => line.startsWith('+') && !line.startsWith('+++'))
+        .map((line) => line.slice(1));
+}
+
+function readCommits(base, head) {
+    const out = git(['log', '--no-merges', '--format=%H%x00%B%x1e', `${base}..${head}`]);
+    return out
+        .split('\x1e')
+        .map((chunk) => chunk.replace(/^\s+/, ''))
+        .filter(Boolean)
+        .map((chunk) => {
+            const [sha, body = ''] = chunk.split('\x00');
+            const subject = body.split('\n')[0].trim();
+            return { sha: sha.trim(), subject, hasNotes: NOTES_TRAILER_RE.test(body) };
+        });
+}
+
+function computeRisk({ repoName, files, rawLines, deletedPaths, addedLines, commits }) {
+    const high = [];
+    const medium = [];
+
+    const countedFiles = files.filter((f) => !isTest(f.path) && !isGenerated(f.path));
+    const linesChanged = files.reduce((sum, f) => sum + f.lines, 0);
+    const linesCounted = countedFiles.reduce((sum, f) => sum + f.lines, 0);
+    const notesCommits = commits.filter((c) => c.hasNotes);
+    const manualCommits = commits.filter((c) => !c.hasNotes);
+
+    if (DB_REPOS.includes(repoName) || files.some((f) => SQL_FILE_RE.test(f.path))) {
+        high.push('database change');
+    }
+    if (CORE_REPOS.includes(repoName)) {
+        high.push('edit to shared core — affects every app');
+    }
+    if (files.some((f) => isSensitivePath(f.path))) {
+        high.push('touches login or permissions');
+    }
+    const deletedTests = deletedPaths.filter(isTest);
+    if (deletedTests.length > 0) {
+        high.push(`${deletedTests.length} test file(s) deleted`);
+    }
+    if (addedLines.some((l) => CORE_DB_REF_RE.test(l) && CLIENT_DB_REF_RE.test(l))) {
+        high.push('a query may mix Core and a Client database — they are on different servers in production');
+    }
+    if (linesCounted > HIGH_LINES_THRESHOLD) {
+        high.push(`large change: ${linesCounted} lines (not counting tests and generated files)`);
+    }
+
+    if (linesCounted > MEDIUM_LINES_THRESHOLD && linesCounted <= HIGH_LINES_THRESHOLD) {
+        medium.push(`medium-size change: ${linesCounted} lines (not counting tests and generated files)`);
+    }
+    if (files.some((f) => PACKAGE_MANIFEST_RE.test(f.path) || LOCKFILE_RE.test(f.path))) {
+        medium.push('new or changed package');
+    }
+    if (manualCommits.length > 0) {
+        const noun = manualCommits.length === 1 ? 'commit has' : 'commits have';
+        medium.push(`${manualCommits.length} ${noun} no session notes`);
+    }
+    if (files.length > MEDIUM_FILES_THRESHOLD) {
+        medium.push(`${files.length} files changed`);
+    }
+    const whitespaceOnly = rawLines - linesChanged;
+    if (whitespaceOnly > MEDIUM_LINES_THRESHOLD) {
+        medium.push(`${whitespaceOnly} lines are whitespace or line-ending only (ignored)`);
+    }
+
+    let level = 'LOW';
+    let reasons = [commits.length > 0
+        ? 'small change with session notes on every commit'
+        : 'small change (no commits found in the range)'];
+    if (high.length > 0) {
+        level = 'HIGH';
+        reasons = high.concat(medium);
+    } else if (medium.length > 0) {
+        level = 'MEDIUM';
+        reasons = medium;
+    }
+
+    const readFirstCandidates = countedFiles
+        .slice()
+        .sort((a, b) => b.lines - a.lines || a.path.localeCompare(b.path))
+        .slice(0, READ_FIRST_LIMIT)
+        .map((f) => ({ path: f.path, linesChanged: f.lines }));
+
+    return {
+        level,
+        reasons,
+        stats: {
+            filesChanged: files.length,
+            linesChanged,
+            rawLines,
+            linesChangedExcludingTestsAndGenerated: linesCounted,
+            commits: commits.length,
+            commitsWithNotes: notesCommits.length,
+            manualCommits: manualCommits.length,
+        },
+        readFirstCandidates,
+        manualCommitList: manualCommits.map((c) => ({ sha: c.sha.slice(0, 7), subject: c.subject })),
+    };
+}
+
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.base || !args.head || !args.repo || args.base === true || args.head === true) {
+        process.stderr.write('Usage: node pr-risk.js --base <sha> --head <sha> --repo <owner/name> [--out risk.json]\n');
+        process.exit(2);
+    }
+    if (!SHA_RE.test(String(args.base)) || !SHA_RE.test(String(args.head))) {
+        process.stderr.write('pr-risk.js: --base and --head must be commit shas (7-40 hex characters)\n');
+        process.exit(2);
+    }
+    const repoName = String(args.repo).split('/').pop();
+    const range = `${args.base}...${args.head}`;
+
+    const result = computeRisk({
+        repoName,
+        files: readFileStats(range, true),
+        rawLines: readFileStats(range, false).reduce((sum, f) => sum + f.lines, 0),
+        deletedPaths: readDeletedPaths(range),
+        addedLines: readAddedLines(range),
+        commits: readCommits(args.base, args.head),
+    });
+    result.repo = String(args.repo);
+
+    const json = JSON.stringify(result, null, 2) + '\n';
+    if (args.out && args.out !== true) {
+        fs.writeFileSync(args.out, json);
+    }
+    process.stdout.write(json);
+}
+
+try {
+    main();
+} catch (err) {
+    process.stderr.write(`pr-risk.js failed: ${err.message}\n`);
+    process.exit(1);
+}

package/scripts/hooks/session-files.js

@@ -0,0 +1,144 @@
+'use strict';
+/* session-files.js — remembers which files THIS Claude Code session edited, per git repo.
+ *
+ * PostToolUse (Edit|Write|MultiEdit|NotebookEdit): appends one JSON line to
+ *   <gitdir>/claude-sessions/<sessionId>.jsonl  — read later by skills/commit (commit-helper.js).
+ *   Silent on stdout. No child processes (fires on every edit — must stay fast).
+ * UserPromptSubmit: when the prompt starts with "/commit", prints the session id + transcript
+ *   path so the /commit skill knows which list is its own.
+ *
+ * Never denies, never crashes, always exits 0. Disable: TOGA_SESSION_FILES_DISABLED=1.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const PRUNE_AFTER_DAYS = 14;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const MAX_SESSION_ID_LENGTH = 64;
+const SESSIONS_DIR_NAME = 'claude-sessions';
+const COMMIT_PROMPT_RE = /^\/(?:[\w-]+:)?commit(\s|$)/;
+
+/* A closed pipe (EPIPE) on stdout must never crash the hook. */
+process.stdout.on('error', () => {});
+
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (!raw || !raw.trim()) return null;
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+function safeSessionId(id) {
+  return String(id || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, MAX_SESSION_ID_LENGTH);
+}
+
+/* Walk up from `start` looking for .git. Returns { repoRoot, gitDir } or null. */
+function findRepo(start) {
+  let dir = start;
+  for (;;) {
+    const dotGit = path.join(dir, '.git');
+    let st = null;
+    try { st = fs.statSync(dotGit); } catch (e) { st = null; }
+    if (st && st.isDirectory()) return { repoRoot: dir, gitDir: dotGit };
+    if (st && st.isFile()) {
+      try {
+        const m = fs.readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m) return { repoRoot: dir, gitDir: path.resolve(dir, m[1].trim()) };
+      } catch (e) { /* unreadable .git file — keep walking */ }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function hasHeadFile(gitDir) {
+  try { return fs.statSync(path.join(gitDir, 'HEAD')).isFile(); } catch (e) { return false; }
+}
+
+function readBranch(gitDir) {
+  try {
+    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+    const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+    if (m) return m[1];
+    return head.slice(0, 7);
+  } catch (e) {
+    return null;
+  }
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function pruneOld(dir, keepFile) {
+  const cutoff = Date.now() - PRUNE_AFTER_DAYS * MS_PER_DAY;
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch (e) { return; }
+  for (const name of names) {
+    const full = path.join(dir, name);
+    if (full === keepFile || !name.endsWith('.jsonl')) continue;
+    try {
+      if (fs.statSync(full).mtimeMs < cutoff) fs.unlinkSync(full);
+    } catch (e) { /* another session may have removed it — fine */ }
+  }
+}
+
+function handlePostToolUse(input) {
+  const sessionId = safeSessionId(input.session_id);
+  if (!sessionId) return;
+  const ti = input.tool_input || {};
+  const rawPath = ti.file_path || ti.notebook_path;
+  if (!rawPath) return;
+
+  const filePath = path.resolve(input.cwd || process.cwd(), String(rawPath));
+  const repo = findRepo(path.dirname(filePath));
+  if (!repo) return;
+  if (!hasHeadFile(repo.gitDir)) return; /* not a real git dir — write nothing */
+  if (isInside(filePath, repo.gitDir) || isInside(filePath, path.join(repo.repoRoot, '.git'))) return;
+
+  const sessionsDir = path.join(repo.gitDir, SESSIONS_DIR_NAME);
+  const listFile = path.join(sessionsDir, sessionId + '.jsonl');
+  const isNew = !fs.existsSync(listFile);
+  fs.mkdirSync(sessionsDir, { recursive: true });
+
+  const entry = {
+    ts: new Date().toISOString(),
+    sessionId: String(input.session_id),
+    transcriptPath: input.transcript_path || null,
+    repoRoot: repo.repoRoot,
+    branch: readBranch(repo.gitDir),
+    file: path.relative(repo.repoRoot, filePath).split(path.sep).join('/'),
+    tool: input.tool_name || null,
+  };
+  if (input.agent_id) entry.agentId = input.agent_id;
+  fs.appendFileSync(listFile, JSON.stringify(entry) + '\n');
+
+  if (isNew) pruneOld(sessionsDir, listFile);
+}
+
+function handleUserPromptSubmit(input) {
+  const prompt = String(input.prompt || '').trim();
+  if (!COMMIT_PROMPT_RE.test(prompt)) return;
+  process.stdout.write('TOGA session id: ' + (input.session_id || 'unknown') +
+    ' (transcript: ' + (input.transcript_path || 'unknown') + ')\n');
+}
+
+function main() {
+  if (process.env.TOGA_SESSION_FILES_DISABLED === '1') return;
+  const input = readInput();
+  if (!input) return;
+  if (input.hook_event_name === 'UserPromptSubmit') return handleUserPromptSubmit(input);
+  if (input.hook_event_name === 'PostToolUse') return handlePostToolUse(input);
+}
+
+try {
+  main();
+} catch (e) {
+  /* Never block or break a session over bookkeeping. */
+}
+process.exitCode = 0; /* not process.exit() — let stdout flush */

package/skills/commit/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: commit
+description: Commit ONLY the files this Claude Code session changed, in every repo it touched, and write the session's notes (why the task exists, what was found, approach, turned-down options, who decided) into the commit message so the PR reviewer can build the PR summary from it. Safe when several sessions work on the same branch in the same checkout. Never pushes. Trigger on "/commit", "commit this", "commit my changes".
+---
+
+# /commit — commit this session's files, with the session's notes
+
+Helper: `node "$CLAUDE_PROJECT_DIR/.claude/skills/commit/scripts/commit-helper.js" <command>`
+(below: `helper <command>`). It prints JSON. The edit lists come from the
+`session-files.js` hook, stored in `<repo>/.git/claude-sessions/<sessionId>.jsonl`.
+
+## Step 0 — Rules
+
+- Running `/commit` IS the developer's explicit commit authorization — **for these commits only**.
+- Never push. Never `git add -A` or `git add .`. Never `--no-verify`. Never `--amend`.
+  Never switch branches. Never commit a file the developer did not approve.
+
+## Step 1 — Find your own session id
+
+- Look in context for the line `TOGA session id: <id> (transcript: <path>)` — the hook adds it
+  when the prompt starts with `/commit`. Use that id and transcript path.
+- If it is missing: run `helper sessions`. Show the developer each list (repo, branch, file
+  count, first/last time, first message). Ask which one is theirs. Use its `transcriptPath`.
+
+## Step 2 — See what will be committed
+
+Run `helper status --session=<id>`. For each repo, tell the developer in plain words:
+
+1. **Will commit:** the `toCommit` files.
+2. **Other changed files, not from this session:** the `otherChanged` files (hand edits,
+   lockfiles, generated code, files changed by shell commands). Include them **only if the
+   developer says so**. Note any included ones under "Manual changes".
+3. **Overlap warning** for each `overlaps` file: "`X` was also changed by another session —
+   committing it includes their changes too." Ask before including it.
+4. **Branch mismatch:** `branchMismatch` files were last edited on another branch
+   (`entryBranch`). They are NOT in `toCommit`. If the list is not empty, **stop** for that
+   repo: say which files were edited on which branch, and ask the developer to switch
+   branches themselves.
+5. **Possibly yours from before a resume:** list `sameBranchOtherSessions` (time, file count).
+   If the developer says one is theirs, run `status` with that id too and merge the lists.
+6. **Ticket:** use `ticket` from the branch name. If it is `null`, ask the developer for it.
+
+`alreadyClean` files have no change right now (committed, reverted, or stashed). Do not commit
+them. They stay in the list, so a `git stash pop` brings them back into `toCommit`.
+
+`repos[]` entries with an `error` field could not be read — tell the developer the error.
+
+## Step 3 — Checks before committing
+
+On the files you will commit:
+
+1. `php -l <file>` on every PHP file. If `php` is not on PATH, say so — do not skip silently.
+2. After staging, read `git -C <repo> diff --cached` and look for:
+   - secrets: keys, tokens, passwords, connection strings, `.env` files;
+   - absolute local paths (`C:\`, `D:\`, `/Users/`);
+   - commented-out code.
+3. Confirm the branch is the ticket branch.
+
+Fix what you can. If you cannot, unstage (`git -C <repo> restore --staged -- <files>`), stop,
+and tell the developer.
+
+## Step 4 — Get the developer's own words
+
+Run `helper devwords --transcript=<path>`. Use it to:
+
+- fill "Developer's words" with a short real quote;
+- decide honestly who made each decision. A decision is the **developer's** only if the
+  developer said it or approved it in their own message. Otherwise it is **Claude alone**.
+
+If you still do not know why the task exists, ask the developer once, in one plain question.
+
+## Step 5 — Write the message and commit, per repo
+
+Subject rules (api2 CI checks this; use it in every repo): `<TICKET>: <Subject>` — ticket from
+the branch (`^[A-Z]+-\d+`), subject starts with a capital letter, imperative ("Use", "Add",
+"Fix" — not "Used/Added/Fixed"), max 80 characters, no period at the end, more than one word.
+
+Write the message to a temp file **outside every repo** — the OS temp dir (`$TMPDIR`, `$TEMP`,
+or `os.tmpdir()`), named like `toga-commit-<session id>-<repo name>.txt`. Never inside the repo,
+so it can never be staged. Use this format EXACTLY:
+
+```
+TRUE-79868: Use client default tax code when invoice tax code is blank
+
+Why this exists: <problem + scope in 1-3 plain lines — why the ticket exists, what is and isn't in scope>
+Developer's words: "<short quote of how the developer described the task>"
+Found: <what was found, 1-3 lines>
+Approach: <what this commit does in THIS repo and why, 1-3 lines>
+Turned down: <options considered and rejected, and why — or "none">
+Decisions:
+- <decision> (decided by: developer | Claude alone)
+Manual changes: <files the developer changed by hand and asked to include — or "none">
+
+Claude-Notes: v1
+Claude-Session: <session id>
+```
+
+- Same "Why this exists" and "Developer's words" in every repo of the same ticket.
+  "Approach" and "Decisions" are specific to each repo.
+- 5-15 body lines. Plain everyday words. No jargon. No arrow chains.
+- Small follow-up commit on the same ticket: keep every heading; one line each is fine.
+
+`devwords` already replaces token shapes and `password=...` values with `[redacted]`. Still,
+before you commit, read the finished message and check it for:
+
+- secrets: API keys (`sk-ant-`, `ghp_`, `github_pat_`, `AKIA`), private keys, passwords,
+  tokens, connection strings — anything that looks like one, even `[redacted]` leftovers;
+- absolute local paths (`C:\`, `D:\`, `/Users/`, `/home/`).
+
+Remove or reword anything you find. The message goes into git history for good.
+
+Then, per repo:
+
+1. `git -C <repo> add -- <exact files>`
+2. `git -C <repo> commit -F <temp file>`
+3. Delete the temp file (also when the commit fails).
+
+## Step 6 — After each commit
+
+1. `helper forget --session=<id> --repo=<repo> --files=<committed files, comma-separated>`
+2. Report per repo: short hash, subject, file count.
+3. Say: "Push when ready — /commit never pushes."
+4. Say: changes made by hand outside Claude can still be committed the normal way in VS Code;
+   the PR reviewer will show those as manual changes.

package/skills/commit/scripts/commit-helper.js

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+'use strict';
+/* commit-helper.js — data helper for the /commit skill. No npm deps. Prints JSON.
+ *
+ * Reads the per-session edit lists written by scripts/hooks/session-files.js
+ * (<gitdir>/claude-sessions/<sessionId>.jsonl) and compares them with `git status`.
+ *
+ *   status   --session=<id> [--root=<dir>]
+ *   sessions [--root=<dir>]
+ *   devwords --transcript=<path> [--max=40]
+ *   forget   --session=<id> --repo=<path> --files=a,b   (appends "forget" rows)
+ *
+ * List files are append-only: this helper never rewrites them (the hook may be appending).
+ *
+ * Git is called with execFileSync + argument arrays only (never a shell string).
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SESSIONS_DIR_NAME = 'claude-sessions';
+const MAX_SESSION_ID_LENGTH = 64;
+const DEFAULT_DEVWORDS_MAX = 40;
+const DEVWORDS_TEXT_LIMIT = 500;
+const FIRST_MESSAGE_LIMIT = 120;
+const SHORT_SHA_LENGTH = 7;
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+const TICKET_PATTERN = /(?:^|[^A-Za-z0-9])([A-Z]+-\d+)/;
+const IS_WINDOWS = process.platform === 'win32';
+const TRANSCRIPT_HEAD_BYTES = 256 * 1024; /* `sessions` only needs the first human message */
+const FORGET_TYPE = 'forget';
+const REDACTED = '[redacted]';
+
+/* Token shapes that must never reach git history through "Developer's words". Order matters:
+ * the most specific shapes run first. */
+const SECRET_PATTERNS = [
+  /-----BEGIN [A-Z0-9 ]*KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*KEY-----|$)/g,
+  /sk-ant-[A-Za-z0-9_-]+/g,
+  /\bgh[pousr]_[A-Za-z0-9]+/g,
+  /\bgithub_pat_[A-Za-z0-9_]+/g,
+  /\bAKIA[0-9A-Z]{12,}/g,
+  /\beyJ[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]+){0,2}/g,
+  /\b[0-9a-fA-F]{32,}\b/g,
+];
+const SECRET_ASSIGNMENT_RE = /\b(password|passwd|secret|token|apikey|api_key)(\s*[=:]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+const LONG_RUN_RE = /[A-Za-z0-9+_-]{32,}={0,2}/g;
+
+/* ---------- small utilities ---------- */
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (const a of argv) {
+    const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+    if (m) out[m[1]] = m[2] === undefined ? true : m[2];
+    else out._.push(a);
+  }
+  return out;
+}
+
+function print(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+
+function fail(message) {
+  print({ ok: false, error: message });
+  process.exitCode = 1;
+}
+
+function safeSessionId(id) {
+  return String(id || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, MAX_SESSION_ID_LENGTH);
+}
+
+/* Key used to compare repo-relative paths (Windows file names are case-insensitive). */
+function fileKey(p) {
+  const norm = String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+  return IS_WINDOWS ? norm.toLowerCase() : norm;
+}
+
+function git(repo, args) {
+  return execFileSync('git', ['-C', repo].concat(args), {
+    encoding: 'utf8',
+    maxBuffer: GIT_MAX_BUFFER,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+}
+
+function isRepoDir(dir) {
+  try { return fs.existsSync(path.join(dir, '.git')); } catch (e) { return false; }
+}
+
+function listRepos(root) {
+  const repos = [];
+  if (isRepoDir(root)) repos.push(root);
+  let names = [];
+  try { names = fs.readdirSync(root, { withFileTypes: true }); } catch (e) { names = []; }
+  for (const d of names) {
+    if (!d.isDirectory() || d.name === '.git') continue;
+    const full = path.join(root, d.name);
+    if (isRepoDir(full)) repos.push(full);
+  }
+  return repos;
+}
+
+function gitDirOf(repo) {
+  try { return path.resolve(git(repo, ['rev-parse', '--absolute-git-dir']).trim()); } catch (e) { return null; }
+}
+
+/* Branch name like the hook writes it: refs/heads/ stripped; detached HEAD → short sha. */
+function currentBranch(repo) {
+  try {
+    const ref = git(repo, ['symbolic-ref', '-q', 'HEAD']).trim();
+    if (ref) return ref.replace(/^refs\/heads\//, '');
+  } catch (e) { /* detached HEAD: symbolic-ref exits 1 — fall back to the sha */ }
+  try {
+    return git(repo, ['rev-parse', 'HEAD']).trim().slice(0, SHORT_SHA_LENGTH);
+  } catch (e) {
+    return null;
+  }
+}
+
+function ticketFromBranch(branch) {
+  const m = String(branch || '').match(TICKET_PATTERN);
+  return m ? m[1] : null;
+}
+
+function readJsonl(file) {
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (e) { return []; }
+  return parseJsonlText(raw);
+}
+
+/* List files are append-only (the hook appends while we read — never rewrite them).
+ * Fold rows in ts/file order: a `forget` row drops earlier edit rows for that file;
+ * a later edit row adds the file back. Returns the live edit rows. */
+function foldEntries(rows) {
+  const sorted = rows
+    .map((row, i) => ({ row, i }))
+    .sort((a, b) => String(a.row.ts || '').localeCompare(String(b.row.ts || ''))
+      || fileKey(a.row.file).localeCompare(fileKey(b.row.file))
+      || a.i - b.i)
+    .map((x) => x.row);
+  const live = new Map();
+  for (const row of sorted) {
+    const key = fileKey(row.file);
+    if (row.type === FORGET_TYPE) { live.delete(key); continue; }
+    if (!live.has(key)) live.set(key, []);
+    live.get(key).push(row);
+  }
+  return [...live.values()].flat();
+}
+
+/* Newest edit row per file: Map(fileKey -> entry). */
+function latestByFile(entries) {
+  const latest = new Map();
+  for (const e of entries) {
+    const key = fileKey(e.file);
+    const prev = latest.get(key);
+    if (!prev || String(e.ts || '') >= String(prev.ts || '')) latest.set(key, e);
+  }
+  return latest;
+}
+
+/* All session lists in one repo: Map(fileStem -> live entries[]), already folded. */
+function readSessionLists(gitDir) {
+  const dir = path.join(gitDir, SESSIONS_DIR_NAME);
+  const lists = new Map();
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch (e) { return null; }
+  for (const name of names) {
+    if (!name.endsWith('.jsonl')) continue;
+    const rows = readJsonl(path.join(dir, name)).filter((e) => e && typeof e.file === 'string');
+    lists.set(name.slice(0, -'.jsonl'.length), foldEntries(rows));
+  }
+  return lists;
+}
+
+function lastTs(entries) {
+  return entries.reduce((max, e) => (e.ts && e.ts > max ? e.ts : max), '') || null;
+}
+
+function firstTs(entries) {
+  return entries.reduce((min, e) => (e.ts && (!min || e.ts < min) ? e.ts : min), '') || null;
+}
+
+/* `git status --porcelain=v1 -z` → Map(fileKey -> {file, status}). Renames add both paths. */
+function changedFiles(repo) {
+  const out = git(repo, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+  const parts = out.split('\0');
+  const changed = new Map();
+  for (let i = 0; i < parts.length; i++) {
+    const item = parts[i];
+    if (!item || item.length < 4) continue;
+    const status = item.slice(0, 2);
+    const file = item.slice(3);
+    changed.set(fileKey(file), { file, status });
+    if (status[0] === 'R' || status[0] === 'C' || status[1] === 'R' || status[1] === 'C') {
+      const from = parts[i + 1];
+      i += 1;
+      if (from) changed.set(fileKey(from), { file: from, status: 'R-from' });
+    }
+  }
+  return changed;
+}
+
+function resolveRoot(args) {
+  return path.resolve(String(args.root || process.env.CLAUDE_PROJECT_DIR || process.cwd()));
+}
+
+/* ---------- transcript reading (format is internal to Claude Code — be tolerant) ---------- */
+
+function isNoiseText(text) {
+  const t = text.trim();
+  if (!t) return true;
+  if (t.startsWith('<')) return true; // <system-reminder>, <command-name>, <local-command-stdout>...
+  if (t.startsWith('Caveat:')) return true;
+  if (t.startsWith('[Request interrupted')) return true;
+  if (/^TOGA session id:/.test(t)) return true;
+  return false;
+}
+
+function humanTexts(row) {
+  if (!row || row.type !== 'user') return [];
+  if (row.isMeta === true || row.isSidechain === true || row.toolUseResult !== undefined) return [];
+  const msg = row.message;
+  if (!msg) return [];
+  const content = msg.content;
+  const texts = [];
+  if (typeof content === 'string') {
+    texts.push(content);
+  } else if (Array.isArray(content)) {
+    for (const item of content) {
+      if (item && item.type === 'text' && typeof item.text === 'string') texts.push(item.text);
+    }
+  }
+  return texts
+    .filter((t) => !isNoiseText(t))
+    .map((t) => redactSecrets(t.trim()).slice(0, DEVWORDS_TEXT_LIMIT));
+}
+
+/* Replace token shapes and `password=...`-style values with [redacted]. */
+function redactSecrets(text) {
+  let out = String(text);
+  for (const re of SECRET_PATTERNS) out = out.replace(re, REDACTED);
+  out = out.replace(SECRET_ASSIGNMENT_RE, (m, name, sep) => name + sep + REDACTED);
+  out = out.replace(LONG_RUN_RE, (m) => (/[0-9]/.test(m) && /[A-Za-z]/.test(m) ? REDACTED : m));
+  return out;
+}
+
+function parseJsonlText(raw) {
+  const rows = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch (e) { /* skip a bad or cut-off line */ }
+  }
+  return rows;
+}
+
+/* First human message, reading only the head of the transcript (they can be very large). */
+function readFirstHumanMessage(transcriptPath) {
+  let fd = null;
+  try {
+    fd = fs.openSync(transcriptPath, 'r');
+    const buf = Buffer.alloc(TRANSCRIPT_HEAD_BYTES);
+    const bytes = fs.readSync(fd, buf, 0, TRANSCRIPT_HEAD_BYTES, 0);
+    for (const row of parseJsonlText(buf.toString('utf8', 0, bytes))) {
+      let texts = [];
+      try { texts = humanTexts(row); } catch (e) { texts = []; }
+      if (texts.length) return texts[0].slice(0, FIRST_MESSAGE_LIMIT);
+    }
+    return null;
+  } catch (e) {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch (e) { /* already closed */ }
+    }
+  }
+}
+
+function readDevWords(transcriptPath) {
+  const words = [];
+  for (const row of readJsonl(transcriptPath)) {
+    let texts = [];
+    try { texts = humanTexts(row); } catch (e) { texts = []; }
+    for (const text of texts) words.push({ ts: row.timestamp || null, text });
+  }
+  return words;
+}
+
+/* ---------- commands ---------- */
+
+function cmdStatus(args) {
+  const sessionId = safeSessionId(args.session);
+  if (!sessionId) return fail('missing --session=<id>');
+  const root = resolveRoot(args);
+  const repos = [];
+
+  for (const repo of listRepos(root)) {
+    try {
+      const result = statusForRepo(repo, sessionId);
+      if (result) repos.push(result);
+    } catch (e) {
+      repos.push({ repo, error: String((e && e.message) || e) });
+    }
+  }
+  print({ ok: true, session: sessionId, root, repos });
+}
+
+/* One repo's status for a session, or null when the session has nothing here. Read-only. */
+function statusForRepo(repo, sessionId) {
+  const gitDir = gitDirOf(repo);
+  if (!gitDir) return null;
+  const lists = readSessionLists(gitDir);
+  if (!lists) return null;
+
+  const branch = currentBranch(repo);
+  const changed = changedFiles(repo);
+  const mine = lists.get(sessionId) || [];
+  const others = [...lists.entries()].filter(([id]) => id !== sessionId);
+
+  const anyListKeys = new Set();
+  for (const [, entries] of lists) for (const e of entries) anyListKeys.add(fileKey(e.file));
+
+  /* Judge each file by its LATEST entry. alreadyClean is computed here only — the list
+   * is never rewritten, so a stash/pop or revert does not lose the record. */
+  const toCommit = [];
+  const alreadyClean = [];
+  const branchMismatch = [];
+  for (const [key, latest] of latestByFile(mine)) {
+    const change = changed.get(key);
+    if (!change) { alreadyClean.push(latest.file); continue; }
+    if (latest.branch && branch && latest.branch !== branch) {
+      branchMismatch.push({ file: change.file, status: change.status, entryBranch: latest.branch });
+      continue;
+    }
+    toCommit.push(change.file);
+  }
+
+  const otherChanged = [...changed.entries()]
+    .filter(([key, v]) => !anyListKeys.has(key) && v.status !== 'R-from')
+    .map(([, v]) => ({ file: v.file, status: v.status }));
+
+  const overlaps = [];
+  for (const file of toCommit) {
+    const key = fileKey(file);
+    const by = others
+      .map(([id, entries]) => ({ id, hits: entries.filter((e) => fileKey(e.file) === key) }))
+      .filter((o) => o.hits.length)
+      .map((o) => ({ sessionId: o.id, lastTs: lastTs(o.hits) }));
+    if (by.length) overlaps.push({ file, otherSessions: by });
+  }
+
+  const sameBranchOtherSessions = others
+    .map(([id, entries]) => ({ id, onBranch: entries.filter((e) => e.branch === branch) }))
+    .filter((o) => o.onBranch.length)
+    .map((o) => ({
+      sessionId: o.id,
+      lastTs: lastTs(o.onBranch),
+      fileCount: new Set(o.onBranch.map((e) => fileKey(e.file))).size,
+    }));
+
+  if (!mine.length && !sameBranchOtherSessions.length) return null;
+
+  return {
+    repo,
+    branch,
+    ticket: ticketFromBranch(branch),
+    toCommit,
+    alreadyClean,
+    otherChanged,
+    overlaps,
+    branchMismatch,
+    sameBranchOtherSessions,
+  };
+}
+
+function cmdSessions(args) {
+  const root = resolveRoot(args);
+  const sessions = [];
+  const firstMessageCache = new Map();
+  for (const repo of listRepos(root)) {
+    const gitDir = gitDirOf(repo);
+    if (!gitDir) continue;
+    const lists = readSessionLists(gitDir);
+    if (!lists) continue;
+    for (const [id, entries] of lists) {
+      if (!entries.length) continue; /* every file was forgotten (committed) */
+      const transcript = (entries.find((e) => e.transcriptPath) || {}).transcriptPath || null;
+      let firstMessage = null;
+      if (transcript) {
+        if (!firstMessageCache.has(transcript)) {
+          firstMessageCache.set(transcript, readFirstHumanMessage(transcript));
+        }
+        firstMessage = firstMessageCache.get(transcript);
+      }
+      sessions.push({
+        sessionId: (entries[0] && entries[0].sessionId) || id,
+        repo,
+        branches: [...new Set(entries.map((e) => e.branch).filter(Boolean))],
+        fileCount: new Set(entries.map((e) => fileKey(e.file))).size,
+        firstTs: firstTs(entries),
+        lastTs: lastTs(entries),
+        transcriptPath: transcript,
+        firstMessage,
+      });
+    }
+  }
+  sessions.sort((a, b) => String(b.lastTs).localeCompare(String(a.lastTs)));
+  print({ ok: true, root, sessions });
+}
+
+function cmdDevwords(args) {
+  if (!args.transcript || args.transcript === true) return fail('missing --transcript=<path>');
+  const transcript = path.resolve(String(args.transcript));
+  if (!fs.existsSync(transcript)) return fail('transcript not found: ' + transcript);
+  const max = Math.max(1, parseInt(args.max, 10) || DEFAULT_DEVWORDS_MAX);
+  const words = readDevWords(transcript);
+  let messages = words;
+  let skipped = 0;
+  if (words.length > max) {
+    const head = Math.ceil(max / 2);
+    const tail = max - head;
+    messages = words.slice(0, head).concat(tail ? words.slice(-tail) : []);
+    skipped = words.length - max;
+  }
+  print({ ok: true, transcript, total: words.length, skippedInMiddle: skipped, messages });
+}
+
+function cmdForget(args) {
+  const sessionId = safeSessionId(args.session);
+  if (!sessionId) return fail('missing --session=<id>');
+  if (!args.repo || args.repo === true) return fail('missing --repo=<path>');
+  if (!args.files || args.files === true) return fail('missing --files=a,b');
+  const repo = path.resolve(String(args.repo));
+  const gitDir = gitDirOf(repo);
+  if (!gitDir) return fail('not a git repo: ' + repo);
+  const files = [...new Set(String(args.files).split(',').map((f) => f.trim().replace(/\\/g, '/')).filter(Boolean))];
+  if (!files.length) return fail('missing --files=a,b');
+  const sessionsDir = path.join(gitDir, SESSIONS_DIR_NAME);
+  const listFile = path.join(sessionsDir, sessionId + '.jsonl');
+  /* Append tombstones only — never rewrite the list (the hook may be appending right now). */
+  const ts = new Date().toISOString();
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  fs.appendFileSync(listFile, files.map((file) => JSON.stringify({ type: FORGET_TYPE, file, ts })).join('\n') + '\n');
+  const live = foldEntries(readJsonl(listFile).filter((e) => e && typeof e.file === 'string'));
+  print({
+    ok: true,
+    repo,
+    session: sessionId,
+    forgotten: files,
+    remainingFiles: new Set(live.map((e) => fileKey(e.file))).size,
+  });
+}
+
+const COMMANDS = { status: cmdStatus, sessions: cmdSessions, devwords: cmdDevwords, forget: cmdForget };
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = COMMANDS[args._[0]];
+  if (!cmd) return fail('usage: commit-helper.js <status|sessions|devwords|forget> [--options]');
+  try {
+    cmd(args);
+  } catch (e) {
+    fail(String((e && e.message) || e));
+  }
+}
+
+main();

package/skills/work-ticket/SKILL.md

@@ -141,9 +141,9 @@ For **each repo in the plan's `Repos:` header** that has changes, run inside tha
 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,
+2. **Commit.** Stage only the files the plan changed. Build the commit message exactly as the
+   `/commit` skill's format (`skills/commit/SKILL.md` Step 5: `<TICKET>: <Subject>` subject,
+   the notes body, and the `Claude-Notes: v1` / `Claude-Session:` trailer). **Pre-commit check:** `php -l` passes on changed PHP,
    no commented-out code, no credentials or local paths, branch name correct.
 3. **Push** the branch to origin: `git -C "<repo-path>" push -u origin <TICKET>`.