toga-ai 1.0.968 → 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/package.json

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