toga-ai 1.0.984 → 1.0.985

package/knowledge/standalone/apps/claude/workflows/clickup-ticket-workflow.md

@@ -6,7 +6,7 @@ project: Claude Harness
 client: shared
 type: workflow
 status: active
-updated: 2026-10-08
+updated: 2026-10-09
 owners: ["jcardinal"]
 files:
   - claude/skills/start/SKILL.md
@@ -36,7 +36,9 @@ writes, and agents until the session has a ticket. These replaced `/kickoff`, `/
 
 1. **`/start TRUE-1234`** — ticket id only (anything else is blocked). The `ticket-reader` agent
    reads the ticket (apps, clients, task type, pseudocode, comments) off the main thread. Then
-   `/start` checks branches, primes the team KB, and loads PR review feedback if an open PR
+   `/start` builds the repo list from the ticket's Application values, checks only those repos'
+   branches, and offers to create/switch to the ticket branch (see below). It primes the team
+   KB, moves the status `to do` -> `in progress`, and loads PR review feedback if an open PR
    exists (rework: same branch, same PR). If ClickUp can't be read, it stops — no offline mode.
 2. **`/commit`** — commits only this session's files, ticket from the session file, then the
    branch. Never pushes.
@@ -47,12 +49,33 @@ writes, and agents until the session has a ticket. These replaced `/kickoff`, `/
    repo with work, open or update a PR per repo, post a PM comment, set status
    `development finished`.
 
+### Ticket branch at /start
+
+- Application -> repo map lives in `skills/start/SKILL.md` Step 4 (e.g. TOGa Desk ->
+  `toga25-desk`, API2 -> `api2`, Team Knowledge Base -> KB repo only, no branch work). The dev
+  can add or drop repos.
+- `start-helper.js branch-check --repos <a,b>` checks only those repos (match / mismatch /
+  missing). Without `--repos`, the old scan of every repo under the root still runs.
+- For each mismatch Claude asks once "Create/switch to `<T>` in `<repo>` from `<base>`?" (base
+  from `gh repo view <owner/repo> --json defaultBranchRef`). On yes:
+  `start-helper.js create-branch --session <sid> --repo <path> --base <base>` — checks out
+  `origin/<T>` if it exists, else local `<T>`, else creates `<T>` from `origin/<base>` and runs
+  `git push -u origin <T>` (never force). Refuses on uncommitted tracked changes (never
+  stashes), on the KB repo, and when the session ticket is not verified.
+- This is the one branch exception in `rules/common/git-workflow.md`.
+
+### Status flow
+
+`to do` -> `in progress` (`/start`, only from `to do`, never backward) -> `development finished`
+(`/finish`). The `start-gate` guard allows only those two status values.
+
 ### Ticket-write rules
 
 - Writes go only to the session's own ticket — the `start-gate` hook blocks any other task id,
   and blocks task creation, deletion, moves, tags, links, docs, chat, and time tracking.
-- `permissions.ask` makes Claude Code ask the developer before every `clickup_update_task` and
-  `clickup_create_comment`.
+- `permissions.ask` makes Claude Code ask the developer before every `clickup_update_task`
+  (it cannot be scoped to one argument, so the status change asks too). `clickup_create_comment`
+  posts without a prompt.
 - Use only the `clickup` MCP server (`mcp__clickup__clickup_*`). The old read-only
   "claude.ai ClickUP for Dev" server (`mcp__claude_ai_ClickUP_for_Dev__*`) is blocked.
 
@@ -100,7 +123,9 @@ All tested 2026-10-08:
   recorded — Claude never writes it. It auto-checks Has UI Changes when a ticket enters a Dev
   Sprints list; `/finish` keeps it checked only if the session changed UI files (`.jsx .tsx .css
   .scss .less .html`, a React app's `src/`, blox components), else unchecks it.
-- **Branch = bare ticket id**, created by ClickUp. PR base = the repo's default branch (usually
+- **Branch = bare ticket id**, created by ClickUp or by `/start`'s `create-branch`. A branch
+  named with the ticket id should link to the ticket through the GitHub integration — confirm on
+  the first real `create-branch` run. PR base = the repo's default branch (usually
   `_production`, varies) — resolve with `gh repo view <owner/repo> --json defaultBranchRef`.
 - **The KB repo (`toga-tech`) works on `_main`.** No branch check and no PRs there; `/finish`
   still does the ticket check.
@@ -127,6 +152,10 @@ All tested 2026-10-08:
   pushes still ask. (jcardinal)
 - 2026-10-08 — Added big-read/saved-file behavior, `gh auth login` note, and PR summary Action. (jcardinal)
 - 2026-10-08 — Dropped the PR summary Action: `/finish` writes the review summary into the PR description. (jcardinal)
+- 2026-10-09 — `/start` builds the repo list from Application, `branch-check --repos` checks only
+  those, and `create-branch` creates/switches the ticket branch after the dev's yes. (jcardinal)
+- 2026-10-09 — `/start` sets status `to do` -> `in progress`; the gate allows `in progress` and
+  `development finished` only. (jcardinal)
 
 ## Related
 

package/package.json

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

@@ -58,6 +58,11 @@ them switch (`git checkout` / `git switch`) — Claude does **not** switch branc
 either (see *Claude never rewrites code because a branch changed*). Present diffs/patches and
 let the developer commit, PR, and deploy.
 
+**One exception — `/start`'s `create-branch`.** At `/start`, after the developer says yes for
+that repo, Claude may run `start-helper.js create-branch` to create (from the default branch)
+or check out the ticket branch `<TICKET>`. Nothing else: no worktree, no stash, never on a
+repo with uncommitted changes, never force-push. See *Branch naming*.
+
 ## Claude never rewrites code because a branch changed
 
 Many developers work across many projects and switch branches constantly. A change that is
@@ -117,10 +122,15 @@ Never force-push to `_main` under any circumstances.
 ## Branch naming
 
 The branch is the bare ClickUp ticket id — e.g. `TRUE-82600`. No prefix, no description.
-ClickUp creates it. One branch per ticket per repo.
-
-`/start` checks that every repo with work is on the ticket branch. On a mismatch it stops and
-says which repo is on which branch. Claude never switches branches itself.
+ClickUp may create it, or `/start` creates it. One branch per ticket per repo.
+
+`/start` checks that every repo on the ticket (from its Application values) is on the ticket
+branch. On a mismatch it asks once per repo: "Create/switch to `<TICKET>` in `<repo>` from
+`<base>`?" On yes it runs `start-helper.js create-branch` (checks out `origin/<TICKET>` or the
+local branch if one exists, else creates it from the default branch and pushes it with
+`git push -u`, never force). A repo with uncommitted changes is refused — Claude stops and
+says so. This is the only case where Claude creates or switches a branch; otherwise Claude
+never switches branches itself.
 
 The KB/harness repo (`toga-tech`) is the exception: work there goes on `_main`.
 

package/scripts/hooks/start-gate.js

@@ -15,8 +15,9 @@
  * Stages (PreToolUse), from the session file:
  *   none     no file (never ran /start). Block Edit/Write/MultiEdit/NotebookEdit and Agent/Task.
  *            Reads, searches, Bash and MCP reads stay allowed (answering questions is fine).
- *   ticket   state "pending". Only the ticket-read steps: ClickUp reads, the pinned start/ scripts,
- *            gh auth status / gh pr list|view|checks, plain git reads, KB + ~/.claude + temp reads,
+ *   ticket   state "pending". Only the ticket-read steps: ClickUp reads, the pinned start/ scripts
+ *            (incl. `start-helper.js create-branch`, which refuses until verified),
+ *            gh auth status / gh pr list|view|checks / gh repo view, plain git reads, KB + ~/.claude + temp reads,
  *            and an Agent spawn of subagent_type `ticket-reader` only.
  *   primer   state "verified", not primed. Old kickoff stage 2: KB reads, INVENTORY.md / APPS.md
  *            reads, edits under the team repo knowledge/, and read-only knowledge.js commands.
@@ -32,7 +33,8 @@
  * the team repo.
  *
  * ClickUp guard (any stage, any tool name containing "clickup"): an ALLOWLIST. Reads pass.
- * Writes pass only for `mcp__clickup__clickup_update_task` (allowed keys and fields only) and
+ * Writes pass only for `mcp__clickup__clickup_update_task` (allowed keys and fields only; status
+ * only "in progress" or "development finished") and
  * `mcp__clickup__clickup_create_comment` (entity_type "task"), on the session ticket. Everything
  * else is blocked, including every tool of the old "ClickUP for Dev" server. This branch FAILS
  * CLOSED on an internal error; the rest of the gate fails open.
@@ -101,7 +103,8 @@ const OLD_CLICKUP_SERVER_RE = /^claude_ai_ClickUP_for_Dev$/i;
 const CLICKUP_READ_RE = /^(get_.+|search|search_.+|filter_.+|list_.+|find_.+|resolve_assignees)$/;
 const UPDATE_TASK_KEYS = new Set(['task_id', 'workspace_id', 'status', 'name', 'custom_fields']);
 const CUSTOM_FIELD_ITEM_KEYS = new Set(['id', 'value']);
-const DONE_STATUS = 'development finished';
+/* /start sets "in progress" (only from "to do"); /finish sets "development finished". */
+const ALLOWED_STATUSES = new Set(['in progress', 'development finished']);
 const WRITABLE_FIELDS = new Map([
   ['32e9fcd3-6f59-448a-a06e-de52afc87587', 'Application'],
   ['ec15edfd-5920-4c12-a1dc-94ede4a62438', 'Stakeholders'],
@@ -184,7 +187,7 @@ const MSG = {
   alwaysBlocked: (op) => 'ClickUp call blocked: `' + op + '` is not allowed from Claude. Ask the developer to do it in ClickUp.',
   commentEntity: 'ClickUp write blocked: comments may only go on the session ticket (entity_type "task").',
   badKey: (k) => 'ClickUp write blocked: update_task may not set `' + k + '`. Allowed: status, name, custom_fields (Application, Stakeholders, Task Type, Pseudocode, Has UI Changes).',
-  badStatus: 'ClickUp write blocked: the only status Claude may set is "development finished".',
+  badStatus: 'ClickUp write blocked: the only statuses Claude may set are "in progress" (/start) and "development finished" (/finish).',
   hasCodeChanges: 'ClickUp write blocked: never write Has Code Changes — worker2 owns it.',
   badField: (id) => 'ClickUp write blocked: custom field `' + id + '` is not one Claude may write.',
   guardError: 'ClickUp call blocked: the start gate could not check it (internal error). Try again; if it repeats, tell the developer.',
@@ -610,6 +613,7 @@ function isGhRead(words) {
   if (!words.length || words[0].toLowerCase() !== 'gh') return false;
   const a = (words[1] || '').toLowerCase();
   const b = (words[2] || '').toLowerCase();
+  if (a === 'repo' && b === 'view') return !words.slice(3).some((w) => /^(-w|--web)$/i.test(w)); // default branch lookup for create-branch
   return (a === 'auth' && b === 'status') || (a === 'pr' && ['list', 'view', 'checks'].includes(b));
 }
 
@@ -768,7 +772,7 @@ function checkCustomFields(value) {
 
 function checkUpdateTask(ti) {
   for (const k of Object.keys(ti)) if (!UPDATE_TASK_KEYS.has(k)) return MSG.badKey(k);
-  if ('status' in ti && (typeof ti.status !== 'string' || ti.status.trim().toLowerCase() !== DONE_STATUS)) return MSG.badStatus;
+  if ('status' in ti && (typeof ti.status !== 'string' || !ALLOWED_STATUSES.has(ti.status.trim().toLowerCase()))) return MSG.badStatus;
   if ('name' in ti && typeof ti.name !== 'string') return MSG.badKey('name');
   if ('custom_fields' in ti) return checkCustomFields(ti.custom_fields);
   return null;

package/skills/start/SKILL.md

@@ -27,7 +27,7 @@ The hook already checked the id, wrote the session ticket file
    `mcp__clickup__clickup_update_task` (fields: Application, Stakeholders, Task Type,
    Pseudocode, Has UI Changes, `name`, status `development finished`) and
    `mcp__clickup__clickup_create_comment`. The hook blocks every other ClickUp write, and
-   Claude Code asks the developer before each one. /start itself writes nothing to ClickUp.
+   Claude Code asks the developer before each one. /start writes only the status `to do` -> `in progress` (Step 6b).
 
 Trailing text is never permission to skip steps. If a block message appears, do the step it
 names. Do not fight the gate. (Harness work only: `TOGA_START_GATE_DISABLED=1`.)
@@ -93,20 +93,59 @@ customId is not the session ticket, the session file is missing, the internal id
 or the url is not `https://app.clickup.com/...`. On a refusal, show the error and stop. On
 `{ok:true,...}` the gate moves to the primer stage.
 
-## Step 4 — Branch check
-
-```
-node ".../start-helper.js" branch-check --session <sid> --root "$CLAUDE_PROJECT_DIR"
-```
-
-Prints `{matches:[{repo,branch}], mismatches:[{repo,branch,changes}], notInvolved:[...],
-skipped:[...]}`. The KB repo (toga-tech) is skipped — it works on `_main`. A repo on another
-branch with no tracked changes is "not involved", not a problem.
-
-If `mismatches` is not empty, STOP and show a numbered list: repo, current branch, number of
-changed files, expected branch `<T>`. Say: "Switch these repos to `<T>` (ClickUp creates the
-branch), then tell me. Or say 'continue anyway'." Never switch branches yourself. Only on an
-explicit "continue anyway":
+## Step 4 — Ticket repos and branches
+
+1. **Repo list from the ticket's `application` values:**
+
+   | Application | Repo(s) |
+   |---|---|
+   | TOGa Supply | `toga25-supply` (+ `api2` if backend work) |
+   | TOGa Desk | `toga25-desk` |
+   | TOGa IQ | `toga25-iq` |
+   | TOGa Commerce | `toga2-commerce` |
+   | TOGa Blox | `toga25-blox` |
+   | TOGa Platform | `toga2-template` |
+   | API2 | `api2` |
+   | Worker 2.0 | `worker2` |
+   | _underscore | `_underscore` |
+   | Library | `library` |
+   | Worker 1.0 | `worker` |
+   | TOGa Classic 1.0 | `toga` |
+   | Team Knowledge Base | the KB repo only — it works on `_main`, no branch work |
+   | anything else | ask the developer |
+
+   Show the list. The developer can add or drop repos. KB-only ticket → skip the rest of Step 4.
+
+2. **Check only those repos:**
+   ```
+   node ".../start-helper.js" branch-check --session <sid> --root "$CLAUDE_PROJECT_DIR" --repos <a,b>
+   ```
+   Prints `{matches, mismatches:[{repo,branch,changes}], missing, skipped}`. Repos not listed are
+   ignored (other work in them is not this ticket's problem). `missing` = no clone at that path
+   — ask for the local path.
+
+3. **For each repo in `mismatches`, ask once:** "Create/switch to `<T>` in `<repo>` from
+   `<base>`?" Resolve `<base>` with
+   `gh repo view <owner/repo> --json defaultBranchRef -q .defaultBranchRef.name` when gh works
+   (owner/repo from `git -C <repo> remote get-url origin`); else leave `--base` off (origin's
+   default is used). If `changes` > 0, do not offer — STOP and say: "`<repo>` has uncommitted
+   changes on `<branch>`. Commit or move them, then tell me." Never stash.
+
+4. **On yes:**
+   ```
+   node ".../start-helper.js" create-branch --session <sid> --repo "<repo path>" --base <base>
+   ```
+   It checks out `origin/<T>` if it exists, else local `<T>`, else creates `<T>` from
+   `origin/<base>` and pushes it (`git push -u origin <T>`, never force). It refuses on
+   uncommitted tracked changes and on the KB repo. Prints
+   `{ok, repo, branch, base, created, pushed, from}`. On `ok:false`, show `error` and stop.
+   Then run `branch-check --repos` again, fresh, and report what it shows.
+   Branches named with the ticket id link to the ClickUp ticket through the GitHub
+   integration — on the first real run, confirm the link shows on the ticket.
+
+This is the **only** time Claude creates or switches a branch, and only after the developer's
+yes (`rules/common/git-workflow.md`). On no, say: "Switch these repos to `<T>`, then tell me.
+Or say 'continue anyway'." Only on an explicit "continue anyway":
 
 ```
 node ".../start-helper.js" override-branch --session <sid>
@@ -159,6 +198,21 @@ Same method as the old /kickoff. Do it in this main session, no agents.
 
 If `estimate.heavy` is true, suggest dropping repos the ticket does not touch.
 
+## Step 6b — Status to "in progress"
+
+After verify and priming: if the reader's `status` is `to do` (any case), set it — no question:
+
+```
+mcp__clickup__clickup_update_task
+  task_id: "<T>"
+  status: "in progress"
+```
+
+Tell the developer in one line: "Ticket <T> moved to in progress." Any other status (in
+progress, review, rework, development finished, ...) → leave it; never move a ticket backward.
+If ClickUp rejects the status (the list has no "in progress"), say so in one line and skip.
+Status flow: to do -> in progress (/start) -> development finished (/finish).
+
 ## Step 7 — Pseudocode and rework
 
 - **`pseudocode`** not empty -> show it and follow it as the agreed plan. If the work needs to differ,
@@ -179,7 +233,8 @@ Ticket:     <T> — <title>  (<status>, <list>)
 Apps:       <repos>  (core: <core>)
 Clients:    <clients>
 Task type:  <type>
-Branch:     all on <T> | override | mismatches listed
+Status:     <old> -> in progress | unchanged
+Branch:     all on <T> | created/switched: <repos> | override | mismatches listed
 Pseudocode: yes | no
 Rework:     yes (PR #n) | no
 KB loaded:  <doc titles>; gaps: <none | list>

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

@@ -20,14 +20,24 @@
  *   scan            --file <path>                           secret scan: exit 1 + {ok:false,hits:[types]}
  *                                                           on a match, exit 0 + {ok:true} if clean,
  *                                                           exit 2 if the file can't be read
- *   branch-check    --session <sid> --root <dir>            {ok, ticket, matches, mismatches, notInvolved, skipped}
+ *   branch-check    --session <sid> --root <dir> [--repos <a,b>]
+ *                                                           {ok, ticket, matches, mismatches, notInvolved, missing, skipped}
+ *                   --repos: comma list of repo folder names (under --root) or paths. Only those
+ *                   repos are checked (match / mismatch / missing); every other repo is ignored.
+ *   create-branch   --session <sid> --repo <path> [--base <branch>]
+ *                   Checks out the ticket branch (name = the verified session ticket). Order:
+ *                   origin/<T> exists -> check it out (tracking); else local <T> -> check it out;
+ *                   else create <T> from origin/<base> and `git push -u origin <T>` (never force).
+ *                   Refuses on tracked uncommitted changes (never stashes) and on the KB repo.
+ *                   {ok, repo, branch, base, created, pushed, from}
  *   override-branch --session <sid>                         branchOverride -> true
  *   latest-for      --ticket <T> [--max-age-hours 24] [--exclude-session <sid>]
  *                                                           newest verified file for that ticket, or {}
  *   repos-with-work --session <sid> --root <dir>            {ok, ticket, repos:[...]}
  *
  * Exit 0 on success, 1 on error (prints {ok:false, error}). Prunes files older than 30 days on
- * every write. Never pushes, fetches, or changes a branch.
+ * every write. Only create-branch fetches, pushes, or changes a branch — and /start runs it only
+ * after the developer says yes.
  */
 
 const fs = require('fs');
@@ -49,6 +59,8 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
 const MS_PER_HOUR = 60 * 60 * 1000;
 const DEFAULT_REATTACH_HOURS = 24;
 const GIT_TIMEOUT_MS = 20000;
+const GIT_NETWORK_TIMEOUT_MS = 120000;
+const MAX_ERROR_CHARS = 500;
 const TICKET_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
 const KB_REMOTE_RE = /(agilantsolutions|togatech)\/claude(\.git)?\/?$/i;
 const DEFAULT_BRANCH_GUESSES = ['_production', 'main', 'master', '_main'];
@@ -159,6 +171,19 @@ function git(repo, args) {
   }
 }
 
+/* Like git(), but throws an Error carrying git's stderr. Used where the failure reason matters. */
+function gitOrThrow(repo, args, timeout) {
+  try {
+    return execFileSync('git', ['-C', repo].concat(args), {
+      encoding: 'utf8', timeout: timeout || GIT_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+      env: Object.assign({}, process.env, { GIT_TERMINAL_PROMPT: '0' }),
+    }).trim();
+  } catch (e) {
+    const detail = String((e.stderr && e.stderr.toString()) || e.message || e).trim().slice(0, MAX_ERROR_CHARS);
+    throw new Error('git ' + args.join(' ') + ' failed: ' + detail);
+  }
+}
+
 function isRepo(dir) {
   try { return fs.existsSync(path.join(dir, '.git')); } catch (e) { return false; }
 }
@@ -195,10 +220,14 @@ function currentBranch(repo) {
   return b === 'HEAD' ? '(detached)' : b;
 }
 
-function trackedChangeCount(repo) {
+function trackedChanges(repo) {
   const out = git(repo, ['status', '--porcelain', '--untracked-files=no']);
-  if (out === null) return 0;
-  return out ? out.split(/\r?\n/).filter(Boolean).length : 0;
+  if (!out) return [];
+  return out.split(/\r?\n/).filter(Boolean);
+}
+
+function trackedChangeCount(repo) {
+  return trackedChanges(repo).length;
 }
 
 function localBranchFor(repo, ticket) {
@@ -217,6 +246,21 @@ function defaultRemoteBranch(repo) {
   return DEFAULT_BRANCH_GUESSES.find((b) => refExists(repo, 'refs/remotes/origin/' + b)) || null;
 }
 
+/* origin's default branch: origin/HEAD, else "HEAD branch:" from `git remote show origin`. */
+function originDefaultBranch(repo) {
+  const head = git(repo, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+  if (head) return head.replace(/^refs\/remotes\/origin\//, '');
+  let shown = null;
+  try { shown = gitOrThrow(repo, ['remote', 'show', 'origin'], GIT_NETWORK_TIMEOUT_MS); } catch (e) { return null; }
+  const m = shown.match(/HEAD branch:\s*(\S+)/);
+  return m && m[1] !== '(unknown)' ? m[1] : null;
+}
+
+function validBranchName(repo, name) {
+  return typeof name === 'string' && !!name && !name.startsWith('-') &&
+    git(repo, ['check-ref-format', '--branch', name]) !== null;
+}
+
 function aheadCount(repo, base, branch) {
   const n = git(repo, ['rev-list', '--count', base + '..' + branch]);
   return n === null ? null : parseInt(n, 10);
@@ -338,12 +382,35 @@ function cmdLatestFor(args) {
   print(best || {});
 }
 
+/* --repos "a,b,D:/x/c": folder names resolve under root; paths are used as given. */
+function listedRepos(root, list) {
+  return String(list).split(',').map((x) => x.trim()).filter(Boolean)
+    .map((x) => (path.isAbsolute(x) || /[\/\\]/.test(x) ? path.resolve(x) : path.join(path.resolve(root), x)));
+}
+
+/* Listed repos only: each is a match, a mismatch (any other branch, changes or not) or missing. */
+function checkListedRepos(result, repos, ticket) {
+  for (const repo of repos) {
+    if (!isRepo(repo)) { result.missing.push({ repo }); continue; }
+    if (isKbRepo(repo)) { result.skipped.push({ repo, reason: 'KB repo (works on _main)' }); continue; }
+    const branch = currentBranch(repo);
+    if (branch === null) { result.skipped.push({ repo, reason: 'git failed' }); continue; }
+    if (branch.toLowerCase() === ticket.toLowerCase()) { result.matches.push({ repo, branch }); continue; }
+    result.mismatches.push({ repo, branch, changes: trackedChangeCount(repo) });
+  }
+}
+
 function cmdBranchCheck(args) {
   const r = requireSession(args);
   if (!r) return;
   if (typeof args.root !== 'string') return fail('missing --root <dir>');
   const ticket = r.s.ticket;
-  const result = { ok: true, ticket, branchOverride: !!r.s.branchOverride, matches: [], mismatches: [], notInvolved: [], skipped: [] };
+  const result = { ok: true, ticket, branchOverride: !!r.s.branchOverride, matches: [], mismatches: [], notInvolved: [], missing: [], skipped: [] };
+  if (args.repos !== undefined) {
+    if (typeof args.repos !== 'string' || !args.repos.trim()) return fail('--repos needs a comma list of repo names or paths');
+    checkListedRepos(result, listedRepos(args.root, args.repos), ticket);
+    return print(result);
+  }
   for (const repo of reposUnder(args.root)) {
     if (isKbRepo(repo)) { result.skipped.push({ repo, reason: 'KB repo (works on _main)' }); continue; }
     const branch = currentBranch(repo);
@@ -356,6 +423,73 @@ function cmdBranchCheck(args) {
   print(result);
 }
 
+function createBranchError(repo, message, extra) {
+  print(Object.assign({ ok: false, repo, error: message }, extra || {}));
+  process.exitCode = 1;
+}
+
+/* Base for a new branch: --base, else origin's default. */
+function resolveBase(repo, given) {
+  if (given !== undefined) {
+    if (!validBranchName(repo, given)) return { error: 'bad --base branch name' };
+    return { base: given };
+  }
+  const base = originDefaultBranch(repo);
+  return base ? { base } : { error: 'cannot find origin\'s default branch — pass --base <branch>' };
+}
+
+/* origin/<T> first, then local <T>, else create from origin/<base> and push (never force). */
+function checkoutTicket(repo, ticket, base) {
+  const onRemote = refExists(repo, 'refs/remotes/origin/' + ticket);
+  const onLocal = refExists(repo, 'refs/heads/' + ticket);
+  if (onRemote) {
+    if (onLocal) gitOrThrow(repo, ['checkout', ticket]);
+    else gitOrThrow(repo, ['checkout', '-b', ticket, '--track', 'origin/' + ticket]);
+    return { created: false, pushed: false, from: onLocal ? 'local' : 'origin/' + ticket };
+  }
+  if (onLocal) {
+    gitOrThrow(repo, ['checkout', ticket]);
+    return { created: false, pushed: false, from: 'local' };
+  }
+  if (!base.base) return { error: base.error };
+  if (!refExists(repo, 'refs/remotes/origin/' + base.base)) return { error: 'origin/' + base.base + ' does not exist' };
+  gitOrThrow(repo, ['checkout', '--no-track', '-b', ticket, 'origin/' + base.base]);
+  try {
+    gitOrThrow(repo, ['push', '-u', 'origin', ticket], GIT_NETWORK_TIMEOUT_MS);
+  } catch (e) {
+    return { error: 'branch created locally but the push failed: ' + e.message, created: true, pushed: false };
+  }
+  return { created: true, pushed: true, from: 'origin/' + base.base };
+}
+
+function cmdCreateBranch(args) {
+  const r = requireSession(args);
+  if (!r) return;
+  if (r.s.state !== 'verified') return fail('session ticket is not verified — finish /start verify first');
+  const ticket = String(r.s.ticket || '');
+  if (!TICKET_RE.test(ticket)) return fail('bad session ticket');
+  if (typeof args.repo !== 'string' || !args.repo) return fail('missing --repo <path>');
+  const repo = path.resolve(args.repo);
+  if (!isRepo(repo)) return createBranchError(repo, 'not a git repo');
+  if (isKbRepo(repo)) return createBranchError(repo, 'KB repo works on _main — no ticket branch');
+  if (args.base !== undefined && typeof args.base !== 'string') return createBranchError(repo, '--base needs a branch name');
+  if (currentBranch(repo) === ticket) {
+    return print({ ok: true, repo, branch: ticket, base: args.base || null, created: false, pushed: false, from: 'current' });
+  }
+  const dirty = trackedChanges(repo);
+  if (dirty.length) return createBranchError(repo, 'uncommitted tracked changes — commit or move them first (never stashed)', { changes: dirty });
+  try {
+    gitOrThrow(repo, ['fetch', 'origin'], GIT_NETWORK_TIMEOUT_MS);
+  } catch (e) {
+    return createBranchError(repo, e.message);
+  }
+  const base = resolveBase(repo, args.base);
+  let out;
+  try { out = checkoutTicket(repo, ticket, base); } catch (e) { return createBranchError(repo, e.message); }
+  if (out.error) return createBranchError(repo, out.error, out.created ? { branch: ticket, created: true, pushed: false } : null);
+  print(Object.assign({ ok: true, repo, branch: currentBranch(repo), base: base.base || null }, out));
+}
+
 function cmdReposWithWork(args) {
   const r = requireSession(args);
   if (!r) return;
@@ -389,9 +523,10 @@ function main() {
     case 'override-branch': return cmdOverrideBranch(args);
     case 'latest-for': return cmdLatestFor(args);
     case 'repos-with-work': return cmdReposWithWork(args);
+    case 'create-branch': return cmdCreateBranch(args);
     case 'scan': return cmdScan(args);
     default:
-      return fail('usage: start-helper.js <get|verify|branch-check|override-branch|latest-for|repos-with-work|scan> [--flags]');
+      return fail('usage: start-helper.js <get|verify|branch-check|create-branch|override-branch|latest-for|repos-with-work|scan> [--flags]');
   }
 }