agentxchain 0.8.3 → 0.8.4

package/README.md

@@ -20,18 +20,9 @@ npx agentxchain init
 # 1. Create a project (interactive template selection)
 agentxchain init
 
-# 2. PM-first kickoff (human + PM align scope first)
+# 2. Run guided PM-first kickoff wizard
 cd my-project/
-agentxchain start --agent pm
-
-# 3. Launch remaining agents after planning is clear
-agentxchain start --remaining
-
-# 4. Start supervisor (watch + auto-nudge)
-agentxchain supervise --autonudge
-
-# 5. Release the human lock — agents start claiming turns
-agentxchain release
+agentxchain kickoff
 ```
 
 Each agent runs in its own Cursor window with a self-polling loop. Agents check `lock.json` every 60 seconds, claim when it's their turn, do their work, release, and go back to waiting. `supervise --autonudge` handles watch + nudging automatically.
@@ -41,9 +32,11 @@ Each agent runs in its own Cursor window with a self-polling loop. Agents check
 | Command | What it does |
 |---------|-------------|
 | `init` | Create project folder with agents, protocol files, and templates |
+| `kickoff` | Guided PM-first flow: PM kickoff, validate, launch remaining, release |
 | `start` | Open a Cursor window per agent + copy prompts to clipboard |
 | `supervise` | Run watcher and optional AppleScript auto-nudge together |
 | `generate` | Regenerate agent files from `agentxchain.json` |
+| `validate` | Enforce PM signoff + waves/phases + turn artifact schema |
 | `status` | Show lock holder, phase, turn number, agents |
 | `doctor` | Validate local setup (tools, trigger flow, accessibility checks) |
 | `claim` | Human takes control (agents stop claiming) |
@@ -64,9 +57,15 @@ agentxchain start --ide claude-code # Claude Code — spawns CLI processes
 ### Additional flags
 
 ```bash
+agentxchain kickoff                # guided first-run PM-first workflow
+agentxchain kickoff --ide vscode   # guided flow for VS Code mode
+agentxchain kickoff --send         # with Cursor auto-nudge auto-send enabled
+
 agentxchain start --agent pm        # launch only one specific agent
 agentxchain start --remaining       # launch all agents except PM (PM-first flow)
 agentxchain start --dry-run         # preview agents without launching
+agentxchain validate --mode kickoff # required before --remaining
+agentxchain validate --mode turn --agent pm
 agentxchain watch --daemon          # run watch in background
 agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
 agentxchain supervise --autonudge --send   # auto-press Enter after paste
@@ -110,14 +109,15 @@ Notes:
 - Grant Accessibility permissions to Terminal and Cursor
 - The script watches `.agentxchain-trigger.json`, which is written by `agentxchain watch`
 - `run-autonudge.sh` now requires watch to be running first
+- The script only nudges when it finds a unique matching agent window (no random fallback)
 
 ## How it works
 
 ### Cursor mode (default)
 
-1. `agentxchain start` opens a **separate Cursor window** for each agent
+1. `agentxchain kickoff` launches PM first for human-product alignment
 2. Each window gets a unique prompt copied to clipboard
-3. Recommended first-run flow: `start --agent pm` (kickoff), then `start --remaining`
+3. Kickoff validates PM signoff and launches remaining agents
 4. Agent prompts include a self-polling loop: read `lock.json` → check if it's my turn → claim → work → release → sleep 60s → repeat
 5. Agents know their rotation order from `agentxchain.json` and only claim when the previous agent released
 6. Human can `claim` to pause and `release` to resume anytime

package/bin/agentxchain.js

@@ -15,6 +15,8 @@ import { claimCommand, releaseCommand } from '../src/commands/claim.js';
 import { generateCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
+import { validateCommand } from '../src/commands/validate.js';
+import { kickoffCommand } from '../src/commands/kickoff.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -47,6 +49,15 @@ program
   .option('--dry-run', 'Print what would be launched without doing it')
   .action(startCommand);
 
+program
+  .command('kickoff')
+  .description('Guided PM-first first-run workflow')
+  .option('--ide <ide>', 'Target IDE: cursor, vscode, claude-code', 'cursor')
+  .option('--send', 'When using Cursor auto-nudge, auto-send nudges')
+  .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
+  .option('--no-autonudge', 'Skip auto-nudge supervisor prompt')
+  .action(kickoffCommand);
+
 program
   .command('stop')
   .description('Stop all running agent sessions')
@@ -102,4 +113,12 @@ program
   .description('Check local environment and first-run readiness')
   .action(doctorCommand);
 
+program
+  .command('validate')
+  .description('Validate Get Shit Done docs and QA protocol artifacts')
+  .option('--mode <mode>', 'Validation mode: kickoff, turn, full', 'full')
+  .option('--agent <id>', 'Expected agent for last history entry (turn mode)')
+  .option('-j, --json', 'Output as JSON')
+  .action(validateCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {

package/scripts/agentxchain-autonudge.applescript

@@ -58,7 +58,11 @@ on nudgeAgent(agentId, turnNum)
 
   tell application "Cursor" to activate
   delay 0.5
-  my focusAgentWindow(agentId)
+  set focusedOk to my focusAgentWindow(agentId)
+  if focusedOk is false then
+    do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
+    return
+  end if
   delay 0.2
 
   tell application "System Events"
@@ -85,23 +89,34 @@ on focusAgentWindow(agentId)
     tell process "Cursor"
       set frontmost to true
 
-      set didRaise to false
+      set matchedIndexes to {}
+      set idx to 0
       repeat with w in windows
+        set idx to idx + 1
         try
           set wn to name of w as text
-          if wn contains agentId then
-            perform action "AXRaise" of w
-            set didRaise to true
-            exit repeat
+          if my isStrongWindowMatch(wn, agentId) then
+            set end of matchedIndexes to idx
           end if
         end try
       end repeat
 
-      if didRaise is false then
+      if (count of matchedIndexes) = 1 then
         try
-          perform action "AXRaise" of window 1
+          set targetIndex to item 1 of matchedIndexes
+          perform action "AXRaise" of window targetIndex
+          return true
         end try
+      else if (count of matchedIndexes) > 1 then
+        return false
       end if
     end tell
   end tell
+  return false
 end focusAgentWindow
+
+on isStrongWindowMatch(windowName, agentId)
+  set tokenA to ".agentxchain-workspaces/" & agentId
+  if windowName contains tokenA then return true
+  return false
+end isStrongWindowMatch

package/src/adapters/cursor-local.js

@@ -171,8 +171,12 @@ Actions:
 - core workflow
 - MVP boundary
 - success metric
-3) Update planning docs with concrete acceptance criteria.
-4) Do NOT start round-robin agent handoffs yet.
+3) Update planning docs with concrete acceptance criteria and Get Shit Done structure:
+- .planning/ROADMAP.md must define Waves and Phases.
+- Create .planning/phases/phase-1/PLAN.md and TESTS.md.
+4) Update .planning/PM_SIGNOFF.md:
+- Set "Approved: YES" only when human agrees kickoff is complete.
+5) Do NOT start round-robin agent handoffs yet.
 
 Context:
 - Project: ${config.project}

package/src/commands/claim.js

@@ -1,4 +1,4 @@
-import { writeFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
@@ -36,6 +36,7 @@ export async function claimCommand(opts) {
     claimed_at: new Date().toISOString()
   };
   writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  clearBlockedState(root);
 
   console.log('');
   console.log(chalk.green(`  ✓ Lock claimed by ${chalk.bold('human')} (turn ${lock.turn_number})`));
@@ -74,9 +75,24 @@ export async function releaseCommand(opts) {
     claimed_at: null
   };
   writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  if (who === 'human') {
+    clearBlockedState(root);
+  }
 
   console.log('');
   console.log(chalk.green(`  ✓ Lock released by ${chalk.bold(who)} (turn ${newLock.turn_number})`));
   console.log(chalk.dim('  The Stop hook will coordinate the next agent turn in VS Code.'));
   console.log('');
 }
+
+function clearBlockedState(root) {
+  const statePath = join(root, 'state.json');
+  if (!existsSync(statePath)) return;
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (state.blocked || state.blocked_on) {
+      const next = { ...state, blocked: false, blocked_on: null };
+      writeFileSync(statePath, JSON.stringify(next, null, 2) + '\n');
+    }
+  } catch {}
+}

package/src/commands/doctor.js

@@ -3,6 +3,7 @@ import { execSync } from 'child_process';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
 
 export async function doctorCommand() {
   const result = loadConfig();
@@ -21,6 +22,7 @@ export async function doctorCommand() {
   checks.push(checkBinary('jq', 'jq installed (required for auto-nudge)'));
   checks.push(checkBinary('osascript', 'osascript available (required for auto-nudge, macOS)'));
   checks.push(checkPm(config));
+  checks.push(checkValidation(root, config));
   checks.push(checkWatchProcess());
   checks.push(checkTrigger(root));
   checks.push(checkAccessibility());
@@ -130,3 +132,15 @@ function checkAccessibility() {
     };
   }
 }
+
+function checkValidation(root, config) {
+  const validation = validateProject(root, config, { mode: 'kickoff' });
+  if (validation.ok) {
+    return { name: 'kickoff validation', level: 'pass', detail: 'PM signoff + waves/phases look ready' };
+  }
+  return {
+    name: 'kickoff validation',
+    level: 'warn',
+    detail: `Run \`agentxchain validate --mode kickoff\` (${validation.errors.length} issue(s))`
+  };
+}

package/src/commands/init.js

@@ -229,6 +229,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, '.planning', 'REQUIREMENTS.md'), `# Requirements — ${project}\n\n## v1 (MVP)\n\n(PM fills this: numbered list of requirements. Each requirement has one-sentence acceptance criteria.)\n\n| # | Requirement | Acceptance criteria | Phase | Status |\n|---|-------------|-------------------|-------|--------|\n| 1 | | | | Pending |\n\n## v2 (Future)\n\n(Out of scope for MVP. Captured here so they don't creep in.)\n\n## Out of scope\n\n(Explicitly not building.)\n`);
 
   writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
+  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${project}\n\nApproved: NO\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
 
   // QA structure
   writeFileSync(join(dir, '.planning', 'qa', 'TEST-COVERAGE.md'), `# Test Coverage — ${project}\n\n## Coverage Map\n\n| Feature / Area | Unit tests | Integration tests | E2E tests | Manual QA | UX audit | Status |\n|---------------|-----------|------------------|----------|----------|---------|--------|\n| (QA fills this as testing progresses) | | | | | | |\n\n## Coverage gaps\n\n(Areas with no tests or insufficient coverage.)\n`);
@@ -254,7 +255,7 @@ export async function initCommand(opts) {
   console.log(`    ${chalk.dim('├──')} state.json / state.md / history.jsonl`);
   console.log(`    ${chalk.dim('├──')} log.md / HUMAN_TASKS.md`);
   console.log(`    ${chalk.dim('├──')} .planning/`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PROJECT.md / REQUIREMENTS.md / ROADMAP.md`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PROJECT.md / REQUIREMENTS.md / ROADMAP.md / PM_SIGNOFF.md`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} research/ / phases/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} qa/  ${chalk.dim('TEST-COVERAGE / BUGS / UX-AUDIT / ACCEPTANCE-MATRIX')}`);
   console.log(`    ${chalk.dim('├──')} .github/agents/  ${chalk.dim(`(${agentCount} .agent.md files)`)}`);

package/src/commands/kickoff.js

@@ -0,0 +1,119 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { loadConfig } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
+import { startCommand } from './start.js';
+import { releaseCommand } from './claim.js';
+import { superviseCommand } from './supervise.js';
+
+export async function kickoffCommand(opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const pmId = pickPmAgentId(config);
+  const ide = opts.ide || 'cursor';
+
+  if (!pmId) {
+    console.log(chalk.red('No agents configured.'));
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Kickoff Wizard'));
+  console.log(chalk.dim(`  Project: ${config.project}`));
+  console.log(chalk.dim(`  PM agent: ${pmId}`));
+  console.log(chalk.dim(`  IDE: ${ide}`));
+  console.log('');
+
+  await startCommand({ ide, agent: pmId, remaining: false, dryRun: false });
+
+  console.log(chalk.cyan('  PM kickoff launched.'));
+  console.log(chalk.dim('  Discuss product scope with PM, then mark .planning/PM_SIGNOFF.md as Approved: YES.'));
+  console.log('');
+
+  const { readyForValidation } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'readyForValidation',
+    message: 'Is PM kickoff complete and signoff updated?',
+    default: false
+  }]);
+
+  if (!readyForValidation) {
+    console.log('');
+    console.log(chalk.yellow('  Kickoff paused.'));
+    console.log(chalk.dim('  Resume later with: agentxchain validate --mode kickoff && agentxchain start --remaining'));
+    console.log('');
+    return;
+  }
+
+  const validation = validateProject(root, config, { mode: 'kickoff' });
+  if (!validation.ok) {
+    console.log('');
+    console.log(chalk.red('  Kickoff validation failed.'));
+    for (const err of validation.errors) {
+      console.log(chalk.dim(`   - ${err}`));
+    }
+    if (validation.warnings.length > 0) {
+      console.log(chalk.yellow('  Warnings:'));
+      for (const warn of validation.warnings) {
+        console.log(chalk.dim(`   - ${warn}`));
+      }
+    }
+    console.log('');
+    console.log(chalk.bold('  Run: agentxchain validate --mode kickoff'));
+    console.log('');
+    process.exit(1);
+  }
+
+  console.log(chalk.green('  ✓ Kickoff validation passed.'));
+  console.log('');
+
+  await startCommand({ ide, remaining: true, agent: undefined, dryRun: false });
+
+  const { doRelease } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'doRelease',
+    message: 'Release human lock now so agents can start?',
+    default: true
+  }]);
+
+  if (doRelease) {
+    await releaseCommand({ force: false });
+  } else {
+    console.log(chalk.dim('  Lock remains with human. Run `agentxchain release` when ready.'));
+  }
+
+  if (ide === 'cursor' && opts.autonudge !== false) {
+    const { startSupervisor } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'startSupervisor',
+      message: 'Start supervisor with auto-nudge now?',
+      default: true
+    }]);
+
+    if (startSupervisor) {
+      await superviseCommand({
+        autonudge: true,
+        send: !!opts.send,
+        interval: opts.interval || '3'
+      });
+    } else {
+      console.log('');
+      console.log(chalk.dim('  Start later with: agentxchain supervise --autonudge'));
+      console.log('');
+    }
+  }
+}
+
+function pickPmAgentId(config) {
+  if (config.agents?.pm) return 'pm';
+  for (const [id, def] of Object.entries(config.agents || {})) {
+    const name = String(def?.name || '').toLowerCase();
+    if (name.includes('product manager')) return id;
+  }
+  return Object.keys(config.agents || {})[0] || null;
+}

package/src/commands/start.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
 
 export async function startCommand(opts) {
   const result = loadConfig();
@@ -30,6 +31,22 @@ export async function startCommand(opts) {
     process.exit(1);
   }
 
+  if (opts.remaining) {
+    const kickoffValidation = validateProject(root, config, { mode: 'kickoff' });
+    if (!kickoffValidation.ok) {
+      console.log(chalk.red('  PM kickoff is incomplete. Cannot run --remaining yet.'));
+      console.log(chalk.dim('  Fix these first:'));
+      for (const e of kickoffValidation.errors) {
+        console.log(chalk.dim(`   - ${e}`));
+      }
+      console.log('');
+      console.log(chalk.dim('  Suggested next step: complete .planning/PM_SIGNOFF.md and roadmap waves/phases, then run:'));
+      console.log(chalk.bold('    agentxchain validate --mode kickoff'));
+      console.log('');
+      process.exit(1);
+    }
+  }
+
   const launchConfig = buildLaunchConfig(config, opts);
   const launchAgentIds = Object.keys(launchConfig.agents || {});
   const launchCount = launchAgentIds.length;

package/src/commands/validate.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
+
+export async function validateCommand(opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const mode = opts.mode || 'full';
+  const validation = validateProject(root, config, {
+    mode,
+    expectedAgent: opts.agent || null
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(validation, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
+    console.log(chalk.dim('  ' + '─'.repeat(44)));
+    console.log(chalk.dim(`  Root: ${root}`));
+    console.log('');
+
+    if (validation.ok) {
+      console.log(chalk.green('  ✓ Validation passed.'));
+    } else {
+      console.log(chalk.red(`  ✗ Validation failed (${validation.errors.length} errors).`));
+    }
+
+    if (validation.errors.length > 0) {
+      console.log('');
+      console.log(chalk.red('  Errors:'));
+      for (const e of validation.errors) console.log(`    - ${e}`);
+    }
+
+    if (validation.warnings.length > 0) {
+      console.log('');
+      console.log(chalk.yellow('  Warnings:'));
+      for (const w of validation.warnings) console.log(`    - ${w}`);
+    }
+    console.log('');
+  }
+
+  if (!validation.ok) process.exit(1);
+}

package/src/commands/watch.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
+import { validateProject } from '../lib/validation.js';
 
 export async function watchCommand(opts) {
   if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
@@ -82,6 +83,20 @@ export async function watchCommand(opts) {
       }
 
       if (stateKey !== lastState) {
+        if (lock.last_released_by && config.agents?.[lock.last_released_by]) {
+          const validation = validateProject(root, config, {
+            mode: 'turn',
+            expectedAgent: lock.last_released_by
+          });
+          if (!validation.ok) {
+            log('warn', `Validation failed after ${lock.last_released_by}. Handing lock to HUMAN.`);
+            blockOnValidation(root, lock, config, validation);
+            sendNotification('Validation failed. Human action required: run agentxchain validate.');
+            lastState = null;
+            return;
+          }
+        }
+
         const next = pickNextAgent(lock, config);
         log('free', `Lock free (released by ${lock.last_released_by || 'none'}). Next: ${chalk.bold(next)}.`);
         writeTrigger(root, next, lock, config);
@@ -142,6 +157,41 @@ function writeTrigger(root, agentId, lock, config) {
   }, null, 2) + '\n');
 }
 
+function blockOnValidation(root, lock, config, validation) {
+  const lockPath = join(root, LOCK_FILE);
+  const newLock = {
+    holder: 'human',
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+
+  const statePath = join(root, 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const current = JSON.parse(readFileSync(statePath, 'utf8'));
+      const message = validation.errors[0] || 'Validation failed';
+      const nextState = {
+        ...current,
+        blocked: true,
+        blocked_on: `validation: ${message}`
+      };
+      writeFileSync(statePath, JSON.stringify(nextState, null, 2) + '\n');
+    } catch {}
+  }
+
+  const logFile = config.log || 'log.md';
+  const logPath = join(root, logFile);
+  if (existsSync(logPath)) {
+    const summary = validation.errors.map(e => `- ${e}`).join('\n');
+    appendFileSync(
+      logPath,
+      `\n---\n\n### [system] (Watch Validation) | Turn ${lock.turn_number}\n\n**Status:** Validation failed after ${lock.last_released_by}.\n\n**Action:** Lock assigned to human for intervention.\n\n**Errors:**\n${summary}\n\n`
+    );
+  }
+}
+
 function log(type, msg) {
   const time = new Date().toLocaleTimeString();
   const tags = {

package/src/lib/seed-prompt-polling.js

@@ -75,6 +75,14 @@ These files give you project context. Read the ones relevant to your role.
 
 When your role requires it, CREATE or UPDATE these files.
 
+GET SHIT DONE FRAMEWORK (mandatory):
+- Plan in waves and phases (not ad hoc tasks).
+- Keep .planning/ROADMAP.md updated with explicit Wave and Phase sections.
+- For every active phase, maintain:
+  - .planning/phases/phase-N/PLAN.md
+  - .planning/phases/phase-N/TESTS.md
+- QA must keep acceptance matrix and UX audit current with evidence, not placeholders.
+
 ---
 
 TEAM ROTATION: ${agentIds.join(' → ')} → (repeat)
@@ -108,6 +116,10 @@ YOUR LOOP (run forever, never exit, never say "I'm done"):
 
    ${writeSection}${verifySection}
 
+   VALIDATE (mandatory before release):
+   Run: agentxchain validate --mode turn --agent ${agentId}
+   If validation fails, fix docs/artifacts first. Do NOT release.
+
 5. RELEASE the lock:
    Write lock.json: {"holder":null,"last_released_by":"${agentId}","turn_number":<previous + 1>,"claimed_at":null}
    THIS MUST BE THE LAST FILE YOU WRITE.

package/src/lib/validation.js

@@ -0,0 +1,179 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+export function validateProject(root, config, opts = {}) {
+  const mode = opts.mode || 'full';
+  const expectedAgent = opts.expectedAgent || null;
+
+  const errors = [];
+  const warnings = [];
+
+  const mustExist = [
+    '.planning/PROJECT.md',
+    '.planning/REQUIREMENTS.md',
+    '.planning/ROADMAP.md',
+    '.planning/PM_SIGNOFF.md',
+    '.planning/qa/TEST-COVERAGE.md',
+    '.planning/qa/BUGS.md',
+    '.planning/qa/UX-AUDIT.md',
+    '.planning/qa/ACCEPTANCE-MATRIX.md',
+    '.planning/qa/REGRESSION-LOG.md',
+    'state.md',
+    'history.jsonl',
+    'lock.json',
+    'state.json'
+  ];
+
+  for (const rel of mustExist) {
+    if (!existsSync(join(root, rel))) {
+      errors.push(`Missing required file: ${rel}`);
+    }
+  }
+
+  const signoff = readText(root, '.planning/PM_SIGNOFF.md');
+  const signoffApproved = /approved\s*:\s*yes/i.test(signoff || '');
+  if (!signoffApproved) {
+    if (mode === 'kickoff' || mode === 'full') {
+      errors.push('PM signoff is not approved. Set "Approved: YES" in .planning/PM_SIGNOFF.md.');
+    } else {
+      warnings.push('PM signoff is not approved.');
+    }
+  }
+
+  const roadmap = readText(root, '.planning/ROADMAP.md') || '';
+  if (!/\bwave\b/i.test(roadmap)) {
+    errors.push('ROADMAP.md must define at least one Wave.');
+  }
+  if (!/\bphase\b/i.test(roadmap)) {
+    errors.push('ROADMAP.md must define at least one Phase.');
+  }
+
+  const phaseStatus = validatePhaseArtifacts(root);
+  errors.push(...phaseStatus.errors);
+  warnings.push(...phaseStatus.warnings);
+
+  const history = validateHistory(root, config, { expectedAgent, requireEntry: mode !== 'kickoff' });
+  errors.push(...history.errors);
+  warnings.push(...history.warnings);
+
+  const qaSignals = validateQaArtifacts(root);
+  warnings.push(...qaSignals.warnings);
+
+  return { ok: errors.length === 0, mode, errors, warnings };
+}
+
+function validatePhaseArtifacts(root) {
+  const result = { errors: [], warnings: [] };
+  const phasesDir = join(root, '.planning', 'phases');
+  if (!existsSync(phasesDir)) {
+    result.errors.push('Missing .planning/phases directory.');
+    return result;
+  }
+
+  const entries = safeReadDir(phasesDir).filter(name => !name.startsWith('.'));
+  if (entries.length === 0) {
+    result.errors.push('No phase artifacts found. Add .planning/phases/phase-*/PLAN.md and TESTS.md.');
+    return result;
+  }
+
+  let hasAnyPlan = false;
+  let hasAnyTests = false;
+  for (const name of entries) {
+    const plan = join(phasesDir, name, 'PLAN.md');
+    const tests = join(phasesDir, name, 'TESTS.md');
+    if (existsSync(plan)) hasAnyPlan = true;
+    if (existsSync(tests)) hasAnyTests = true;
+  }
+
+  if (!hasAnyPlan) result.errors.push('No phase PLAN.md found under .planning/phases/.');
+  if (!hasAnyTests) result.errors.push('No phase TESTS.md found under .planning/phases/.');
+  return result;
+}
+
+function validateHistory(root, config, opts) {
+  const result = { errors: [], warnings: [] };
+  const historyPath = join(root, 'history.jsonl');
+  if (!existsSync(historyPath)) {
+    result.errors.push('history.jsonl is missing.');
+    return result;
+  }
+
+  const lines = (readFileSync(historyPath, 'utf8') || '')
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(Boolean);
+
+  if (lines.length === 0) {
+    if (opts.requireEntry) {
+      result.errors.push('history.jsonl has no entries.');
+    } else {
+      result.warnings.push('history.jsonl has no entries yet.');
+    }
+    return result;
+  }
+
+  const lastRaw = lines[lines.length - 1];
+  let last;
+  try {
+    last = JSON.parse(lastRaw);
+  } catch {
+    result.errors.push('Last history.jsonl entry is not valid JSON.');
+    return result;
+  }
+
+  const requiredFields = ['turn', 'agent', 'summary', 'files_changed', 'verify_result', 'timestamp'];
+  for (const f of requiredFields) {
+    if (!(f in last)) result.errors.push(`Last history entry missing field: ${f}`);
+  }
+
+  if (last.agent && !config.agents?.[last.agent]) {
+    result.errors.push(`Last history agent "${last.agent}" is not in agentxchain.json.`);
+  }
+  if (!Array.isArray(last.files_changed)) {
+    result.errors.push('Last history entry: files_changed must be an array.');
+  }
+  if (last.verify_result && !['pass', 'fail', 'skipped'].includes(last.verify_result)) {
+    result.errors.push('Last history entry: verify_result must be pass|fail|skipped.');
+  }
+  if (opts.expectedAgent && last.agent !== opts.expectedAgent) {
+    result.errors.push(`Last history entry agent "${last.agent}" does not match expected "${opts.expectedAgent}".`);
+  }
+
+  return result;
+}
+
+function validateQaArtifacts(root) {
+  const result = { warnings: [] };
+  const checks = [
+    ['.planning/qa/TEST-COVERAGE.md', /\(QA fills this as testing progresses\)/i, 'TEST-COVERAGE.md still looks uninitialized'],
+    ['.planning/qa/ACCEPTANCE-MATRIX.md', /\(QA fills this from REQUIREMENTS\.md\)/i, 'ACCEPTANCE-MATRIX.md still looks uninitialized'],
+    ['.planning/qa/UX-AUDIT.md', /\(QA adds UX issues here\)/i, 'UX-AUDIT.md issues table appears unmodified']
+  ];
+
+  for (const [rel, placeholderRegex, message] of checks) {
+    const text = readText(root, rel);
+    if (text && placeholderRegex.test(text)) {
+      result.warnings.push(message);
+    }
+  }
+
+  return result;
+}
+
+function readText(root, rel) {
+  const path = join(root, rel);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function safeReadDir(path) {
+  try {
+    return readdirSync(path);
+  } catch {
+    return [];
+  }
+}