dw-kit 1.4.0 → 1.6.0-rc.1

package/src/commands/agent-claim.mjs

@@ -0,0 +1,235 @@
+import chalk from 'chalk';
+import { existsSync, openSync, closeSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createClaim, persistClaim, validateClaim, transitionClaim, loadClaim, listClaims } from '../lib/agent-claim.mjs';
+import { logAgentEvent } from '../lib/agent-events.mjs';
+import { scopesOverlap } from '../lib/agent-conflict.mjs';
+import { logEvent as logTelemetry } from '../lib/telemetry.mjs';
+
+const LOCK_DIR = '.dw/cache/agents';
+const LOCK_FILE = 'claim.lock';
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_POLL_MS = 50;
+
+function acquireClaimLock(rootDir) {
+  const dir = join(rootDir, LOCK_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const lockPath = join(dir, LOCK_FILE);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let fd;
+  while (Date.now() < deadline) {
+    try {
+      fd = openSync(lockPath, 'wx');
+      return { fd, path: lockPath };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const wait = LOCK_POLL_MS + Math.floor(Math.random() * 50);
+      const end = Date.now() + wait;
+      while (Date.now() < end) { /* busy wait — node has no sync sleep */ }
+    }
+  }
+  return { fd: null, path: lockPath, timedOut: true };
+}
+
+function releaseClaimLock(lock) {
+  if (!lock || lock.fd === null) return;
+  try { closeSync(lock.fd); } catch { /* ignore */ }
+  try { unlinkSync(lock.path); } catch { /* ignore */ }
+}
+
+function parseList(value) {
+  if (!value) return [];
+  return String(value).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+function parseLease(s) {
+  const m = String(s || '').match(/^(\d+)([smhd]?)$/i);
+  if (!m) return 3600;
+  const n = parseInt(m[1], 10);
+  const unit = (m[2] || 's').toLowerCase();
+  const mult = { s: 1, m: 60, h: 3600, d: 86400 }[unit];
+  return n * mult;
+}
+
+export async function agentClaimCommand(taskId, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (!taskId) {
+    console.error(chalk.red('✗ Task ID required: dw agent claim <task-id> --subtasks ST-1,ST-2 --write src/foo.js'));
+    process.exit(1);
+  }
+  if (!existsSync(join(rootDir, '.dw/tasks', taskId, 'task.md'))) {
+    console.error(chalk.red(`✗ No v3 task at .dw/tasks/${taskId}/task.md`));
+    process.exit(1);
+  }
+
+  const subtasks = parseList(opts.subtasks);
+  if (subtasks.length === 0) {
+    console.error(chalk.red('✗ --subtasks required (e.g. --subtasks ST-1,ST-2)'));
+    process.exit(1);
+  }
+
+  const role = opts.role || 'worker';
+  const writeScope = parseList(opts.write);
+  const readScope = parseList(opts.read);
+  const leaseSeconds = parseLease(opts.lease || '1h');
+
+  if (role !== 'reader' && writeScope.length === 0) {
+    console.error(chalk.red('✗ --write required for non-reader roles (e.g. --write "src/foo.js,test/**")'));
+    process.exit(1);
+  }
+
+  const agentId = opts.agent || process.env.DW_AGENT_ID || `${opts.vendor || 'claude'}-${Date.now().toString(36)}-${randomBytes(2).toString('hex')}`;
+  const vendor = opts.vendor || 'claude';
+
+  const claim = createClaim({
+    taskId,
+    agent: { id: agentId, vendor, role },
+    subtasks,
+    writeScope,
+    readScope,
+    leaseSeconds,
+    worktreePath: opts.worktree || null,
+  }, rootDir);
+
+  const v = validateClaim(claim, rootDir);
+  if (!v.ok) {
+    console.error(chalk.red('✗ Schema validation failed:'));
+    for (const e of v.errors) console.error(chalk.red(`  ${e.path}: ${e.message}`));
+    process.exit(1);
+  }
+
+  // R2-1 + reviewer Critical #2: acquire exclusive lock around overlap-check + persist
+  // to close the TOCTOU window between two concurrent `dw agent claim` invocations.
+  const lock = acquireClaimLock(rootDir);
+  if (lock.timedOut) {
+    console.error(chalk.red(`✗ Could not acquire claim lock (${lock.path}) within ${LOCK_TIMEOUT_MS}ms.`));
+    console.error(chalk.dim('  Another `dw agent claim` may be running. Retry, or stale-remove the lock file.'));
+    process.exit(1);
+  }
+  let target;
+  try {
+    const wouldConflict = checkOverlapAgainstActive(claim, rootDir);
+    if (wouldConflict.length && !opts.force) {
+      console.error(chalk.red(`✗ Claim would overlap ${wouldConflict.length} existing active claim(s):`));
+      for (const c of wouldConflict) {
+        console.error(chalk.red(`  - ${c.claim_id} (agent: ${c.agent_id}, overlap: ${c.reason})`));
+      }
+      console.error(chalk.dim('  Use --force to claim anyway, or release the conflicting claim first.'));
+      releaseClaimLock(lock);
+      process.exit(1);
+    }
+    target = persistClaim(claim, rootDir);
+  } finally {
+    releaseClaimLock(lock);
+  }
+  logAgentEvent(taskId, {
+    event: 'claim_created',
+    claim_id: claim.claim_id,
+    agent_id: agentId,
+    vendor,
+    role,
+    subtasks,
+    write_scope: writeScope,
+    lease_expires: claim.lease_expires,
+  }, rootDir);
+  logTelemetry({ event: 'agent', action: 'claim.create', name: taskId, vendor, role }, rootDir);
+
+  console.log();
+  console.log(chalk.green('✓') + ` Claim created: ${chalk.cyan(claim.claim_id)}`);
+  console.log(chalk.dim(`  file: ${target}`));
+  console.log(chalk.dim(`  task: ${taskId}`));
+  console.log(chalk.dim(`  agent: ${agentId} (${vendor}/${role})`));
+  console.log(chalk.dim(`  subtasks: ${subtasks.join(', ')}`));
+  console.log(chalk.dim(`  write_scope: ${writeScope.join(', ') || '(read-only)'}`));
+  console.log(chalk.dim(`  lease_expires: ${claim.lease_expires} (in ${leaseSeconds}s)`));
+  console.log();
+  console.log(chalk.dim('  Next: write your changes, then `dw agent release ' + claim.claim_id + '` when done.'));
+  console.log();
+}
+
+function checkOverlapAgainstActive(newClaim, rootDir) {
+  // Reviewer Warning #3: write_scope collisions must be detected REPO-WIDE,
+  // not just within the same task. Subtask overlap remains task-scoped (IDs only
+  // meaningful within a single task).
+  const allActive = listClaims(rootDir).filter((c) => {
+    const ls = c._live_status;
+    return ls === 'created' || ls === 'active';
+  });
+
+  const conflicts = [];
+  for (const e of allActive) {
+    const sameTask = e.task_id === newClaim.task_id;
+    const subtaskOverlap = sameTask
+      ? newClaim.subtasks.filter((s) => e.subtasks.includes(s))
+      : [];
+    const writeOverlap = [];
+    for (const pa of newClaim.write_scope) {
+      for (const pb of e.write_scope) {
+        if (scopesOverlap(pa, pb)) writeOverlap.push({ new: pa, existing: pb });
+      }
+    }
+    if (subtaskOverlap.length || writeOverlap.length) {
+      const reasons = [];
+      if (subtaskOverlap.length) reasons.push(`subtasks ${subtaskOverlap.join(',')}`);
+      if (writeOverlap.length) reasons.push(`write scope ${writeOverlap.map((o) => o.existing).join(',')}`);
+      if (!sameTask) reasons.push(`(cross-task: ${e.task_id})`);
+      conflicts.push({ claim_id: e.claim_id, agent_id: e.agent.id, reason: reasons.join('; ') });
+    }
+  }
+  return conflicts;
+}
+
+export async function agentReleaseCommand(claimId, opts = {}) {
+  const rootDir = process.cwd();
+  if (!claimId) {
+    console.error(chalk.red('✗ Claim ID required: dw agent release <claim-id>'));
+    process.exit(1);
+  }
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) {
+    console.error(chalk.red(`✗ Claim not found: ${claimId}`));
+    process.exit(1);
+  }
+  const result = transitionClaim(claimId, 'released', { reason: opts.reason }, rootDir);
+  if (!result.ok) {
+    console.error(chalk.red(`✗ Cannot release: ${result.reason}`));
+    process.exit(1);
+  }
+  logAgentEvent(claim.task_id, {
+    event: 'claim_released',
+    claim_id: claimId,
+    agent_id: claim.agent.id,
+    reason: opts.reason || 'clean exit',
+  }, rootDir);
+  logTelemetry({ event: 'agent', action: 'claim.release', name: claim.task_id }, rootDir);
+  console.log(chalk.green('✓') + ` Released: ${claimId}`);
+}
+
+export async function agentExpireCommand(claimId, opts = {}) {
+  const rootDir = process.cwd();
+  if (!claimId) {
+    console.error(chalk.red('✗ Claim ID required'));
+    process.exit(1);
+  }
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) {
+    console.error(chalk.red(`✗ Claim not found: ${claimId}`));
+    process.exit(1);
+  }
+  const status = opts.invalidate ? 'invalidated' : 'expired';
+  const result = transitionClaim(claimId, status, { reason: opts.reason || 'manual expire' }, rootDir);
+  if (!result.ok) {
+    console.error(chalk.red(`✗ Cannot ${status}: ${result.reason}`));
+    process.exit(1);
+  }
+  logAgentEvent(claim.task_id, {
+    event: status === 'invalidated' ? 'claim_invalidated' : 'claim_expired',
+    claim_id: claimId,
+    agent_id: claim.agent.id,
+    reason: opts.reason || 'manual',
+  }, rootDir);
+  logTelemetry({ event: 'agent', action: `claim.${status}`, name: claim.task_id }, rootDir);
+  console.log(chalk.yellow(`⚠ ${status}: ${claimId}`));
+}

package/src/commands/agent-inspect.mjs

@@ -0,0 +1,123 @@
+import chalk from 'chalk';
+import { listClaims, computeEffectiveExpiry } from '../lib/agent-claim.mjs';
+import { listReports } from '../lib/agent-report.mjs';
+import { detectClaimOverlaps } from '../lib/agent-conflict.mjs';
+import { logEvent as logTelemetry } from '../lib/telemetry.mjs';
+
+const STATUS_COLOR = {
+  created: chalk.cyan,
+  active: chalk.yellow,
+  released: chalk.green,
+  expired: chalk.red,
+  invalidated: chalk.magenta,
+};
+
+function fmtRel(iso) {
+  if (!iso) return '—';
+  const diff = Date.parse(iso) - Date.now();
+  const abs = Math.abs(diff) / 1000;
+  const unit = abs < 60 ? `${Math.round(abs)}s` : abs < 3600 ? `${Math.round(abs / 60)}m` : abs < 86400 ? `${Math.round(abs / 3600)}h` : `${Math.round(abs / 86400)}d`;
+  return diff < 0 ? `${unit} ago` : `in ${unit}`;
+}
+
+export async function agentClaimsCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const claims = listClaims(rootDir, {
+    taskId: opts.task,
+    status: opts.status,
+    includeStale: !!opts.all,
+  });
+
+  logTelemetry({ event: 'agent', action: 'claims.list', count: claims.length }, rootDir);
+
+  console.log();
+  if (claims.length === 0) {
+    console.log(chalk.dim(`  No claims found${opts.task ? ` for task ${opts.task}` : ''}.`));
+    console.log(chalk.dim('  Create one: `dw agent claim <task> --subtasks ST-1 --write src/foo.js`'));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.bold(`  ${claims.length} claim${claims.length === 1 ? '' : 's'}${opts.task ? ` for ${opts.task}` : ''}`));
+  console.log();
+
+  for (const c of claims) {
+    const liveStatus = c._live_status;
+    const colorFn = STATUS_COLOR[liveStatus] || chalk.white;
+    const effectiveExp = computeEffectiveExpiry(c);
+    const wallClockExp = Date.parse(c.lease_expires);
+    const usingRelative = effectiveExp > wallClockExp;
+
+    console.log(`  ${colorFn(`[${liveStatus.toUpperCase()}]`)} ${chalk.cyan(c.claim_id)}`);
+    console.log(`    task: ${c.task_id}`);
+    console.log(`    agent: ${c.agent.id} (${c.agent.vendor}/${c.agent.role})`);
+    console.log(`    subtasks: ${c.subtasks.join(', ')}`);
+    console.log(`    write_scope: ${c.write_scope.length ? c.write_scope.join(', ') : chalk.dim('(read-only)')}`);
+    console.log(`    lease: ${c.lease_expires} (${fmtRel(c.lease_expires)})${usingRelative ? chalk.dim(' [+relative fallback]') : ''}`);
+    if (c.released_at) console.log(`    released_at: ${c.released_at}${c.release_reason ? ' — ' + c.release_reason : ''}`);
+    if (c.worktree_path) console.log(`    worktree: ${c.worktree_path}`);
+    console.log();
+  }
+}
+
+export async function agentReportsCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const reports = listReports(rootDir, { taskId: opts.task, agentId: opts.agent });
+
+  logTelemetry({ event: 'agent', action: 'reports.list', count: reports.length }, rootDir);
+
+  console.log();
+  if (reports.length === 0) {
+    console.log(chalk.dim(`  No reports found${opts.task ? ` for task ${opts.task}` : ''}.`));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.bold(`  ${reports.length} report${reports.length === 1 ? '' : 's'}`));
+  console.log();
+
+  for (const r of reports) {
+    const sevColor = r.status === 'completed' ? chalk.green : r.status === 'needs-review' ? chalk.red : r.status === 'partial' ? chalk.yellow : chalk.dim;
+    console.log(`  ${sevColor(`[${(r.status || '?').toUpperCase()}]`)} ${chalk.cyan(r._file.split(/[\\/]/).pop())}`);
+    console.log(`    task: ${r._task} · agent: ${r.agent_id || '?'} (${r.vendor || '?'})`);
+    console.log(`    claim: ${r.claim_id || '?'}`);
+    if (r.subtasks_addressed && r.subtasks_addressed.length) console.log(`    subtasks: ${r.subtasks_addressed.join(', ')}`);
+    if (r.files_changed && r.files_changed.length) console.log(`    files: ${r.files_changed.slice(0, 5).join(', ')}${r.files_changed.length > 5 ? `, +${r.files_changed.length - 5} more` : ''}`);
+    if (r.files_outside_scope && r.files_outside_scope.length) console.log(chalk.red(`    out-of-scope: ${r.files_outside_scope.join(', ')}`));
+    if (r.open_questions && r.open_questions.length) console.log(chalk.yellow(`    open: ${r.open_questions[0]}${r.open_questions.length > 1 ? ` (+${r.open_questions.length - 1})` : ''}`));
+    console.log(chalk.dim(`    ${r.created_at || ''}`));
+    console.log();
+  }
+}
+
+export async function agentConflictsCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const conflicts = detectClaimOverlaps(rootDir, { taskId: opts.task });
+
+  logTelemetry({ event: 'agent', action: 'conflicts.check', count: conflicts.length }, rootDir);
+
+  console.log();
+  if (conflicts.length === 0) {
+    console.log(chalk.green('  ✓ No conflicts among active claims.'));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.red(`  ✗ ${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'} detected:`));
+  console.log();
+
+  for (const c of conflicts) {
+    console.log(`  ${chalk.cyan(c.claim_a)} (${c.agent_a})`);
+    console.log(`  ${chalk.cyan(c.claim_b)} (${c.agent_b})`);
+    console.log(`  task: ${c.task_id}`);
+    if (c.subtask_overlap.length) console.log(chalk.yellow(`  subtask overlap: ${c.subtask_overlap.join(', ')}`));
+    for (const w of c.write_overlap) {
+      console.log(chalk.red(`  write overlap: "${w.a}" ↔ "${w.b}"`));
+    }
+    console.log();
+  }
+
+  if (opts.strict !== false) {
+    process.exit(1);
+  }
+}

package/src/commands/doctor.mjs

@@ -191,6 +191,70 @@ export async function doctorCommand() {
     }
   }
 
+  info('Task Docs v3 (ADR-0008)');
+  const templateV3 = join(projectDir, '.dw/core/templates/v3/task.md');
+  const schemaV3 = join(projectDir, '.dw/core/schemas/task-frontmatter.schema.json');
+  if (existsSync(templateV3) && existsSync(schemaV3)) {
+    ok('v3 template + JSON schema present');
+  } else {
+    warn('v3 template/schema not in project — run `dw upgrade` or run from a v1.5+ project');
+    warnings++;
+  }
+  const tasksDir = join(projectDir, '.dw/tasks');
+  if (existsSync(tasksDir)) {
+    const fs = await import('node:fs');
+    const entries = fs.readdirSync(tasksDir).filter((e) => e !== 'archive' && e !== 'ACTIVE.md');
+    let v3 = 0, v2 = 0, v1 = 0, none = 0;
+    for (const e of entries) {
+      const p = join(tasksDir, e);
+      try {
+        if (!fs.statSync(p).isDirectory()) continue;
+        if (existsSync(join(p, 'task.md'))) v3++;
+        else if (existsSync(join(p, 'tracking.md'))) v2++;
+        else if (fs.readdirSync(p).some((f) => f.endsWith('-progress.md'))) v1++;
+        else none++;
+      } catch { /* skip */ }
+    }
+    log(`  Tasks       : ${v3} v3 · ${v2} v2 · ${v1} v1 · ${none} no-tracking`);
+    if (v2 > 0) {
+      log(`  ${v2} v2 task${v2 === 1 ? '' : 's'} can be migrated: \`dw task migrate --all --dry-run\``);
+    }
+  }
+
+  info('Agent OS (ADR-0009)');
+  const claimSchema = join(projectDir, '.dw/core/schemas/agent-claim.schema.json');
+  const reportSchema = join(projectDir, '.dw/core/schemas/agent-report.schema.json');
+  if (existsSync(claimSchema) && existsSync(reportSchema)) {
+    ok('Agent OS schemas (claim + report) present');
+  } else {
+    warn('Agent OS schemas not in project — run `dw upgrade` or use v1.6+ project');
+    warnings++;
+  }
+  const claimsDir = join(projectDir, '.dw/cache/agents/claims');
+  if (existsSync(claimsDir)) {
+    const fs = await import('node:fs');
+    const claimFiles = fs.readdirSync(claimsDir).filter((f) => f.endsWith('.json'));
+    let active = 0, expired = 0, released = 0;
+    const now = Date.now();
+    for (const f of claimFiles) {
+      try {
+        const c = JSON.parse(fs.readFileSync(join(claimsDir, f), 'utf8'));
+        const wallClock = Date.parse(c.lease_expires) || 0;
+        const relative = (Date.parse(c.created_at) || 0) + (c.lease_duration_seconds || 0) * 1000;
+        const effective = Math.max(wallClock, relative);
+        if (c.status === 'released' || c.status === 'invalidated') released++;
+        else if (effective < now) expired++;
+        else active++;
+      } catch { /* skip */ }
+    }
+    log(`  Claims      : ${active} active · ${expired} expired (not reaped) · ${released} released`);
+    if (expired > 0) {
+      log(`  Run \`dw agent claims --status expired\` to inspect; \`dw agent expire <id>\` to reap.`);
+    }
+  } else {
+    log('  Claims      : (no .dw/cache/agents/claims/ yet — first `dw agent claim` will initialize)');
+  }
+
   info('Supply-Chain Guard (ADR-0005, opt-in)');
   const sc = snapshotInfo(projectDir);
   if (!sc.exists) {

package/src/commands/lint-task.mjs

@@ -0,0 +1,112 @@
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import chalk from 'chalk';
+import yaml from 'js-yaml';
+import { lintTimeline, findAllTaskDirs } from '../lib/lint-rules.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+
+function getLintLevel(rootDir) {
+  try {
+    const cfgPath = join(rootDir, '.dw', 'config', 'dw.config.yml');
+    if (!existsSync(cfgPath)) return 'strict';
+    const cfg = yaml.load(readFileSync(cfgPath, 'utf8'), { schema: yaml.CORE_SCHEMA });
+    return cfg?.task?.lint ?? cfg?.task_lint ?? 'strict';
+  } catch {
+    return 'strict';
+  }
+}
+
+function severityColor(sev) {
+  if (sev === 'error') return chalk.red;
+  if (sev === 'warning') return chalk.yellow;
+  return chalk.dim;
+}
+
+function printViolations(taskDir, result) {
+  if (result.violations.length === 0) {
+    console.log(chalk.green(`  ✓  ${taskDir} — clean`));
+    return;
+  }
+  console.log();
+  console.log(chalk.bold(`  ${taskDir}`));
+  for (const v of result.violations) {
+    const sev = severityColor(v.severity)(`[${v.severity}]`);
+    const rule = chalk.dim(`(${v.rule})`);
+    const lineRef = v.line ? chalk.dim(`:${v.line}`) : '';
+    console.log(`    ${sev} ${v.message} ${rule}${lineRef}`);
+  }
+}
+
+export async function lintTaskCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+  const level = opts.level || getLintLevel(rootDir);
+
+  if (level === 'off') {
+    console.log(chalk.dim('  Task lint disabled (task_lint: off in dw.config.yml). Skipping.'));
+    return;
+  }
+
+  let targets;
+  if (taskName) {
+    targets = [join(rootDir, TASKS_DIR, taskName)];
+  } else {
+    targets = findAllTaskDirs(rootDir);
+  }
+
+  if (targets.length === 0) {
+    console.log(chalk.dim('  No v3 tasks to lint.'));
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold(`  Linting ${targets.length} task${targets.length === 1 ? '' : 's'} (level: ${level})`));
+
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalClean = 0;
+
+  for (const dir of targets) {
+    const result = lintTimeline(dir);
+    printViolations(dir, result);
+    const errs = result.violations.filter((v) => v.severity === 'error').length;
+    const warns = result.violations.filter((v) => v.severity === 'warning').length;
+    totalErrors += errs;
+    totalWarnings += warns;
+    if (result.violations.length === 0) totalClean++;
+
+    for (const v of result.violations) {
+      logEvent({
+        event: 'task',
+        action: 'lint.violation',
+        rule: v.rule,
+        severity: v.severity,
+      }, rootDir);
+    }
+  }
+
+  console.log();
+  const summary = `  ${totalClean} clean · ${totalWarnings} warnings · ${totalErrors} errors`;
+  if (totalErrors > 0) {
+    console.log(chalk.red(summary));
+  } else if (totalWarnings > 0) {
+    console.log(chalk.yellow(summary));
+  } else {
+    console.log(chalk.green(summary));
+  }
+  console.log();
+
+  logEvent({
+    event: 'task',
+    action: 'lint.run',
+    targets: targets.length,
+    errors: totalErrors,
+    warnings: totalWarnings,
+    level,
+  }, rootDir);
+
+  if (level === 'strict' && totalErrors > 0) {
+    process.exit(1);
+  }
+}