@yemi33/minions 0.1.1994 → 0.1.1996

package/dashboard/js/settings.js

@@ -87,6 +87,7 @@ async function openSettings() {
       settingsField('Shutdown Timeout', 'set-shutdownTimeout', e.shutdownTimeout || 300000, 'ms', 'Max wait for agents during graceful shutdown') +
       settingsField('Restart Grace Period', 'set-restartGracePeriod', e.restartGracePeriod || 1200000, 'ms', 'Grace period before orphan detection on restart') +
       settingsField('Meeting Round Timeout', 'set-meetingRoundTimeout', e.meetingRoundTimeout || 900000, 'ms', 'Auto-advance meeting round after this') +
+      settingsField('Operator login (used in branch names)', 'set-operatorLogin', e.operatorLogin || '', '', 'Override the human operator login used in user/<loginname>/<wi-id>-<slug> branches. Empty = auto-resolve via gh / git email / OS username (currently resolves to: ' + (e._resolvedOperatorLogin || 'unknown') + ')') +
     '</div>' +
     '<h3 style="font-size:13px;color:var(--blue);margin-bottom:8px">Automation</h3>' +
     '<div style="display:flex;flex-direction:column;gap:6px;margin-bottom:16px">' +
@@ -564,6 +565,7 @@ async function saveSettings() {
       shutdownTimeout: document.getElementById('set-shutdownTimeout').value,
       restartGracePeriod: document.getElementById('set-restartGracePeriod').value,
       meetingRoundTimeout: document.getElementById('set-meetingRoundTimeout').value,
+      operatorLogin: (document.getElementById('set-operatorLogin')?.value ?? '').trim(),
       autoApprovePlans: document.getElementById('set-autoApprovePlans').checked,
       evalLoop: document.getElementById('set-evalLoop').checked,
       autoDecompose: document.getElementById('set-autoDecompose').checked,

package/dashboard.js

@@ -4441,6 +4441,19 @@ const server = http.createServer(async (req, res) => {
         item.meta = { ...body.meta };
       }
       copyWorkItemPrFields(item, body);
+      // W-mpejf0fq000e84d6: pre-compute the canonical branch name at create
+      // time so the persisted WI carries `branch` from the moment it hits
+      // disk. Skip when the caller already supplied a branch, when this is
+      // a shared-branch plan (feature_branch wins), or when the type is a
+      // PR-targeted op (engine reuses the PR's branch).
+      if (!item.branch
+          && item.branchStrategy !== 'shared-branch'
+          && !item.pr_id && !item.prNumber && !item._pr && !item.targetPr && !item.sourcePr) {
+        try {
+          const derived = shared.deriveWorkItemBranchName(item, CONFIG);
+          if (derived) item.branch = derived;
+        } catch (e) { /* identity resolver best-effort; engine will derive on dispatch */ }
+      }
       const createResult = createWorkItemWithDedup(wiPath, item);
       if (!createResult.created) {
         const duplicateId = createResult.duplicateOf || createResult.item?.id;
@@ -7632,6 +7645,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const config = queries.getConfig();
       const routing = safeRead(path.join(MINIONS_DIR, 'routing.md')) || '';
       const engine = { ...shared.ENGINE_DEFAULTS, ...(config.engine || {}) };
+      // W-mpejf0fq000e84d6: surface the auto-resolved operator login so the
+      // Settings UI can render it as the placeholder for the optional
+      // engine.operatorLogin override. Best-effort — never let identity
+      // resolution fail the settings read.
+      try { engine._resolvedOperatorLogin = shared.getOperatorLogin(config); }
+      catch { engine._resolvedOperatorLogin = null; }
       return jsonReply(res, 200, {
         engine,
         claude: settingsClaudeConfig(config),
@@ -7705,6 +7724,18 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
         // String fields
         if (e.worktreeRoot !== undefined) _setEngineConfig('worktreeRoot', String(e.worktreeRoot || D.worktreeRoot));
+        // W-mpejf0fq000e84d6: operator login override. Empty string clears
+        // the override (engine falls back to gh/git/os resolution); any other
+        // value pins the login used in `user/<login>/<wi-id>-<slug>` branches.
+        // Reset the identity-resolver cache so the change takes effect on the
+        // next dispatch instead of after `minions restart`.
+        if (e.operatorLogin !== undefined) {
+          const raw = String(e.operatorLogin || '').trim();
+          if (raw) _setEngineConfig('operatorLogin', raw);
+          else _deleteEngineConfig('operatorLogin');
+          try { require('./engine/operator-identity')._resetOperatorLoginCacheForTest(); }
+          catch { /* identity module missing — safe to ignore */ }
+        }
 
         // ── Runtime fleet (P-7a5c1f8e) ─────────────────────────────────────
         // Empty string clears the override — the dashboard's "Default (CLI
@@ -8427,6 +8458,71 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return;
   }
 
+  // ── QA Runbooks (W-mpeiwz6k0005bf34-a) ──────────────────────────────────────
+  // CRUD over per-project test plans stored at
+  // <MINIONS_DIR>/projects/<name>/runbooks/<id>.json. Pure persistence —
+  // dispatch + run records + UI are deferred to follow-up plan items.
+  function handleQaRunbooksList(req, res) {
+    try {
+      const qaRunbooks = require('./engine/qa-runbooks');
+      const u = new URL(req.url, 'http://x');
+      const project = (u.searchParams.get('project') || '').trim();
+      const items = qaRunbooks.listRunbooks(project || undefined);
+      return jsonReply(res, 200, { items }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  function handleQaRunbooksGet(req, res, match) {
+    try {
+      const qaRunbooks = require('./engine/qa-runbooks');
+      const id = match && match[1] ? decodeURIComponent(match[1]) : '';
+      if (!id) return jsonReply(res, 400, { error: 'id required' }, req);
+      const rec = qaRunbooks.getRunbook(id);
+      if (!rec) return jsonReply(res, 404, { error: `runbook not found: ${id}` }, req);
+      return jsonReply(res, 200, rec, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  async function handleQaRunbooksSave(req, res) {
+    try {
+      const qaRunbooks = require('./engine/qa-runbooks');
+      const body = await readBody(req);
+      const validation = qaRunbooks.validateRunbook(body);
+      if (!validation.ok) {
+        return jsonReply(res, 400, { error: 'invalid runbook', details: validation.errors }, req);
+      }
+      let saved;
+      try { saved = qaRunbooks.saveRunbook(body); }
+      catch (e) {
+        // Cross-project collision is a client error (409), not a server error.
+        if (/already exists under project/.test(e.message)) {
+          return jsonReply(res, 409, { error: e.message }, req);
+        }
+        throw e;
+      }
+      return jsonReply(res, 200, saved, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  function handleQaRunbooksDelete(req, res, match) {
+    try {
+      const qaRunbooks = require('./engine/qa-runbooks');
+      const id = match && match[1] ? decodeURIComponent(match[1]) : '';
+      if (!id) return jsonReply(res, 400, { error: 'id required' }, req);
+      const removed = qaRunbooks.deleteRunbook(id);
+      if (!removed) return jsonReply(res, 404, { error: `runbook not found: ${id}` }, req);
+      return jsonReply(res, 200, { ok: true, id }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   // ── QA runs + artifact serving (W-mpeiwz6k0005bf34-b) ──────────────────────
   // Lifecycle for QA validation runs lives in engine/qa-runs.js. These three
   // handlers expose: list (with optional ?limit= + ?status= filters), single-
@@ -8645,6 +8741,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       _trackSseClient(_hotReloadClients, req, res);
     }},
 
+    // QA Runbooks (W-mpeiwz6k0005bf34-a) — per-project test plans stored at
+    // <MINIONS_DIR>/projects/<name>/runbooks/<id>.json. Pure persistence —
+    // dispatch + run records + UI live in follow-up plan items.
+    { method: 'GET',  path: '/api/qa/runbooks', desc: 'List QA runbooks across all projects. Optional ?project= filter.', handler: handleQaRunbooksList },
+    { method: 'GET',  path: /^\/api\/qa\/runbooks\/([^/?]+)$/, template: '/api/qa/runbooks/<id>', desc: 'Get a single QA runbook by id.', handler: handleQaRunbooksGet },
+    { method: 'POST', path: '/api/qa/runbooks', desc: 'Create or update a QA runbook. Body: full runbook spec (id, name, project, targetName, steps[], expectedArtifacts[]).', handler: handleQaRunbooksSave },
+    { method: 'DELETE', path: /^\/api\/qa\/runbooks\/([^/?]+)$/, template: '/api/qa/runbooks/<id>', desc: 'Delete a QA runbook by id.', handler: handleQaRunbooksDelete },
+
     // Work items
     { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?, oneShot?, meta?', handler: handleWorkItemsCreate },
     { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?, references?, acceptanceCriteria?', handler: handleWorkItemsUpdate },

package/docs/qa-runbooks.md

@@ -0,0 +1,104 @@
+# QA Runbooks
+
+> Plan item **W-mpeiwz6k0005bf34-a** — schema + persistence + CRUD endpoints.
+> Run dispatch, run records, and UI live in follow-up items.
+
+## Storage location
+
+Runbooks are per-project test plans. Each runbook is a single JSON file at:
+
+```
+<MINIONS_DIR>/projects/<project-name>/runbooks/<runbook-id>.json
+```
+
+This mirrors the `projects/<name>/pull-requests.json` precedent — anything
+scoped to a single project lives under its `projects/<name>/` state dir
+rather than a root-level `runbooks/` directory. Two reasons:
+
+1. **Lifecycle parity with the project.** When a project is removed via
+   `engine/projects.js removeProject`, its `projects/<name>/` dir is
+   archived as one unit. Co-locating runbooks under that dir means they
+   travel with the project rather than dangling in a global `runbooks/`
+   that has no relationship to the project being removed.
+2. **No central collision with multi-project setups.** Two projects can
+   pick the same human-readable runbook name without stepping on each
+   other on disk. The runbook **id** is still globally unique (kebab-case,
+   ≤ 64 chars) so single-id lookups don't need a project hint.
+
+## Schema
+
+```jsonc
+{
+  "id": "kebab-case-id",           // required, kebab-case, ≤ 64 chars, globally unique
+  "name": "Human-readable name",   // required, ≤ 200 chars
+  "project": "project-name",       // required, the owning project (matches projects/<name>/)
+  "targetName": "string",          // required, the system under test (e.g. process name, URL, target)
+  "steps": [                       // ≤ 20 steps
+    {
+      "description": "Step 1 description",   // required, ≤ 500 chars
+      "command": "optional shell command"    // optional, ≤ 2000 chars
+    }
+  ],
+  "expectedArtifacts": [           // ≤ 20 artifacts
+    {
+      "type": "screenshot",        // required, one of: screenshot | video | log | other
+      "label": "Login page",       // required, ≤ 200 chars
+      "path": "screenshots/login.png"  // optional hint, ≤ 500 chars
+    }
+  ],
+  "createdAt": "2026-05-20T20:42:00.000Z",  // ISO-8601, set on first save
+  "updatedAt": "2026-05-20T20:42:00.000Z"   // ISO-8601, set on every save
+}
+```
+
+`id`, `createdAt`, and `updatedAt` are managed by `saveRunbook`. The id
+must match `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`.
+
+## API
+
+| Method | Path                          | Notes                                                     |
+| ------ | ----------------------------- | --------------------------------------------------------- |
+| GET    | `/api/qa/runbooks`            | List all. Optional `?project=<name>` filter.              |
+| GET    | `/api/qa/runbooks/<id>`       | Fetch a single runbook by globally-unique id.             |
+| POST   | `/api/qa/runbooks`            | Create or update. Body is the full runbook spec.          |
+| DELETE | `/api/qa/runbooks/<id>`       | Remove a runbook. Returns 404 when not found.             |
+
+Responses:
+
+- `200 { items: [...] }` — list
+- `200 { ...runbook }` — get/save
+- `200 { ok: true, id }` — delete
+- `400 { error, details? }` — validation failure (`details` is the
+  `validateRunbook` error array)
+- `404 { error }` — not found
+- `409 { error }` — cross-project id collision; `deleteRunbook(id)` then
+  retry with the new project
+
+## Module
+
+`engine/qa-runbooks.js` exports:
+
+```js
+{
+  ARTIFACT_TYPES,       // ['screenshot','video','log','other']
+  LIMITS,               // schema bounds (idMax, nameMax, stepsMax, ...)
+  validateRunbook(spec) // → { ok: boolean, errors: string[] } — never throws
+  listRunbooks(project?) // → array of parsed runbook records
+  getRunbook(id)        // → record | null (scans all projects by id)
+  saveRunbook(spec)     // upsert; throws on validation or cross-project collision
+  deleteRunbook(id)     // → boolean; locks the runbook's file before unlink
+}
+```
+
+All writes use `mutateJsonFileLocked` per the repo convention. Deletes use
+`withFileLock` directly to coordinate with concurrent saves before the
+unlink (so an in-progress `saveRunbook` rename can't race with the
+unlink).
+
+## Out of scope (deferred items)
+
+This module deliberately does NOT:
+
+- Spawn a QA agent or dispatch a run (W-mpeiwz6k0005bf34-c).
+- Persist run records or artifacts (W-mpeiwz6k0005bf34-b).
+- Render any UI (W-mpeiwz6k0005bf34-d).

package/engine/ado.js

@@ -378,6 +378,15 @@ function applyAdoPrMetadata(pr, prData) {
     updated = true;
   }
 
+  // W-mpej044m00076d63: backfill `pr.created` from ADO's real creation
+  // timestamp. lifecycle.js attach paths omit `created` so this poll is the
+  // single source of truth for fresh records, and historical records missing
+  // `created` get backfilled the next time they're polled. Idempotent.
+  if (!pr.created && prData.creationDate) {
+    pr.created = prData.creationDate;
+    updated = true;
+  }
+
   return updated;
 }
 
@@ -720,6 +729,18 @@ async function pollPrStatus(config) {
       pr.status = newStatus;
       updated = true;
 
+      // W-mpej044m00076d63: persist platform close/merge timestamps on the
+      // normal-poll status flip. ADO does not split mergedAt vs closedAt at
+      // the API level — `closedDate` is set whenever a PR moves out of
+      // `active` (whether via merge or abandon). Mirror that into our own
+      // fields with the standard idempotency guard.
+      if (newStatus === PR_STATUS.MERGED && !pr.mergedAt) {
+        pr.mergedAt = prData.closedDate || ts();
+      }
+      if ((newStatus === PR_STATUS.ABANDONED || newStatus === PR_STATUS.CLOSED) && !pr.closedAt) {
+        pr.closedAt = prData.closedDate || ts();
+      }
+
       if (newStatus === PR_STATUS.MERGED || newStatus === PR_STATUS.ABANDONED) {
         if (pr.reviewStatus === 'waiting') {
           pr.reviewStatus = newStatus === PR_STATUS.MERGED ? 'approved' : 'pending';
@@ -1070,7 +1091,7 @@ async function pollPrHumanComments(config) {
     const threadsData = await adoFetch(threadsUrl, token);
     const threads = threadsData.value || [];
 
-    const cutoffStr = pr.humanFeedback?.lastProcessedCommentDate || pr.created || '1970-01-01';
+    const cutoffStr = pr.humanFeedback?.lastProcessedCommentDate || pr.created || pr._attachedAt || '1970-01-01';
     const cutoffMs = new Date(cutoffStr).getTime() || 0;
 
     // Collect ALL human comments on the PR for full context. `allCommentDates`

package/engine/github.js

@@ -661,6 +661,16 @@ async function pollPrStatus(config) {
     else if (prData.state === 'closed') newStatus = PR_STATUS.ABANDONED;
     else if (prData.state === 'open') newStatus = PR_STATUS.ACTIVE;
 
+    // W-mpej044m00076d63: backfill `pr.created` from the platform's real
+    // creation timestamp. lifecycle.js attach paths deliberately omit
+    // `created` so this poll is the single source of truth — and historical
+    // records that pre-date the fix get backfilled the next time they're
+    // polled. Idempotent: only writes when missing.
+    if (!pr.created && prData.created_at) {
+      pr.created = prData.created_at;
+      updated = true;
+    }
+
     // Track head SHA changes to detect new pushes (used for review re-dispatch gating)
     if (prData.head?.sha && pr.headSha !== prData.head.sha) {
       pr.headSha = prData.head.sha;
@@ -745,6 +755,17 @@ async function pollPrStatus(config) {
       pr.status = newStatus;
       updated = true;
 
+      // W-mpej044m00076d63: persist platform close/merge timestamps on the
+      // normal-poll status flip (previously only the abandoned-reconciliation
+      // path at ~line 1489 set mergedAt). Idempotency guard prevents a later
+      // reconciliation pass from overwriting an earlier-known value.
+      if (newStatus === PR_STATUS.MERGED && !pr.mergedAt) {
+        pr.mergedAt = prData.merged_at || prData.closed_at || ts();
+      }
+      if ((newStatus === PR_STATUS.ABANDONED || newStatus === PR_STATUS.CLOSED) && !pr.closedAt) {
+        pr.closedAt = prData.closed_at || ts();
+      }
+
       if (newStatus === PR_STATUS.MERGED || newStatus === PR_STATUS.ABANDONED) {
         // Resolve stale 'waiting' review status — won't be polled again after this
         if (pr.reviewStatus === 'waiting') {
@@ -961,7 +982,7 @@ async function pollPrHumanComments(config) {
     // fixture already populated the field.
     _backfillViewerDidAuthor(allComments, viewerLogin);
 
-    const cutoffStr = pr.humanFeedback?.lastProcessedCommentDate || pr.created || '1970-01-01';
+    const cutoffStr = pr.humanFeedback?.lastProcessedCommentDate || pr.created || pr._attachedAt || '1970-01-01';
     const cutoffMs = new Date(cutoffStr).getTime() || 0;
 
     // Collect comments that should advance the cutoff separately from comments

package/engine/lifecycle.js

@@ -907,7 +907,11 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
       branch: meta?.branch || '',
       reviewStatus: 'pending',
       status: PR_STATUS.ACTIVE,
-      created: ts(),
+      // W-mpej044m00076d63: do NOT seed `created` with ts() (engine discovery time).
+      // The next GitHub/ADO poll backfills `pr.created` from the platform's real
+      // creation timestamp; `_attachedAt` is preserved as a fallback for downstream
+      // cutoffs (e.g. comment-poll cutoffStr) that need any timestamp at all.
+      _attachedAt: ts(),
       url: prUrl,
       prdItems: meta?.item?.id ? [meta.item.id] : [],
       sourcePlan: meta?.item?.sourcePlan || '',
@@ -1221,7 +1225,9 @@ function _attachFoundPrToWi(found, meta, agentId, resultSummary, config) {
     branch: meta.branch || '',
     reviewStatus: 'pending',
     status: PR_STATUS.ACTIVE,
-    created: ts(),
+    // W-mpej044m00076d63: omit `created` — the next poll backfills from the
+    // platform's real createdAt. `_attachedAt` is the discovery-time fallback.
+    _attachedAt: ts(),
     url: found.url,
     prdItems: [meta.item.id],
     sourcePlan: meta.item?.sourcePlan || '',

package/engine/operator-identity.js

@@ -0,0 +1,104 @@
+// engine/operator-identity.js — W-mpejf0fq000e84d6
+//
+// Resolve the human operator's platform login for branch naming and other
+// dispatch-time identity needs. The convention is documented in CLAUDE.md
+// ("Branch naming convention") and shared with agents via playbook context.
+//
+// Resolution chain (first non-empty wins, cached at module scope):
+//   1. `config.engine.operatorLogin` — explicit override from the Settings UI
+//   2. `gh api user --jq .login`     — works in any GitHub-authed install
+//   3. `git config user.email`        localpart (`user@host` → `user`)
+//   4. `os.userInfo().username`       — last-resort fallback
+//   5. literal string `'unknown'`     — if all four fail
+//
+// The resolved value is cached in module state. The cache is intentionally
+// process-lifetime: `minions restart` re-resolves; the per-tick dispatch hot
+// path does not. Test helpers expose cache reset + exec/os.username injection
+// so unit tests stay hermetic.
+
+const { execSync } = require('child_process');
+const os = require('os');
+
+let _cached = null;
+
+// Test seams. The default impls shell out; tests inject pure functions.
+let _execImpl = (cmd) => {
+  try {
+    return String(execSync(cmd, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    })).trim();
+  } catch {
+    return '';
+  }
+};
+
+let _osUsernameOverride = null; // null = call real os.userInfo()
+
+function _osUsername() {
+  if (_osUsernameOverride !== null) return _osUsernameOverride;
+  try {
+    const u = os.userInfo().username;
+    return u ? String(u) : '';
+  } catch {
+    return '';
+  }
+}
+
+function resolveOperatorLogin(config, { force = false } = {}) {
+  if (!force && _cached) return _cached;
+
+  // 1. Explicit override
+  const override = config?.engine?.operatorLogin;
+  if (override && typeof override === 'string' && override.trim()) {
+    _cached = override.trim();
+    return _cached;
+  }
+
+  // 2. gh CLI
+  const ghLogin = _execImpl('gh api user --jq .login');
+  if (ghLogin) { _cached = ghLogin; return _cached; }
+
+  // 3. git email localpart
+  const email = _execImpl('git config user.email');
+  if (email) {
+    const local = String(email).split('@')[0].trim();
+    if (local) { _cached = local; return _cached; }
+  }
+
+  // 4. OS username
+  const user = _osUsername();
+  if (user) { _cached = user; return _cached; }
+
+  // 5. Last-resort sentinel
+  _cached = 'unknown';
+  return _cached;
+}
+
+// ── Test helpers (not part of the public API) ────────────────────────────────
+
+function _resetOperatorLoginCacheForTest() { _cached = null; }
+function _setExecImplForTest(fn) { _execImpl = typeof fn === 'function' ? fn : _execImpl; }
+function _resetExecImplForTest() {
+  _execImpl = (cmd) => {
+    try {
+      return String(execSync(cmd, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5000,
+      })).trim();
+    } catch {
+      return '';
+    }
+  };
+}
+function _setOsUsernameForTest(value) { _osUsernameOverride = value; }
+
+module.exports = {
+  resolveOperatorLogin,
+  _resetOperatorLoginCacheForTest,
+  _setExecImplForTest,
+  _resetExecImplForTest,
+  _setOsUsernameForTest,
+};

package/engine/qa-runbooks.js

@@ -0,0 +1,328 @@
+/**
+ * engine/qa-runbooks.js — W-mpeiwz6k0005bf34-a
+ *
+ * Per-project QA runbook persistence + CRUD helpers. Runbooks are test plans
+ * that travel with a project entry, mirroring the
+ * projects/<name>/pull-requests.json precedent. Each runbook is one JSON file
+ * at <MINIONS_DIR>/projects/<project>/runbooks/<id>.json.
+ *
+ * Pure persistence + validation only — this module does NOT spawn agents,
+ * dispatch runs, or touch UI. The dispatch endpoint, run records, and QA UI
+ * are intentionally deferred to follow-up plan items.
+ *
+ * All writes go through mutateJsonFileLocked per the repo convention. The id
+ * field is globally unique across projects (kebab-case, ≤64 chars) so reads
+ * by id can locate the file without the caller knowing the project.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+
+const RUNBOOKS_DIR = 'runbooks';
+
+const _KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// Mirrors shared.PROJECT_NAME_RE — kept local to avoid a require cycle and to
+// keep this module self-contained for path-traversal hardening (review feedback
+// on PR #2694: id/project params previously flowed into path.join without
+// validation, so `..%2F..%2F..%2Fconfig` could read MINIONS_DIR/config.json
+// and DELETE could wipe dispatch.json).
+const _PROJECT_NAME_RE = /^[a-zA-Z0-9_\-]{1,64}$/;
+
+const ARTIFACT_TYPES = ['screenshot', 'video', 'log', 'other'];
+
+const LIMITS = {
+  idMax: 64,
+  nameMax: 200,
+  targetNameMax: 200,
+  stepDescriptionMax: 500,
+  stepCommandMax: 2000,
+  artifactLabelMax: 200,
+  artifactPathMax: 500,
+  stepsMax: 20,
+  artifactsMax: 20,
+};
+
+function _projectsDir() {
+  return path.join(shared.MINIONS_DIR, 'projects');
+}
+
+function _runbooksDir(projectName) {
+  return path.join(_projectsDir(), projectName, RUNBOOKS_DIR);
+}
+
+function _runbookPath(projectName, id) {
+  return path.join(_runbooksDir(projectName), id + '.json');
+}
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+// Guards against path traversal at the module boundary. Mirrors the validation
+// saveRunbook already applies via validateRunbook(). Reject anything that isn't
+// a safe kebab-case id ≤ idMax chars so it can never reach path.join().
+function _isSafeId(id) {
+  return _isNonEmptyString(id) && id.length <= LIMITS.idMax && _KEBAB_RE.test(id);
+}
+
+// Guards against path traversal via the project segment. Project directory
+// names on disk follow shared.PROJECT_NAME_RE — anything outside that set
+// (path separators, `..`, null bytes, whitespace) cannot be a real project.
+function _isSafeProjectName(name) {
+  return _isNonEmptyString(name) && _PROJECT_NAME_RE.test(name);
+}
+
+/**
+ * Validate a runbook spec. Returns { ok: boolean, errors: string[] }.
+ * Never throws.
+ */
+function validateRunbook(spec) {
+  const errors = [];
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+    return { ok: false, errors: ['spec must be a plain object'] };
+  }
+
+  if (!_isNonEmptyString(spec.id)) {
+    errors.push('id is required (non-empty string)');
+  } else {
+    if (spec.id.length > LIMITS.idMax) errors.push('id exceeds ' + LIMITS.idMax + ' chars');
+    if (!_KEBAB_RE.test(spec.id)) errors.push('id must be kebab-case (a-z, 0-9, hyphens; no leading/trailing hyphen)');
+  }
+
+  if (!_isNonEmptyString(spec.name)) {
+    errors.push('name is required (non-empty string)');
+  } else if (spec.name.length > LIMITS.nameMax) {
+    errors.push('name exceeds ' + LIMITS.nameMax + ' chars');
+  }
+
+  if (!_isNonEmptyString(spec.project)) {
+    errors.push('project is required (non-empty string)');
+  } else if (!_PROJECT_NAME_RE.test(spec.project)) {
+    // Reject path-traversal / illegal project names at the schema layer so
+    // they never reach path.join in saveRunbook (review feedback on PR #2694:
+    // POST /api/qa/runbooks with project="../engine" previously wrote arbitrary
+    // JSON outside MINIONS_DIR).
+    errors.push('project must match ' + _PROJECT_NAME_RE.source + ' (alphanumerics, underscore, hyphen; 1-64 chars)');
+  }
+
+  if (!_isNonEmptyString(spec.targetName)) {
+    errors.push('targetName is required (non-empty string)');
+  } else if (spec.targetName.length > LIMITS.targetNameMax) {
+    errors.push('targetName exceeds ' + LIMITS.targetNameMax + ' chars');
+  }
+
+  if (!Array.isArray(spec.steps)) {
+    errors.push('steps must be an array');
+  } else {
+    if (spec.steps.length > LIMITS.stepsMax) {
+      errors.push('steps exceeds max of ' + LIMITS.stepsMax);
+    }
+    for (let i = 0; i < spec.steps.length; i++) {
+      const s = spec.steps[i];
+      if (!s || typeof s !== 'object' || Array.isArray(s)) {
+        errors.push('steps[' + i + '] must be an object');
+        continue;
+      }
+      if (!_isNonEmptyString(s.description)) {
+        errors.push('steps[' + i + '].description is required (non-empty string)');
+      } else if (s.description.length > LIMITS.stepDescriptionMax) {
+        errors.push('steps[' + i + '].description exceeds ' + LIMITS.stepDescriptionMax + ' chars');
+      }
+      if (s.command !== undefined && s.command !== null) {
+        if (typeof s.command !== 'string') {
+          errors.push('steps[' + i + '].command must be a string when present');
+        } else if (s.command.length > LIMITS.stepCommandMax) {
+          errors.push('steps[' + i + '].command exceeds ' + LIMITS.stepCommandMax + ' chars');
+        }
+      }
+    }
+  }
+
+  if (!Array.isArray(spec.expectedArtifacts)) {
+    errors.push('expectedArtifacts must be an array');
+  } else {
+    if (spec.expectedArtifacts.length > LIMITS.artifactsMax) {
+      errors.push('expectedArtifacts exceeds max of ' + LIMITS.artifactsMax);
+    }
+    for (let i = 0; i < spec.expectedArtifacts.length; i++) {
+      const a = spec.expectedArtifacts[i];
+      if (!a || typeof a !== 'object' || Array.isArray(a)) {
+        errors.push('expectedArtifacts[' + i + '] must be an object');
+        continue;
+      }
+      if (!_isNonEmptyString(a.type) || !ARTIFACT_TYPES.includes(a.type)) {
+        errors.push('expectedArtifacts[' + i + '].type must be one of: ' + ARTIFACT_TYPES.join(', '));
+      }
+      if (!_isNonEmptyString(a.label)) {
+        errors.push('expectedArtifacts[' + i + '].label is required (non-empty string)');
+      } else if (a.label.length > LIMITS.artifactLabelMax) {
+        errors.push('expectedArtifacts[' + i + '].label exceeds ' + LIMITS.artifactLabelMax + ' chars');
+      }
+      if (a.path !== undefined && a.path !== null) {
+        if (typeof a.path !== 'string') {
+          errors.push('expectedArtifacts[' + i + '].path must be a string when present');
+        } else if (a.path.length > LIMITS.artifactPathMax) {
+          errors.push('expectedArtifacts[' + i + '].path exceeds ' + LIMITS.artifactPathMax + ' chars');
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function _readRunbookFile(filePath) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf8'); }
+  catch (_e) { return null; }
+  try { return JSON.parse(raw); }
+  catch (_e) { return null; }
+}
+
+function _listProjectNames() {
+  const dir = _projectsDir();
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (_e) { return []; }
+  return entries.filter(e => e.isDirectory()).map(e => e.name);
+}
+
+/**
+ * List runbooks across all projects, or filtered to a single project. Each
+ * returned record is the parsed file contents (already includes id + project
+ * + timestamps).
+ */
+function listRunbooks(project) {
+  let projects;
+  if (project === undefined || project === null || project === '') {
+    projects = _listProjectNames();
+  } else {
+    // Hardened: reject traversal/illegal project names instead of letting them
+    // flow into path.join (review feedback on PR #2694).
+    if (!_isSafeProjectName(project)) return [];
+    projects = [project];
+  }
+  const out = [];
+  for (const name of projects) {
+    const dir = _runbooksDir(name);
+    let files;
+    try { files = fs.readdirSync(dir); }
+    catch (_e) { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue;
+      const parsed = _readRunbookFile(path.join(dir, f));
+      if (parsed && typeof parsed === 'object') out.push(parsed);
+    }
+  }
+  return out;
+}
+
+/**
+ * Find a runbook by globally-unique id. Returns the parsed record or null.
+ */
+function getRunbook(id) {
+  // Hardened: reject traversal ids before they can reach path.join + existsSync
+  // (review feedback on PR #2694).
+  if (!_isSafeId(id)) return null;
+  for (const name of _listProjectNames()) {
+    const filePath = _runbookPath(name, id);
+    if (fs.existsSync(filePath)) {
+      return _readRunbookFile(filePath);
+    }
+  }
+  return null;
+}
+
+/**
+ * Locate the project that currently owns id, or null if not present.
+ */
+function _findOwningProject(id) {
+  for (const name of _listProjectNames()) {
+    if (fs.existsSync(_runbookPath(name, id))) return name;
+  }
+  return null;
+}
+
+/**
+ * Create or update a runbook. Sets createdAt on first save and updatedAt on
+ * every save. Throws on validation failure. Rejects cross-project renames —
+ * if id already exists under a different project, the caller must
+ * deleteRunbook(id) first.
+ */
+function saveRunbook(spec) {
+  const v = validateRunbook(spec);
+  if (!v.ok) {
+    const err = new Error('invalid runbook: ' + v.errors.join('; '));
+    err.validationErrors = v.errors;
+    throw err;
+  }
+  const existingProject = _findOwningProject(spec.id);
+  if (existingProject && existingProject !== spec.project) {
+    throw new Error('runbook id "' + spec.id + '" already exists under project "' + existingProject + '" — delete it before saving under "' + spec.project + '"');
+  }
+
+  const filePath = _runbookPath(spec.project, spec.id);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const nowIso = new Date().toISOString();
+  const result = shared.mutateJsonFileLocked(filePath, (data) => {
+    const prior = (data && typeof data === 'object' && !Array.isArray(data)) ? data : {};
+    return {
+      id: spec.id,
+      name: spec.name,
+      project: spec.project,
+      targetName: spec.targetName,
+      steps: spec.steps.map(s => {
+        const out = { description: s.description };
+        if (typeof s.command === 'string' && s.command.length > 0) out.command = s.command;
+        return out;
+      }),
+      expectedArtifacts: spec.expectedArtifacts.map(a => {
+        const out = { type: a.type, label: a.label };
+        if (typeof a.path === 'string' && a.path.length > 0) out.path = a.path;
+        return out;
+      }),
+      createdAt: _isNonEmptyString(prior.createdAt) ? prior.createdAt : nowIso,
+      updatedAt: nowIso,
+    };
+  }, { defaultValue: {} });
+  return result;
+}
+
+/**
+ * Remove a runbook by id. No-op when the id is not found. Returns true when
+ * a file was removed.
+ *
+ * Coordination: acquires the runbook's lock via withFileLock so a concurrent
+ * saveRunbook can't be mid-rename when we unlink. The unlink happens inside
+ * the lock callback (single fs call — keeps the callback synchronous and
+ * fast per the repo convention).
+ */
+function deleteRunbook(id) {
+  // Hardened: reject traversal ids before they can reach _findOwningProject /
+  // path.join / unlink (review feedback on PR #2694).
+  if (!_isSafeId(id)) return false;
+  const owning = _findOwningProject(id);
+  if (!owning) return false;
+  const filePath = _runbookPath(owning, id);
+  shared.withFileLock(filePath + '.lock', () => {
+    try { fs.unlinkSync(filePath); } catch (_e) { /* already gone */ }
+    try { fs.unlinkSync(filePath + '.backup'); } catch (_e) { /* optional */ }
+  });
+  return true;
+}
+
+module.exports = {
+  ARTIFACT_TYPES,
+  LIMITS,
+  validateRunbook,
+  listRunbooks,
+  getRunbook,
+  saveRunbook,
+  deleteRunbook,
+  // internals exposed for testing
+  _runbookPath,
+  _runbooksDir,
+};

package/engine/queries.js

@@ -673,12 +673,22 @@ function getPullRequests(config) {
     }
   }
   allPrs.sort((a, b) => {
-    // Normalize to YYYY-MM-DD for date comparison (some have full ISO, some date-only)
-    const aDate = (a.created || '').slice(0, 10);
-    const bDate = (b.created || '').slice(0, 10);
-    const dateComp = bDate.localeCompare(aDate);
-    if (dateComp !== 0) return dateComp;
-    // Same date — sort by PR number descending (newest first)
+    // W-mpej044m00076d63: sort by the full ISO `created` timestamp DESC so
+    // same-day PRs preserve creation order (previously the slice-to-date
+    // collapsed every PR opened on the same day into one bucket, then tied
+    // on a noisy PR-number-derived integer that ignored owner/repo digits).
+    // The PR-number tiebreaker survives only as a guard for records that
+    // legitimately lack `created` (e.g. mid-poll backfill window).
+    const aCreated = a.created || '';
+    const bCreated = b.created || '';
+    if (aCreated && bCreated) {
+      const cmp = bCreated.localeCompare(aCreated);
+      if (cmp !== 0) return cmp;
+    } else if (aCreated || bCreated) {
+      // One missing — surface the one with a timestamp first (newer signal).
+      return bCreated ? 1 : -1;
+    }
+    // Final guard for missing-data records: keep PR-number desc (newer first).
     const aNum = parseInt((a.id || '').replace(/\D/g, '')) || 0;
     const bNum = parseInt((b.id || '').replace(/\D/g, '')) || 0;
     return bNum - aNum;

package/engine/shared.js

@@ -1921,6 +1921,13 @@ const ENGINE_DEFAULTS = {
   constellationBridge: {
     enabled: false,
   },
+  // ── Operator identity (W-mpejf0fq000e84d6) ──────────────────────────────────
+  // Explicit override for the human operator's platform login used in branch
+  // names (see `deriveWorkItemBranchName`). `null` (default) means auto-resolve
+  // via `engine/operator-identity.js` (gh → git email localpart → os user).
+  // Settings UI exposes this as a free-text input; clearing the field deletes
+  // the override and falls back to auto-resolution.
+  operatorLogin: null,
 };
 
 // ─── Runtime Fleet Resolution (P-3b8e5f1d) ──────────────────────────────────
@@ -3205,6 +3212,41 @@ function sanitizeBranch(name) {
   return String(name).replace(/[^a-zA-Z0-9._\-\/]/g, '-').slice(0, 200);
 }
 
+// ── Branch name derivation (W-mpejf0fq000e84d6) ──────────────────────────────
+//
+// Single source of truth for the canonical work-item branch name. The convention
+// is `user/<loginname>/<wi-id-lowercased>-<title-slug>` (≤120 chars total).
+//
+// Callers MUST use this helper rather than templating `work/<id>` inline — the
+// branch-naming unit test asserts the literal `work/${item.id}` fallback is
+// gone from engine.js. PR-targeted dispatches and `shared-branch` plans bypass
+// this helper entirely (they reuse the existing branch).
+//
+// `getOperatorLogin` is a thin shim around `engine/operator-identity` so other
+// modules don't need a second require. Required lazily to keep shared.js free
+// of side-effecting child_process imports at module load.
+
+function getOperatorLogin(config) {
+  try {
+    return require('./operator-identity').resolveOperatorLogin(config || {});
+  } catch {
+    return null;
+  }
+}
+
+function deriveWorkItemBranchName(item, config) {
+  const login = getOperatorLogin(config) || 'unknown';
+  const wid = String(item?.id || '').toLowerCase();
+  const src = String(item?.title || item?.description || '').toLowerCase();
+  let slug = src.replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const prefix = `user/${login}/${wid}-`;
+  // Cap total length at 120 chars by trimming the slug, leaving at least 8
+  // chars of slug room. Strip any trailing dash exposed by truncation.
+  const budget = Math.max(8, 120 - prefix.length);
+  if (slug.length > budget) slug = slug.slice(0, budget).replace(/-+$/, '');
+  return sanitizeBranch(prefix + (slug || 'work'));
+}
+
 function _worktreeNameSuffix(dispatchId, projectName, branchName) {
   const id = String(dispatchId || '').split('-').filter(Boolean).pop();
   if (id) return safeSlugComponent(id, 32);
@@ -4812,6 +4854,8 @@ module.exports = {
   getAdoOrgBase,
   sanitizePath,
   sanitizeBranch,
+  getOperatorLogin,
+  deriveWorkItemBranchName,
   safeSlugComponent,
   buildWorktreeDirName, // exported for testing
   isPathInside,

package/engine.js

@@ -4601,7 +4601,7 @@ function refreshDeferredWorkItemPrompt(item, config) {
   const project = projectFromDispatchMeta(item.meta.project, config);
   const root = project?.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..');
   const workType = routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT);
-  const branchName = item.meta.branch || item.meta.item.branch || `work/${item.meta.item.id}`;
+  const branchName = item.meta.branch || item.meta.item.branch || shared.deriveWorkItemBranchName(item.meta.item, config);
   const rendered = renderProjectWorkItemPromptForAgent(item.meta.item, workType, item.agent, config, project, root, branchName);
   if (rendered.prompt) item.prompt = rendered.prompt;
   item.meta.deferAgentResolution = false;
@@ -4802,7 +4802,24 @@ function discoverFromWorkItems(config, project) {
       continue;
     }
     const isShared = item.branchStrategy === 'shared-branch' && item.featureBranch;
-    const branchName = isPrTargeted && prBranch ? prBranch : (isShared ? item.featureBranch : (item.branch || `work/${item.id}`));
+    // W-mpejf0fq000e84d6: when no branch is explicitly set, derive the
+    // canonical `user/<loginname>/<wi-id>-<slug>` name once and persist it
+    // back onto the work item so re-dispatches land on the same branch and
+    // the dashboard surfaces the right value.
+    let branchName;
+    if (isPrTargeted && prBranch) {
+      branchName = prBranch;
+    } else if (isShared) {
+      branchName = item.featureBranch;
+    } else if (item.branch) {
+      branchName = item.branch;
+    } else {
+      branchName = shared.deriveWorkItemBranchName(item, config);
+      if (branchName && item.branch !== branchName) {
+        item.branch = branchName;
+        needsWrite = true;
+      }
+    }
     const deferredAgentResolution = agentId === routing.ANY_AGENT;
 
     // Branch mutex: skip if target branch is locked by an active dispatch
@@ -5356,8 +5373,19 @@ function discoverCentralWorkItems(config) {
         mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, projectMutation));
       }
 
-      // Branch mutex: skip if target branch is locked by an active dispatch
-      const centralBranch = item.branch || item.featureBranch || `work/${item.id}`;
+      // Branch mutex: skip if target branch is locked by an active dispatch.
+      // W-mpejf0fq000e84d6: fall back to the canonical user/<login>/<wi>-<slug>
+      // name (instead of the legacy `work/<id>`) and persist it back on the
+      // central WI so subsequent ticks see the resolved branch.
+      let centralBranch;
+      if (item.branch) centralBranch = item.branch;
+      else if (item.featureBranch) centralBranch = item.featureBranch;
+      else {
+        centralBranch = shared.deriveWorkItemBranchName(item, config);
+        if (centralBranch) {
+          mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { branch: centralBranch }));
+        }
+      }
       const centralBranchConflict = isBranchActive(centralBranch);
       if (centralBranchConflict) {
         log('info', `Branch mutex: skipping central ${item.id} — branch ${centralBranch} locked by ${centralBranchConflict.id} (${centralBranchConflict.agent})`);
@@ -5512,7 +5540,7 @@ function discoverCentralWorkItems(config) {
         agentRole,
         task: item.title || item.description?.slice(0, 80) || item.id,
         prompt,
-        meta: { dispatchKey: key, source: 'central-work-item', item: { ...item, ...mutations.get(item.id) }, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}`, ...(targetProject ? { project: { name: targetProject.name, localPath: targetProject.localPath } } : {}) }
+        meta: { dispatchKey: key, source: 'central-work-item', item: { ...item, ...mutations.get(item.id) }, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: centralBranch, ...(targetProject ? { project: { name: targetProject.name, localPath: targetProject.localPath } } : {}) }
       });
 
       setCooldown(key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1994",
+  "version": "0.1.1996",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/implement.md

@@ -7,9 +7,15 @@ Repository ID is injected as `{{ado_project}}` and `{{repo_name}}` template vari
 Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
 
 ## Branch Naming Convention
-Branch format: `feat/{{item_id}}-<short-description>`
-Examples: `feat/M001-hr-agent`, `feat/M013-multimodal-input`
-Keep branch names lowercase, use hyphens, max 60 chars.
+Branch format: `user/<loginname>/{{item_id}}-<slug>` — see the canonical "Branch Naming Convention" section in shared-rules above.
+
+`<loginname>` is the **human operator's platform login** (e.g. `yemi33` on GitHub, `yemishin` on ADO), resolved via `gh api user --jq .login` or `az account show --query user.name -o tsv`. **Do NOT use the AI agent persona name** (`dallas`, `ripley`, …).
+
+Examples:
+- `user/yemi33/M001-hr-agent`
+- `user/yemishin/M013-multimodal-input`
+
+The engine pre-creates your worktree on a branch matching this convention. The branch is already injected as `{{branch_name}}` — push to that branch as-is; do not create or rename branches.
 
 ## Your Task
 

package/playbooks/plan-to-prd.md

@@ -42,7 +42,7 @@ This file is NOT checked into the repo. The engine reads it on every tick and di
   "status": "awaiting-approval",
   "requires_approval": true,
   "branch_strategy": "shared-branch|parallel",
-  "feature_branch": "feat/plan-short-name",
+  "feature_branch": "user/<loginname>/PL-<short-kebab-slug>",
   "missing_features": [
     {
       "id": "P-<uuid>",
@@ -75,12 +75,12 @@ Choose one of the following strategies based on how the items relate to each oth
 {{branch_strategy_hint}}
 
 When using `shared-branch`:
-- Generate a `feature_branch` name: `feat/plan-<short-kebab-description>` (max 60 chars, lowercase)
+- Generate a `feature_branch` name using the canonical convention: `user/<loginname>/PL-<short-kebab-description>` (≤ 120 chars, lowercase). `<loginname>` is the human operator's platform login (e.g. `yemi33` on GitHub) — never an AI agent persona. See `shared-rules.md` → "Branch Naming Convention".
 - Use `depends_on` to express the ordering — items execute in dependency order
 - Each item should be able to build on the prior items' work
 
 When using `parallel`:
-- Omit `feature_branch` (the engine generates per-item branches)
+- Omit `feature_branch` (the engine derives per-item branches as `user/<loginname>/<wi-id>-<slug>`)
 - `depends_on` is still respected but items can dispatch concurrently if no deps
 
 Rules for items:

package/playbooks/shared-rules.md

@@ -29,6 +29,29 @@ Bias toward senior-engineer restraint:
 - Clean up only artifacts introduced by your own work, such as now-unused imports, variables, helpers, docs, or tests. Mention unrelated dead code instead of deleting it.
 - Turn the task into verifiable goals before editing. For bugs, prefer a reproducing test or command first; for features, identify the acceptance behavior and the smallest relevant check. Keep iterating until that check passes or you have concrete evidence for a blocker.
 
+## Branch Naming Convention
+
+All branches use the format:
+
+    user/<loginname>/<wi-id>-<slug>
+
+- `<loginname>` is the **human operator's platform login** — never the AI agent's persona (`dallas`, `ripley`, `lambert`, …). Resolve in this order:
+  1. GitHub repos: `gh api user --jq .login` (e.g. `yemi33`, `yemishin_microsoft`)
+  2. Azure DevOps repos: `az account show --query user.name -o tsv` and take the localpart before `@` (e.g. `yemishin`)
+  3. Fallback: `git config user.email` localpart, then `$USER` / `$USERNAME`
+- `<wi-id>` is the work-item or PRD-item id verbatim (`W-mp7abc123`, `P-a1b2c3d4`, `PL-…`).
+- `<slug>` is a short lowercase kebab-case summary derived from the title. ASCII only, words separated by `-`, ≤ 40 chars, no leading/trailing hyphens.
+
+Examples:
+- `user/yemi33/W-mp7abc123-fix-login-redirect`
+- `user/yemishin/P-a1b2c3d4-shared-schemas`
+- `user/yemishin_microsoft/PL-feature-rollout-stage-1`
+
+Application:
+- The engine pre-creates your worktree on a branch matching this convention. Push to that branch as injected via `{{branch_name}}` — do not create or rename branches.
+- When you create a work item programmatically (API, plan-to-prd, scripts), set the WI's `branch` (or PRD `feature_branch`) to the conventional name so the engine creates the worktree on the right branch from the start. `dashboard.js` derives this automatically when callers omit `branch`.
+- The legacy `feat/<id>-<slug>` and bare `work/<id>` formats are deprecated; the engine no longer falls back to them.
+
 ## Engine Rules (apply to all tasks)
 
 **Context compaction:** Your context window may be compacted mid-task by Claude's infrastructure. If you notice your earlier conversation history appears truncated or summarized, this is normal and expected. Do not interpret compaction as a signal to stop early or wrap up. Continue working toward your task objective — all relevant instructions and state remain available.

package/playbooks/work-item.md

@@ -17,8 +17,9 @@ Team root: {{team_root}}
 {{additional_context}}
 
 ## Branch Naming Convention
-Branch format: `feat/{{item_id}}-<short-description>`
-Keep branch names lowercase, use hyphens, max 60 chars.
+Branch format: `user/<loginname>/{{item_id}}-<slug>` — see the canonical "Branch Naming Convention" section in shared-rules.
+
+The engine pre-creates the worktree on a branch matching this convention; it is already injected as `{{branch_name}}`. Push to that branch — do not create or rename branches.
 
 ## Delivery Contract
 
@@ -41,7 +42,7 @@ git push -u origin {{branch_name}}
 ```
 
 {{pr_create_instructions}}
-- sourceRefName: `refs/heads/feat/{{item_id}}-<short-desc>`
+- sourceRefName: `refs/heads/{{branch_name}}`
 - targetRefName: `refs/heads/{{main_branch}}`
 - title: `feat({{item_id}}): <description>`