@gredescerber/agent-crew 0.5.0 → 0.6.0

package/src/commands/upgrade.js

@@ -0,0 +1,178 @@
+// crew upgrade [--apply] — bring an existing project's crew files up to this version of agent-crew:
+// AGENTS.md, roles, skills, GitHub workflows and templates, playbooks, generated agent configs, new config keys.
+// Also migrates projects made by hackathon-harness (hk): hk.config.json, hk*.yml, hk-* skills, docs/tz*.md.
+// Without --apply it only shows the plan. With --apply: branch crew/upgrade-<version>, one commit, a PR.
+// The PR changes protected files (AGENTS.md, .github/, agents/), so crew-guard rejects it by design:
+// a human (admin) reviews and merges it.
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, rmSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { ok, fail } from '../core/output.js';
+import { git, gh } from '../core/exec.js';
+import { HARNESS_ROOT, DEFAULT_CONFIG } from '../core/config.js';
+import { LOCAL_VERSION } from '../core/version.js';
+import { buildFiles } from './adapters.js';
+
+/** Files agent-crew owns in a product repo: [source in the package, destination in the repo]. */
+export const OWNED = [
+  ['templates/product/AGENTS.md', 'AGENTS.md'],
+  ['templates/product/.github', '.github'],
+  ['templates/product/docs/playbooks', 'docs/playbooks'],
+  ['roles', 'agents/roles'],
+  ['skills', 'agents/skills'],
+];
+const LEGACY_DELETE = ['.github/workflows/hk.yml', '.github/workflows/hk-guard.yml'];
+/** Skills shipped by hackathon-harness; a project's own skills (even named hk-*) are never touched. */
+const LEGACY_SKILLS = ['hk-kickoff', 'hk-review', 'hk-tz-analysis', 'hk-workflow'];
+const LEGACY_RENAME = [['hk.config.json', 'crew.config.json'], ['docs/tz.md', 'docs/brief.md'], ['docs/tz-analysis.md', 'docs/brief-analysis.md']];
+
+const walk = (abs, base = abs) => {
+  if (!existsSync(abs)) return [];
+  if (statSync(abs).isFile()) return [relative(base, abs).replace(/\\/g, '/')];
+  return readdirSync(abs).flatMap((n) => walk(join(abs, n), base));
+};
+const norm = (s) => String(s ?? '').replace(/\r\n/g, '\n');
+
+/** Package files to put into the repo: [{ path, content }]. */
+export function ownedFiles(harnessRoot = HARNESS_ROOT) {
+  const out = [];
+  for (const [src, dest] of OWNED) {
+    const abs = join(harnessRoot, src);
+    if (statSync(abs).isFile()) out.push({ path: dest, content: readFileSync(abs, 'utf8') });
+    else for (const f of walk(abs)) out.push({ path: `${dest}/${f}`, content: readFileSync(join(abs, f), 'utf8') });
+  }
+  return out;
+}
+
+/** Config after upgrade: user values kept; missing top-level keys and missing areas added. */
+export function mergeConfig(cfg = {}, defaults = DEFAULT_CONFIG) {
+  const out = { ...cfg };
+  const added = [];
+  for (const [k, v] of Object.entries(defaults)) if (!(k in out)) { out[k] = v; added.push(k); }
+  if (defaults.areas && out.areas) {
+    for (const [a, globs] of Object.entries(defaults.areas)) {
+      if (!(a in out.areas)) { out.areas = { ...out.areas, [a]: globs }; added.push(`areas.${a}`); }
+    }
+  }
+  return { config: out, added };
+}
+
+/** .gitignore: the legacy local-files section header and .hk/ become their crew names. */
+export function migrateGitignore(text = '') {
+  return norm(text)
+    .replace(/^# hk: (локальные файлы|local files)$/m, '# crew: local files')
+    .replace(/^\.hk\/$/m, '.crew/');
+}
+
+/**
+ * The plan (pure): repo = { exists(p), read(p), list(dir) }. → { ops, legacy, config_added }
+ * op: { op: 'rename', from, path } | { op: 'delete', path } | { op: 'write', path, content, kind: 'create'|'update' }
+ */
+export function planUpgrade(repo, { files = ownedFiles(), defaults = DEFAULT_CONFIG } = {}) {
+  const ops = [];
+  const legacy = repo.exists('hk.config.json') && !repo.exists('crew.config.json');
+  const moved = new Map(); // destination path -> content (after legacy renames)
+  for (const [from, to] of LEGACY_RENAME) {
+    if (repo.exists(from) && !repo.exists(to)) { ops.push({ op: 'rename', from, path: to }); moved.set(to, repo.read(from)); }
+  }
+  for (const p of LEGACY_DELETE) if (repo.exists(p)) ops.push({ op: 'delete', path: p });
+  for (const p of repo.list?.('agents/skills') ?? []) {
+    if (LEGACY_SKILLS.some((s) => p.startsWith(`agents/skills/${s}/`))) ops.push({ op: 'delete', path: p });
+  }
+  for (const f of files) {
+    const cur = repo.exists(f.path) ? repo.read(f.path) : null;
+    if (cur === null) ops.push({ op: 'write', path: f.path, content: f.content, kind: 'create' });
+    else if (norm(cur) !== norm(f.content)) ops.push({ op: 'write', path: f.path, content: f.content, kind: 'update' });
+  }
+  const cfgText = moved.get('crew.config.json') ?? (repo.exists('crew.config.json') ? repo.read('crew.config.json') : null);
+  let config_added = [];
+  if (cfgText !== null) {
+    const { config, added } = mergeConfig(JSON.parse(cfgText), defaults);
+    config_added = added;
+    if (added.length) ops.push({ op: 'write', path: 'crew.config.json', content: JSON.stringify(config, null, 2) + '\n', kind: 'update' });
+  }
+  if (repo.exists('.gitignore')) {
+    const gi = repo.read('.gitignore');
+    const next = migrateGitignore(gi);
+    if (next !== norm(gi)) ops.push({ op: 'write', path: '.gitignore', content: next, kind: 'update' });
+  }
+  return { ops, legacy, config_added };
+}
+
+const summarize = (ops) => ops.map((o) => (o.op === 'rename' ? `rename ${o.from} -> ${o.path}` : `${o.op === 'delete' ? 'delete' : o.kind} ${o.path}`));
+
+export default {
+  name: 'upgrade',
+  summary: 'Update this project to the installed agent-crew: rules, skills, workflows, configs (and migrate from hk); --apply opens a PR',
+  agent: false,
+  args: [{ name: 'apply', type: 'boolean', description: 'create the branch, commit and open the PR (without it: only show the plan)' }],
+  async run({ apply = false } = {}) {
+    const top = git(['rev-parse', '--show-toplevel'], { allowFail: true });
+    if (top.code !== 0) return fail('not_a_repo', 'Run crew upgrade inside the project repo', { retry: 'cd <project> && crew upgrade' });
+    const root = top.stdout.trim();
+    if (!existsSync(join(root, 'crew.config.json')) && !existsSync(join(root, 'hk.config.json'))) {
+      return fail('not_a_crew_project', 'No crew.config.json (or legacy hk.config.json) here', { retry: 'crew init <dir> for a new project' });
+    }
+    const repo = {
+      exists: (p) => existsSync(join(root, p)),
+      read: (p) => readFileSync(join(root, p), 'utf8'),
+      list: (p) => walk(join(root, p)).map((f) => `${p}/${f}`),
+    };
+    const plan = planUpgrade(repo);
+    const branch = `crew/upgrade-${LOCAL_VERSION}`;
+    const lines = summarize(plan.ops);
+    if (!apply) {
+      return ok(plan.ops.length ? `crew upgrade to ${LOCAL_VERSION}: ${plan.ops.length} changes (dry run)${plan.legacy ? ', migrating from hk' : ''}` : `Already up to date with agent-crew ${LOCAL_VERSION}`, {
+        artifacts: { version: LOCAL_VERSION, legacy: plan.legacy, changes: lines, config_added: plan.config_added },
+        next_actions: plan.ops.length ? ['crew upgrade --apply (creates a branch and a PR; agent configs are regenerated too)'] : ['nothing to do'],
+      });
+    }
+    if (!plan.ops.length) return ok(`Already up to date with agent-crew ${LOCAL_VERSION}`);
+    if (git(['status', '--porcelain'], { cwd: root }).stdout.trim()) {
+      return fail('dirty_tree', 'Uncommitted changes in the project', { retry: 'commit or stash them, then crew upgrade --apply' });
+    }
+    git(['fetch', '--quiet', 'origin'], { cwd: root, allowFail: true });
+    const base = (gh(['repo', 'view', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name'], { cwd: root, allowFail: true }).stdout || '').trim() || 'main';
+    const sw = git(['switch', '-c', branch, `origin/${base}`], { cwd: root, allowFail: true });
+    if (sw.code !== 0) return fail('branch_exists', `Could not create ${branch}`, { cause_hint: (sw.stderr || sw.stdout).split('\n')[0], retry: `git branch -D ${branch} (if it is a leftover), then crew upgrade --apply` });
+    for (const o of plan.ops) {
+      if (o.op === 'rename') git(['mv', o.from, o.path], { cwd: root });
+      else if (o.op === 'delete') rmSync(join(root, o.path), { force: true });
+    }
+    for (const o of plan.ops.filter((x) => x.op === 'write')) {
+      mkdirSync(dirname(join(root, o.path)), { recursive: true });
+      writeFileSync(join(root, o.path), o.content);
+    }
+    // Generated agent configs from the new rules (same as crew adapters build), committed ones only.
+    const config = JSON.parse(readFileSync(join(root, 'crew.config.json'), 'utf8'));
+    const { files } = await buildFiles(root, config);
+    for (const f of files.filter((x) => x.commit)) {
+      mkdirSync(dirname(join(root, f.path)), { recursive: true });
+      writeFileSync(join(root, f.path), f.content);
+    }
+    git(['add', '-A'], { cwd: root });
+    git(['commit', '-q', '-m', `chore: upgrade to agent-crew ${LOCAL_VERSION}`, '-m', 'Agent: crew-upgrade'], { cwd: root });
+    const push = git(['push', '-u', 'origin', branch], { cwd: root, allowFail: true });
+    if (push.code !== 0) return fail('push_failed', `Committed on ${branch}, push failed`, { cause_hint: (push.stderr || push.stdout).split('\n')[0], retry: `git push -u origin ${branch}` });
+    const body = [
+      `Upgrade to agent-crew ${LOCAL_VERSION}${plan.legacy ? ' (migration from hackathon-harness / hk)' : ''}.`,
+      '',
+      'Changes:',
+      ...lines.map((l) => `- ${l}`),
+      '- regenerated agent configs (crew adapters build)',
+      '',
+      'This PR changes protected files (AGENTS.md, .github/, agents/), so crew-guard fails it on purpose: a human reviews and merges it.',
+      'Check the diff of updated and deleted files: local customizations of AGENTS.md, workflows or roles are replaced by the package versions — re-apply the ones you need.',
+      'After merging: `crew github setup --apply` (labels, CREW_HARNESS variable)' + (plan.legacy ? '; delete the old variable: `gh variable delete HK_HARNESS`.' : '.'),
+    ].join('\n');
+    const pr = gh(['pr', 'create', '--base', base, '--head', branch, '--title', `chore: upgrade to agent-crew ${LOCAL_VERSION}`, '--body', body], { cwd: root, allowFail: true });
+    return ok(`Upgrade PR: ${(pr.stdout || '').split('\n').pop() || '(gh pr create failed — open it by hand)'}`, {
+      status: pr.code === 0 ? 'success' : 'warning',
+      artifacts: { branch, version: LOCAL_VERSION, legacy: plan.legacy, changes: lines },
+      next_actions: [
+        'human: review and merge the PR (crew-guard rejects protected-file changes by design)',
+        'after merge: crew github setup --apply' + (plan.legacy ? ' and gh variable delete HK_HARNESS' : ''),
+        'everyone: update the local crew (npm i -g @gredescerber/agent-crew) and restart agent sessions',
+      ],
+    });
+  },
+};

package/src/core/board.js

@@ -0,0 +1,127 @@
+// Task board for humans (crew board): see the queue and steer it by hand without spending agent tokens.
+// Pure functions: the model shown on the page, and the gh arguments for each action the page can request.
+import { labelValue } from './issues.js';
+import { prQueue } from './queue.js';
+import { LOGIN_RE } from './prd.js';
+
+export const COLUMNS = ['ready', 'claimed', 'review', 'waiting', 'blocked', 'needs-spec'];
+export const PRIORITIES = ['high', 'normal', 'low'];
+/** Statuses a human may set from the board. claimed/review belong to the agent's lease and PR flow. */
+export const BOARD_STATUSES = ['ready', 'blocked', 'needs-spec', 'waiting'];
+
+const prio = (i) => labelValue(i, 'priority') ?? 'normal';
+
+export function boardModel({ issues = [], prs = [], members = [], config = {}, now = Date.now() } = {}) {
+  const columns = Object.fromEntries(COLUMNS.map((c) => [c, []]));
+  const other = [];
+  for (const i of issues) {
+    const status = labelValue(i, 'status');
+    if ((i.labels ?? []).some((l) => l.name === 'epic')) continue;
+    const card = {
+      number: i.number,
+      title: i.title,
+      status,
+      area: labelValue(i, 'area'),
+      tier: labelValue(i, 'tier'),
+      risk: labelValue(i, 'risk'),
+      priority: prio(i),
+      assignees: (i.assignees ?? []).map((a) => a.login),
+      idle_min: Math.max(0, Math.round((now - Date.parse(i.updatedAt ?? '')) / 60000)) || 0,
+    };
+    (columns[status] ?? other).push(card);
+  }
+  const order = { high: 0, normal: 1, low: 2 };
+  for (const c of COLUMNS) columns[c].sort((a, b) => order[a.priority] - order[b.priority] || a.number - b.number);
+  const queue = prQueue(prs, { me: 'board', login: null, reviewers: [], config, now }).map((x) => ({
+    kind: x.kind, number: x.number, title: x.title, risk: x.risk, age_min: x.age, reason: x.reason ?? null, have: x.have ?? null, need: x.need ?? null,
+  }));
+  return { columns, untracked: other.length, prs: queue, members: [...new Set(members)].sort((a, b) => a.localeCompare(b)), generated_at: new Date(now).toISOString() };
+}
+
+/**
+ * gh arguments for one board action, or { error }. Everything is validated here because the page
+ * is only a convenience: the server never passes page input to gh unchecked.
+ * current: the issue as listed ({ number, labels, assignees }).
+ */
+export function actionArgs({ op, value }, current, { members = [] } = {}) {
+  if (!current || !Number.isInteger(current.number)) return { error: 'unknown issue' };
+  const n = String(current.number);
+  const labels = (current.labels ?? []).map((l) => l.name);
+  if (op === 'assign') {
+    const to = String(value ?? '');
+    const now = (current.assignees ?? []).map((a) => a.login);
+    if (to && (!LOGIN_RE.test(to) || !members.some((m) => m.toLowerCase() === to.toLowerCase()))) return { error: `${to} is not a member of this repo` };
+    const args = ['issue', 'edit', n];
+    for (const a of now) if (a.toLowerCase() !== to.toLowerCase()) args.push('--remove-assignee', a);
+    if (to && !now.some((a) => a.toLowerCase() === to.toLowerCase())) args.push('--add-assignee', to);
+    return args.length > 3 ? { args } : { noop: true };
+  }
+  if (op === 'status') {
+    const to = String(value ?? '');
+    if (!BOARD_STATUSES.includes(to)) return { error: `status must be one of ${BOARD_STATUSES.join(', ')}` };
+    const from = labels.filter((l) => l.startsWith('status:')).map((l) => l.slice(7));
+    if (from.some((s) => s === 'claimed' || s === 'review')) {
+      return { error: `#${n} is ${from.join(',')}: an agent holds it — use crew task release ${n} --force first` };
+    }
+    if (from.length === 1 && from[0] === to) return { noop: true };
+    const args = ['issue', 'edit', n, '--add-label', `status:${to}`];
+    for (const f of from) if (f !== to) args.push('--remove-label', `status:${f}`);
+    return { args };
+  }
+  if (op === 'priority') {
+    const to = String(value ?? '');
+    if (!PRIORITIES.includes(to)) return { error: `priority must be one of ${PRIORITIES.join(', ')}` };
+    const args = ['issue', 'edit', n];
+    for (const l of labels.filter((x) => x.startsWith('priority:') && x !== `priority:${to}`)) args.push('--remove-label', l);
+    if (to !== 'normal' && !labels.includes(`priority:${to}`)) args.push('--add-label', `priority:${to}`);
+    return args.length > 3 ? { args } : { noop: true };
+  }
+  return { error: `unknown action ${op}` };
+}
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+/** The board page. Data comes from /api/board; actions go to /api/action with the per-run token. */
+export function renderPage({ token, repo }) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>crew board — ${esc(repo)}</title>
+<style>
+:root{--bg:#f6f7f9;--card:#fff;--ink:#1d2433;--muted:#667085;--line:#e3e6ec;--hi:#d92d20}
+@media (prefers-color-scheme:dark){:root{--bg:#111418;--card:#1a1f26;--ink:#e6e9ef;--muted:#98a2b3;--line:#2a313b}}
+*{box-sizing:border-box}body{margin:0;font:14px/1.4 system-ui,sans-serif;background:var(--bg);color:var(--ink)}
+header{display:flex;gap:12px;align-items:center;padding:12px 16px;border-bottom:1px solid var(--line);flex-wrap:wrap}
+header h1{font-size:16px;margin:0}.muted{color:var(--muted)}
+main{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:12px;padding:12px 16px}
+section h2,#prs h2{font-size:12px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:4px 0 8px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:10px;margin-bottom:8px}
+.card a{color:var(--ink);text-decoration:none;font-weight:600}.meta{color:var(--muted);font-size:12px;margin:4px 0 6px}
+.prio-high{border-left:4px solid var(--hi)}.prio-low{opacity:.75}
+.row{display:flex;gap:6px;flex-wrap:wrap}select{font:inherit;font-size:12px;padding:2px 4px;border-radius:6px;border:1px solid var(--line);background:var(--card);color:var(--ink)}
+#prs{padding:0 16px 16px}#prs a{color:var(--ink)}#prs li{margin:4px 0}#msg{color:var(--hi)}
+</style></head><body>
+<header><h1>crew board</h1><span class="muted">${esc(repo)}</span><span class="muted" id="time"></span><span id="msg"></span></header>
+<main id="cols"></main>
+<div id="prs"><h2>Pull requests waiting</h2><ul id="prlist"></ul></div>
+<script>
+const TOKEN=${JSON.stringify(token)};const REPO=${JSON.stringify(repo)};
+const COLS=${JSON.stringify(COLUMNS)};const ST=${JSON.stringify(BOARD_STATUSES)};const PR=${JSON.stringify(PRIORITIES)};
+const e=(t,a={},...k)=>{const n=document.createElement(t);for(const[x,y]of Object.entries(a)){if(x==='on')for(const[ev,f]of Object.entries(y))n.addEventListener(ev,f);else n.setAttribute(x,y)}for(const c of k)n.append(c);return n};
+const sel=(opts,cur,on)=>{const s=e('select',{on:{change:()=>on(s.value)}});for(const[v,l]of opts){const o=e('option',{value:v},l);if(v===cur)o.selected=true;s.append(o)}return s};
+async function act(issue,op,value){const r=await fetch('/api/action',{method:'POST',headers:{'content-type':'application/json','x-crew-token':TOKEN},body:JSON.stringify({issue,op,value})});const j=await r.json();document.getElementById('msg').textContent=j.error||'';load()}
+async function load(){const r=await fetch('/api/board',{headers:{'x-crew-token':TOKEN}});const m=await r.json();if(m.error){document.getElementById('msg').textContent=m.error;return}
+document.getElementById('time').textContent='updated '+new Date(m.generated_at).toLocaleTimeString();
+const cols=document.getElementById('cols');cols.replaceChildren();
+for(const c of COLS){const s=e('section',{},e('h2',{},c+' ('+m.columns[c].length+')'));
+for(const t of m.columns[c]){const who=[['','unassigned'],...m.members.map(x=>[x,x])];
+const ctl=e('div',{class:'row'},sel(who,t.assignees[0]||'',v=>act(t.number,'assign',v)),sel(PR.map(p=>[p,p]),t.priority,v=>act(t.number,'priority',v)));
+if(ST.includes(t.status))ctl.append(sel(ST.map(x=>[x,x]),t.status,v=>act(t.number,'status',v)));
+s.append(e('div',{class:'card prio-'+t.priority},e('a',{href:'https://github.com/'+REPO+'/issues/'+t.number,target:'_blank',rel:'noopener'},'#'+t.number+' '+t.title),
+e('div',{class:'meta'},[t.area&&('area:'+t.area),t.risk&&('risk:'+t.risk),t.tier&&('tier:'+t.tier),t.assignees.length?('@'+t.assignees.join(' @')):'no owner',t.idle_min+' min'].filter(Boolean).join(' · ')),ctl))}
+cols.append(s)}
+const ul=document.getElementById('prlist');ul.replaceChildren();
+for(const p of m.prs)ul.append(e('li',{},e('a',{href:'https://github.com/'+REPO+'/pull/'+p.number,target:'_blank',rel:'noopener'},'#'+p.number+' '+p.title),' — '+(p.kind==='review'?('waiting for review '+p.age_min+' min ('+p.have+'/'+p.need+')'):p.kind==='merge'?'ready to merge':('waiting for the author: '+p.reason))));
+if(!m.prs.length)ul.append(e('li',{class:'muted'},'none'))}
+load();setInterval(load,30000);
+</script></body></html>`;
+}

package/src/core/config.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { hostname } from 'node:os';
+import { pinnedId } from './session.js';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -72,6 +73,11 @@ export const machineName = () =>
  */
 export function agentId(env = process.env) {
   if (env.CREW_AGENT_ID) return env.CREW_AGENT_ID;
+  // A task worktree remembers who claimed it (crew task claim), so CLI calls there act as the same session.
+  if (env === process.env) {
+    const pinned = pinnedId();
+    if (pinned) return pinned;
+  }
   const base = env.CREW_AGENT || 'human';
   return base.includes('@') ? base : `${base}@${machineName()}`;
 }

package/src/core/digest.js

@@ -0,0 +1,67 @@
+// Team digest without an LLM: what waits for a human, stale leases, PRs, idle members. `crew digest` prints it;
+// the sweep job posts it to one pinned issue every 15 minutes, so no agent session has to poll the repo.
+import { labelValue } from './issues.js';
+import { prQueue } from './queue.js';
+import { questionMeta, HUMAN_LABEL, QUESTION_LABEL } from './questions.js';
+
+export const DIGEST_LABEL = 'crew:digest';
+export const DIGEST_TITLE = 'crew digest: team status';
+export const DIGEST_MARKER = '<!-- crew:digest -->';
+
+const minsSince = (now, iso) => Math.max(0, Math.round((now - Date.parse(iso ?? '')) / 60000)) || 0;
+const names = (xs) => (xs ?? []).map((x) => x.name);
+
+/** -> { sections: [{ key, title, lines }], counts } (pure, no network). */
+export function digestModel({ issues = [], prs = [], questions = [], team = null, config = {}, now = Date.now() } = {}) {
+  const lease = config.lease_minutes ?? 45;
+  const reviewWait = config.review?.fallback_minutes ?? 30;
+  const st = (i) => labelValue(i, 'status');
+  const who = (i) => (i.assignees ?? []).map((a) => `@${a.login}`).join(' ') || 'no owner';
+  const tasks = issues.filter((i) => !names(i.labels).some((n) => ['epic', QUESTION_LABEL, DIGEST_LABEL].includes(n)));
+  const ready = tasks.filter((i) => st(i) === 'ready');
+  const claimed = tasks.filter((i) => st(i) === 'claimed');
+
+  const human = questions.filter((q) => names(q.labels).includes(HUMAN_LABEL))
+    .map((q) => `#${q.number} ${q.title} (asked by ${questionMeta(q)?.from ?? 'an agent'})`);
+  const blocked = tasks.filter((i) => ['blocked', 'needs-spec'].includes(st(i))).map((i) => `#${i.number} ${i.title} (${st(i)}, ${who(i)})`);
+  const stale = claimed.filter((i) => minsSince(now, i.updatedAt) > lease)
+    .map((i) => `#${i.number} ${i.title} (${who(i)}, quiet ${minsSince(now, i.updatedAt)} min, lease ${lease})`);
+  const prLines = prQueue(prs, { me: 'crew-digest', login: null, reviewers: [], config, now }).map((x) =>
+    x.kind === 'fix' ? `#${x.number} ${x.title}: waits for its author (${x.reason})`
+      : x.kind === 'merge' ? `#${x.number} ${x.title}: ready to merge`
+        : `#${x.number} ${x.title}: waits for review ${x.age} min${x.age > reviewWait ? ' (slow)' : ''}`);
+  const unanswered = questions.filter((q) => !names(q.labels).includes(HUMAN_LABEL))
+    .map((q) => `#${q.number} ${q.title} (to ${who(q)}, ${minsSince(now, q.createdAt ?? q.updatedAt)} min)`);
+  const idle = [];
+  for (const m of team?.members ?? []) {
+    const lc = m.login.toLowerCase();
+    const mine = (i) => (i.assignees ?? []).some((a) => a.login.toLowerCase() === lc);
+    if (claimed.some(mine)) continue;
+    const waiting = ready.filter(mine).length;
+    idle.push(`@${m.login}: nothing in progress, ${waiting ? `${waiting} ready task(s) assigned` : 'no ready tasks assigned'}`);
+  }
+
+  const sections = [
+    { key: 'human', title: 'Needs a human', lines: [...human, ...blocked] },
+    { key: 'stale', title: 'Stale leases', lines: stale },
+    { key: 'prs', title: 'Pull requests', lines: prLines },
+    { key: 'questions', title: 'Open questions between agents', lines: unanswered },
+    { key: 'idle', title: 'Idle members', lines: idle },
+  ];
+  return {
+    sections,
+    counts: { ready: ready.length, claimed: claimed.length, human: human.length + blocked.length, stale: stale.length, prs: prLines.length, questions: unanswered.length, idle: idle.length },
+  };
+}
+
+/** Markdown for the pinned issue (and the terminal). */
+export function renderDigest(model, { now = Date.now() } = {}) {
+  const c = model.counts;
+  const stamp = new Date(now).toISOString().replace('T', ' ').slice(0, 16);
+  const out = [DIGEST_MARKER, `_Updated ${stamp} UTC by \`crew digest\` (no LLM). Edits here are overwritten._`, '',
+    `**${c.ready}** ready · **${c.claimed}** in progress · **${c.human}** need a human · **${c.stale}** stale · **${c.prs}** PRs waiting`, ''];
+  // The issue is rewritten every 15 minutes: break @mentions (ours and any in titles) so nobody gets pinged each time.
+  const quiet = (l) => l.replace(/@(?=[\w-])/g, '@​');
+  for (const s of model.sections) out.push(`### ${s.title}`, ...(s.lines.length ? s.lines.map((l) => `- ${quiet(l)}`) : ['- none']), '');
+  return out.join('\n');
+}

package/src/core/guard.js

@@ -35,7 +35,7 @@ export function isPureMove(f = {}) {
 
 /** Markers of a task from the issue body: { taskId, testsFor, testsIssue }. */
 export function taskMarkers(issueBody = '') {
-  const pick = (kind, key) => new RegExp(`<!-- crew:${kind}\\b[^>]*?\\b${key}=(\\S+?)[\\s>]`).exec(issueBody ?? '')?.[1] ?? null;
+  const pick = (kind, key) => new RegExp(`<!-- (?:crew|hk):${kind}\\b[^>]*?\\b${key}=(\\S+?)[\\s>]`).exec(issueBody ?? '')?.[1] ?? null;
   return { taskId: pick('task', 'id'), testsFor: pick('tests-for', 'task'), testsIssue: Number(pick('tests', 'issue')) || null };
 }
 export const ACCEPTANCE_SECTION = 'Changes acceptance';
@@ -132,7 +132,7 @@ export function reviewState(comments = [], { headSha, author, policy, prCreatedA
   for (const c of comments) {
     // in a public repo anyone can comment: review markers only count from repo members
     if (!isTrustedComment(c)) continue;
-    for (const m of String(c.body ?? '').matchAll(/<!-- crew:review((?: \w+=\S+)*) -->/g)) {
+    for (const m of String(c.body ?? '').matchAll(/<!-- (?:crew|hk):review((?: \w+=\S+)*) -->/g)) {
       const f = Object.fromEntries([...m[1].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
       if (!f.agent || !f.verdict || !f.sha) continue;
       latest.set(f.agent, { agent: f.agent, verdict: f.verdict, sha: f.sha, at: c.createdAt });
@@ -224,19 +224,26 @@ export function evaluateGuard({ files = [], body = '', issueBody = '', comments
     problems.push({ rule: 'changes_requested', message: `reviewer requests changes: ${review.changes.join(', ')}` });
   }
 
+  // A human may waive "paperwork" rules for this commit (crew pr waive): a PR made outside crew (cloud session,
+  // plain git). Protected files, acceptance tests and the review itself can never be waived.
+  const waivers = waivedRules(comments, headSha);
+  const waived = problems.filter((p) => WAIVABLE.includes(p.rule) && waivers.has(p.rule)).map((p) => p.rule);
+  for (const r of waived) problems.splice(problems.findIndex((p) => p.rule === r), 1);
+
   const fail = problems.length > 0;
   const reviewed = review.approvals.length >= need;
   const state = fail ? 'failure' : reviewed ? 'success' : 'pending';
   const who = policy.require === 'other-vendor' && !review.fallback ? 'an agent from another vendor' : 'another agent';
-  const description = fail
+  const description = (fail
     ? problems.map((p) => p.rule).join(', ')
     : reviewed
       ? `ok: review ${review.approvals.join(', ') || 'not required'}`
-      : `waiting for review by ${who}: ${review.approvals.length}/${need}`;
+      : `waiting for review by ${who}: ${review.approvals.length}/${need}`) + (waived.length && !fail ? ` (waived: ${waived.join(', ')})` : '');
   return {
     state,
     description: description.slice(0, 140),
     problems,
+    waived,
     issue,
     author,
     review: { ...review, need, require: policy.require },
@@ -244,5 +251,23 @@ export function evaluateGuard({ files = [], body = '', issueBody = '', comments
   };
 }
 
+/** Rules a human can waive with crew pr waive (paperwork only). */
+export const WAIVABLE = ['closes', 'agent_trailer', 'not_crew_pr'];
+
+/** Waived rules for this head commit: <!-- crew:waive rule=<r> sha=<head> --> in trusted, non-bot comments. */
+export function waivedRules(comments = [], headSha = '') {
+  const out = new Set();
+  for (const c of comments) {
+    if (!isTrustedComment(c) || /\[bot\]$|^github-actions$/.test(c.author?.login ?? '')) continue;
+    for (const m of String(c.body ?? '').matchAll(/<!-- crew:waive((?: \w+=\S+)*) -->/g)) {
+      const f = Object.fromEntries([...m[1].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
+      if (f.rule && f.sha && f.sha.length >= 7 && String(headSha).startsWith(f.sha)) out.add(f.rule);
+    }
+  }
+  return out;
+}
+
+export const waiveMarker = ({ rule, sha }) => `<!-- crew:waive rule=${rule} sha=${sha} -->`;
+
 /** Review marker text for a comment. */
 export const reviewMarker = ({ verdict, agent, sha }) => `<!-- crew:review verdict=${verdict} agent=${agent} sha=${sha} -->`;

package/src/core/issues.js

@@ -72,7 +72,7 @@ export function parseMarkers(comments = [], { trustedOnly = true } = {}) {
   const out = [];
   for (const c of comments) {
     if (trustedOnly && !isTrustedComment(c)) continue;
-    for (const m of (c.body ?? '').matchAll(/<!-- crew:(\w+)((?: \w+=\S+)*) -->/g)) {
+    for (const m of (c.body ?? '').matchAll(/<!-- (?:crew|hk):(\w+)((?: \w+=\S+)*) -->/g)) {
       const fields = Object.fromEntries([...m[2].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
       out.push({ kind: m[1], ...fields, createdAt: c.createdAt, by: c.author?.login ?? null });
     }

package/src/core/prd.js

@@ -12,12 +12,17 @@ export const HIGH_STAKES_AREAS = ['contracts', 'infra'];
 export const MAX_TASKS = 25;
 export const DEFAULT_PRD = 'docs/prd.md';
 
-const TASK_KEYS = ['id', 'title', 'epic', 'area', 'tier', 'risk', 'after', 'paths', 'contract', 'goal', 'acceptance', 'out_of_scope', 'tests', 'req', 'changes_acceptance', 'tests_for', 'skeleton', 'ready'];
+const TASK_KEYS = ['id', 'title', 'epic', 'area', 'tier', 'risk', 'after', 'paths', 'contract', 'goal', 'acceptance', 'out_of_scope', 'tests', 'req', 'changes_acceptance', 'tests_for', 'skeleton', 'ready', 'independent'];
+/**
+ * Areas whose tasks do not wait for the skeleton (no code: mockups, research, docs). At the hackathon the
+ * designer idled until the skeleton merged. A task elsewhere can opt out with `independent: true`.
+ */
+export const INDEPENDENT_AREAS = ['design', 'research'];
 const EPIC_KEYS = ['id', 'title', 'scenario', 'demo'];
 const TASK_REQUIRED = ['id', 'title', 'area', 'tier', 'goal', 'acceptance'];
 const EPIC_REQUIRED = ['id', 'title', 'scenario'];
 const LIST_KEYS = ['acceptance', 'after', 'paths', 'out_of_scope', 'tests', 'req', 'changes_acceptance'];
-const BOOL_KEYS = ['skeleton', 'ready'];
+const BOOL_KEYS = ['skeleton', 'ready', 'independent'];
 
 const err = (line, id, rule, message) => ({ line, id: id ?? null, rule, message });
 
@@ -168,7 +173,7 @@ export function areaOwners(team) {
 export const teamReviewers = (team) => (team?.members ?? []).filter((m) => m.review).map((m) => m.login);
 
 /** PRD approval header: <!-- crew:prd status: approved by: <login|auto-timeout> at: ISO -->. */
-export const PRD_HEADER_RE = /^\s*<!--\s*crew:prd\s+status:\s*([\w-]+)(?:\s+by:\s*(\S+))?(?:\s+at:\s*(\S+))?\s*-->\s*$/m;
+export const PRD_HEADER_RE = /^\s*<!--\s*(?:crew|hk):prd\s+status:\s*([\w-]+)(?:\s+by:\s*(\S+))?(?:\s+at:\s*(\S+))?\s*-->\s*$/m;
 
 export function prdApproval(text = '') {
   const m = PRD_HEADER_RE.exec(text);
@@ -194,7 +199,8 @@ const skeletonOf = (tasks) => tasks.find((t) => t.fields.skeleton === true) ?? n
  */
 export function depsOf(task, skeletonId, tasks = []) {
   const out = [...(task.fields.after ?? [])];
-  if (skeletonId && task.id !== skeletonId && !out.includes(skeletonId)) out.unshift(skeletonId);
+  const independent = task.fields.independent === true || INDEPENDENT_AREAS.includes(task.fields.area);
+  if (skeletonId && task.id !== skeletonId && !independent && !out.includes(skeletonId)) out.unshift(skeletonId);
   for (const t of tasks) if (t.fields.tests_for === task.id && t.id && !out.includes(t.id)) out.push(t.id);
   return out;
 }
@@ -433,6 +439,19 @@ function lintTeam({ tasks, team }, { areas, errors, warnings }) {
   for (const m of team.members) {
     if (load.get(m.login) === 0 && !m.review) warnings.push(err(m.line, null, 'member_idle', `${m.login} has no tasks in their areas (${m.areas.join(', ') || '-'}): give them an area with tasks`));
   }
+  // Nobody should wait for someone else's task at the start: each member needs a task that is ready right after kickoff.
+  const skel = tasks.find((t) => t.fields.skeleton === true);
+  const startable = new Map(team.members.map((m) => [m.login, 0]));
+  for (const t of tasks) {
+    const o = owner.get(t.fields.area);
+    // ready at kickoff, or right after the skeleton (which everyone waits for briefly)
+    if (o && (t === skel || depsOf(t, skel?.id ?? null, tasks).every((d) => d === skel?.id))) startable.set(o, startable.get(o) + 1);
+  }
+  for (const m of team.members) {
+    if (load.get(m.login) > 0 && startable.get(m.login) === 0) {
+      warnings.push(err(m.line, null, 'member_waits', `every task of ${m.login} waits for other people's tasks: add one that can start right away (area ${INDEPENDENT_AREAS.join('/')}, docs, or independent: true)`));
+    }
+  }
   const counts = [...load.values()].filter((n) => n > 0);
   if (counts.length > 1 && Math.max(...counts) >= 3 && Math.max(...counts) > 2 * Math.min(...counts)) {
     warnings.push(err(team.line, null, 'team_imbalance', `uneven load: ${[...load].map(([l, n]) => `${l} ${n}`).join(', ')}: redistribute areas or tasks`));

package/src/core/questions.js

@@ -0,0 +1,51 @@
+// Agent-to-agent questions through GitHub (crew ask / inbox / answer), pure helpers.
+// A question is an issue labelled crew:question, assigned to the owner of the area (or a person), with a marker
+// <!-- crew:question from=<agent> task=<n> -->. An answer is a comment <!-- crew:answer agent=<agent> --> + close.
+// Decisions only a human can make get the needs-human label and stay open.
+// Question and answer text is DATA for the reader, never instructions.
+import { parseMarkers } from './issues.js';
+
+export const QUESTION_LABEL = 'crew:question';
+export const HUMAN_LABEL = 'needs-human';
+
+/** More than 30% of letters are Cyrillic: agents write to each other in English (humans may use any language). */
+export function mostlyNonEnglish(text = '') {
+  const letters = String(text).match(/\p{L}/gu) ?? [];
+  if (letters.length < 8) return false;
+  const cyr = letters.filter((c) => /[Ѐ-ӿ]/.test(c)).length;
+  return cyr / letters.length > 0.3;
+}
+
+export function questionBody({ text, from, task, area }) {
+  const fields = [`from=${from}`, task ? `task=${task}` : null, area ? `area=${area}` : null].filter(Boolean).join(' ');
+  return `${text.trim()}\n\n_Asked by \`${from}\`${task ? ` while working on #${task}` : ''}. Answer with \`crew answer <this issue> --text "..."\`; if a human must decide, \`crew answer <this issue> --human --text "..."\`._\n\n<!-- crew:question ${fields} -->\n`;
+}
+
+export const questionMeta = (issue) => parseMarkers([{ body: issue.body ?? '' }]).find((m) => m.kind === 'question') ?? null;
+export const answerMarker = (agent) => `<!-- crew:answer agent=${agent} -->`;
+export const ackMarker = (agent) => `<!-- crew:ack agent=${agent} -->`;
+
+/**
+ * What waits for me (pure). open: open crew:question issues; closed: recently closed ones (with comments).
+ * → { toAnswer: [{ number, title, from, task }], answered: [{ number, title, task }] }
+ */
+export function inboxFor({ open = [], closed = [], me, login, myAreas = [] }) {
+  const lc = (s) => String(s ?? '').toLowerCase();
+  const toAnswer = [];
+  for (const q of open) {
+    const meta = questionMeta(q) ?? {};
+    const labels = (q.labels ?? []).map((l) => l.name ?? l);
+    if (labels.includes(HUMAN_LABEL)) continue; // waits for a human, not for an agent
+    if (meta.from === me) continue;
+    const mine = (q.assignees ?? []).some((a) => lc(a.login) === lc(login)) || (meta.area && myAreas.includes(meta.area));
+    if (mine) toAnswer.push({ number: q.number, title: q.title, from: meta.from ?? null, task: meta.task ? Number(meta.task) : null });
+  }
+  const answered = [];
+  for (const q of closed) {
+    const meta = questionMeta(q);
+    if (!meta || meta.from !== me) continue;
+    const acked = parseMarkers(q.comments ?? []).some((m) => m.kind === 'ack' && m.agent === me);
+    if (!acked) answered.push({ number: q.number, title: q.title, task: meta.task ? Number(meta.task) : null });
+  }
+  return { toAnswer: toAnswer.sort((a, b) => a.number - b.number), answered: answered.sort((a, b) => a.number - b.number) };
+}

package/src/core/queue.js

@@ -63,7 +63,7 @@ export function prQueue(prs = [], { me, login, reviewers = [], config = {}, now
       continue;
     }
     const sha7 = String(pr.headRefOid ?? '').slice(0, 7);
-    const reviewedHead = !!sha7 && (pr.comments ?? []).some((c) => new RegExp(`<!-- crew:review [^>]*agent=${esc(me)} [^>]*sha=${esc(sha7)}`).test(c.body ?? ''));
+    const reviewedHead = !!sha7 && (pr.comments ?? []).some((c) => new RegExp(`<!-- (?:crew|hk):review [^>]*agent=${esc(me)} [^>]*sha=${esc(sha7)}`).test(c.body ?? ''));
     const counts = policy.require === 'other-agent' || rs.fallback || !author || vendorOf(author) !== vendorOf(me);
     const authorIsReviewer = reviewers.some((r) => lc(r) === lc(pr.author?.login));
     const turn = isReviewer || !reviewers.length || authorIsReviewer || age >= policy.fallback_minutes;
@@ -86,7 +86,9 @@ export function taskOrder(ready = [], { login, area, tier = 'high' } = {}) {
     .map((i) => {
       const owners = (i.assignees ?? []).map((a) => a.login);
       const mine = !!me && owners.some((o) => o.toLowerCase() === me);
-      return { issue: i, owners, mine, rank: mine ? 0 : owners.length ? 2 : 1 };
+      // priority:high / priority:low (set by a human, e.g. on crew board) order tasks inside each group
+      const p = { high: 0, low: 2 }[labelValue(i, 'priority')] ?? 1;
+      return { issue: i, owners, mine, rank: (mine ? 0 : owners.length ? 2 : 1) * 10 + p };
     })
     .sort((a, b) => a.rank - b.rank || a.issue.number - b.issue.number);
 }

package/src/core/registry.js

@@ -28,6 +28,11 @@ import kickoff from '../commands/kickoff.js';
 import guard from '../commands/guard.js';
 import up from '../commands/up.js';
 import shots from '../commands/shots.js';
+import board from '../commands/board.js';
+import upgrade from '../commands/upgrade.js';
+import askCmds from '../commands/ask.js';
+import mergeReady from '../commands/merge-ready.js';
+import digest from '../commands/digest.js';
 import { existsSync, realpathSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { loadConfig } from './config.js';
@@ -43,7 +48,7 @@ export const CWD_ARG = {
 /** Command arguments including the shared ones (cwd). */
 export const argsOf = (cmd) => [...(cmd.args ?? []), ...(cmd.usesCwd && !(cmd.args ?? []).some((a) => a.name === 'cwd') ? [CWD_ARG] : [])];
 
-export const commands = [...task, ...kickoff, check, ...pr, guard, status, commit, init, up, adapters, labels, ...compliance, doctor, worker, github, metrics, evalCmd, shots];
+export const commands = [...task, ...kickoff, check, ...pr, guard, status, commit, init, up, adapters, labels, ...compliance, doctor, worker, github, metrics, evalCmd, shots, board, upgrade, ...askCmds, mergeReady, digest];
 
 /** For MCP: only commands safe for agents (no init/labels/adapters; a human does those). */
 export const agentCommands = commands.filter((c) => c.agent !== false);