agentxchain 0.8.7 → 2.1.1

package/src/lib/schema.js

@@ -0,0 +1,189 @@
+/**
+ * Lightweight schema validation for AgentXchain protocol files.
+ * No external dependencies — validates shape and types only.
+ */
+
+export function validateLockSchema(data) {
+  const errors = [];
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['lock.json must be a JSON object'] };
+  }
+  if (!('holder' in data)) errors.push('Missing field: holder');
+  else if (data.holder !== null && typeof data.holder !== 'string') errors.push('holder must be a string or null');
+  if (!('turn_number' in data)) errors.push('Missing field: turn_number');
+  else if (typeof data.turn_number !== 'number' || !Number.isInteger(data.turn_number)) errors.push('turn_number must be an integer');
+  if (!('last_released_by' in data)) errors.push('Missing field: last_released_by');
+  else if (data.last_released_by !== null && typeof data.last_released_by !== 'string') errors.push('last_released_by must be a string or null');
+  if (!('claimed_at' in data)) errors.push('Missing field: claimed_at');
+  else if (data.claimed_at !== null && typeof data.claimed_at !== 'string') errors.push('claimed_at must be a string or null');
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateStateSchema(data) {
+  const errors = [];
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['state.json must be a JSON object'] };
+  }
+  if (typeof data.phase !== 'string') errors.push('phase must be a string');
+  if (typeof data.blocked !== 'boolean' && data.blocked !== undefined) errors.push('blocked must be a boolean');
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateGovernedStateSchema(data) {
+  const errors = [];
+  const VALID_RUN_STATUSES = ['idle', 'active', 'paused', 'blocked', 'completed', 'failed'];
+  const isV1_1 = data?.schema_version === '1.1';
+  const hasLegacyCurrentTurn = Object.prototype.hasOwnProperty.call(data || {}, 'current_turn');
+
+  function validateTurn(turn, label) {
+    if (typeof turn !== 'object' || Array.isArray(turn)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+
+    if (typeof turn.turn_id !== 'string' || !turn.turn_id.trim()) errors.push(`${label}.turn_id must be a non-empty string`);
+    if (typeof turn.assigned_role !== 'string' || !turn.assigned_role.trim()) errors.push(`${label}.assigned_role must be a non-empty string`);
+    if (typeof turn.status !== 'string' || !turn.status.trim()) errors.push(`${label}.status must be a non-empty string`);
+    if (typeof turn.runtime_id !== 'string' || !turn.runtime_id.trim()) errors.push(`${label}.runtime_id must be a non-empty string`);
+    if (typeof turn.attempt !== 'number' || !Number.isInteger(turn.attempt)) errors.push(`${label}.attempt must be an integer`);
+    if (isV1_1 && (!Number.isInteger(turn.assigned_sequence) || turn.assigned_sequence < 1)) {
+      errors.push(`${label}.assigned_sequence must be an integer >= 1`);
+    }
+  }
+
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['governed state must be a JSON object'] };
+  }
+
+  const hasRunId = typeof data.run_id === 'string' && data.run_id.trim();
+  const hasNoActiveTurn = isV1_1
+    ? data.active_turns && typeof data.active_turns === 'object' && !Array.isArray(data.active_turns)
+      ? Object.keys(data.active_turns).length === 0
+      : false
+    : data.current_turn === null;
+  const isUninitializedIdle = data.run_id === null && data.status === 'idle' && hasNoActiveTurn;
+  if (!hasRunId && !isUninitializedIdle) {
+    errors.push('run_id must be a non-empty string, or null only for an idle state with no active turn');
+  }
+  if (typeof data.project_id !== 'string' || !data.project_id.trim()) errors.push('project_id must be a non-empty string');
+  if (typeof data.status !== 'string' || !data.status.trim()) {
+    errors.push('status must be a non-empty string');
+  } else if (!VALID_RUN_STATUSES.includes(data.status)) {
+    errors.push(`status must be one of: ${VALID_RUN_STATUSES.join(', ')}`);
+  }
+  if (typeof data.phase !== 'string' || !data.phase.trim()) errors.push('phase must be a non-empty string');
+
+  if (isV1_1) {
+    if (hasLegacyCurrentTurn) {
+      errors.push('current_turn is not allowed when schema_version is "1.1"; use active_turns');
+    }
+    if (!data.active_turns || typeof data.active_turns !== 'object' || Array.isArray(data.active_turns)) {
+      errors.push('active_turns must be an object when schema_version is "1.1"');
+    } else {
+      for (const [turnId, turn] of Object.entries(data.active_turns)) {
+        validateTurn(turn, `active_turns.${turnId}`);
+      }
+    }
+    if (!Number.isInteger(data.turn_sequence) || data.turn_sequence < 0) {
+      errors.push('turn_sequence must be an integer >= 0 when schema_version is "1.1"');
+    }
+  } else if ('current_turn' in data && data.current_turn !== null) {
+    validateTurn(data.current_turn, 'current_turn');
+  }
+
+  if ('phase_gate_status' in data && data.phase_gate_status !== null && typeof data.phase_gate_status !== 'object') {
+    errors.push('phase_gate_status must be an object');
+  }
+  if ('budget_status' in data && data.budget_status !== null && typeof data.budget_status !== 'object') {
+    errors.push('budget_status must be an object');
+  }
+  if (isV1_1 && 'budget_reservations' in data && data.budget_reservations !== null && typeof data.budget_reservations !== 'object') {
+    errors.push('budget_reservations must be an object when provided');
+  }
+
+  if (data.status === 'blocked') {
+    if (typeof data.blocked_on !== 'string' || !data.blocked_on.trim()) {
+      errors.push('blocked_on must be a non-empty string when status is "blocked"');
+    }
+    if (!data.blocked_reason || typeof data.blocked_reason !== 'object') {
+      errors.push('blocked_reason must be an object when status is "blocked"');
+    } else {
+      if (typeof data.blocked_reason.category !== 'string' || !data.blocked_reason.category.trim()) {
+        errors.push('blocked_reason.category must be a non-empty string');
+      }
+      if (typeof data.blocked_reason.blocked_at !== 'string' || !data.blocked_reason.blocked_at.trim()) {
+        errors.push('blocked_reason.blocked_at must be a non-empty string');
+      }
+      if (!('turn_id' in data.blocked_reason) || (data.blocked_reason.turn_id !== null && typeof data.blocked_reason.turn_id !== 'string')) {
+        errors.push('blocked_reason.turn_id must be a string or null');
+      }
+      const recovery = data.blocked_reason.recovery;
+      if (!recovery || typeof recovery !== 'object') {
+        errors.push('blocked_reason.recovery must be an object');
+      } else {
+        if (typeof recovery.typed_reason !== 'string' || !recovery.typed_reason.trim()) errors.push('blocked_reason.recovery.typed_reason must be a non-empty string');
+        if (typeof recovery.owner !== 'string' || !recovery.owner.trim()) errors.push('blocked_reason.recovery.owner must be a non-empty string');
+        if (typeof recovery.recovery_action !== 'string' || !recovery.recovery_action.trim()) errors.push('blocked_reason.recovery.recovery_action must be a non-empty string');
+        if (typeof recovery.turn_retained !== 'boolean') errors.push('blocked_reason.recovery.turn_retained must be a boolean');
+        if ('detail' in recovery && recovery.detail !== null && typeof recovery.detail !== 'string') {
+          errors.push('blocked_reason.recovery.detail must be a string or null');
+        }
+      }
+    }
+  }
+
+  if (data.status === 'paused' && !data.pending_phase_transition && !data.pending_run_completion) {
+    errors.push('paused state must include pending_phase_transition or pending_run_completion');
+  }
+
+  if (data.status === 'active' && data.blocked_on != null) {
+    errors.push('active state must not include blocked_on');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateProjectStateSchema(data) {
+  if (data && typeof data === 'object' && ('run_id' in data || 'current_turn' in data || 'active_turns' in data || 'phase_gate_status' in data)) {
+    return validateGovernedStateSchema(data);
+  }
+  return validateStateSchema(data);
+}
+
+export function validateConfigSchema(data) {
+  const errors = [];
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['agentxchain.json must be a JSON object'] };
+  }
+  if (data.version !== 3) errors.push('version must be 3');
+  if (typeof data.project !== 'string' || !data.project.trim()) errors.push('project must be a non-empty string');
+  if (!data.agents || typeof data.agents !== 'object') {
+    errors.push('agents must be an object');
+  } else {
+    for (const [id, agent] of Object.entries(data.agents)) {
+      if (!/^[a-z0-9_-]+$/.test(id)) errors.push(`Invalid agent id: "${id}" (must be lowercase alphanumeric, hyphens, underscores)`);
+      if (!agent || typeof agent !== 'object') { errors.push(`Agent "${id}" must be an object`); continue; }
+      if (typeof agent.name !== 'string' || !agent.name.trim()) errors.push(`Agent "${id}": name must be a non-empty string`);
+      if (typeof agent.mandate !== 'string' || !agent.mandate.trim()) errors.push(`Agent "${id}": mandate must be a non-empty string`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Safely parse JSON with schema validation.
+ * Returns { ok, data, errors }.
+ */
+export function safeParseJson(raw, validator) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, data: null, errors: [`Invalid JSON: ${err.message}`] };
+  }
+  if (validator) {
+    const result = validator(data);
+    return { ok: result.ok, data, errors: result.errors };
+  }
+  return { ok: true, data, errors: [] };
+}

package/src/lib/schemas/turn-result.schema.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentxchain.dev/schemas/turn-result/v1",
+  "title": "AgentXchain Turn Result v1",
+  "description": "Structured output produced by every agent turn. The orchestrator validates and accepts/rejects based on this contract.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "run_id",
+    "turn_id",
+    "role",
+    "runtime_id",
+    "status",
+    "summary",
+    "decisions",
+    "objections",
+    "files_changed",
+    "verification",
+    "artifact",
+    "proposed_next_role"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": "1.0",
+      "description": "Must be '1.0' for v1 turn results."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Must match the current run. Format: run_XXXX..."
+    },
+    "turn_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Must match the current turn assignment. Format: turn-NNNN"
+    },
+    "role": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]+$",
+      "description": "Must match the role assigned for this turn."
+    },
+    "runtime_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The runtime that executed this turn."
+    },
+    "status": {
+      "enum": ["completed", "blocked", "needs_human", "failed"],
+      "description": "Outcome of this turn."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable summary of what happened."
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "category", "statement", "rationale"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^DEC-\\d+$",
+            "description": "Decision ID, e.g. DEC-014"
+          },
+          "category": {
+            "enum": ["implementation", "architecture", "scope", "process", "quality", "release"]
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "objections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "statement"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^OBJ-\\d+$",
+            "description": "Objection ID, e.g. OBJ-007"
+          },
+          "severity": {
+            "enum": ["low", "medium", "high", "blocking"]
+          },
+          "against_turn_id": {
+            "type": "string",
+            "description": "Turn that this objection challenges."
+          },
+          "against_decision_id": {
+            "type": "string",
+            "description": "Decision ID being challenged."
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          },
+          "proposed_resolution": {
+            "type": "string"
+          },
+          "status": {
+            "enum": ["raised", "acknowledged", "resolved", "escalated", "resolved_by_human", "resolved_by_director"],
+            "default": "raised"
+          }
+        }
+      }
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths of files modified during this turn. Must match observed diff for authoritative runtimes."
+    },
+    "artifacts_created": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths of planning/review artifacts created (under .planning/ or .agentxchain/)."
+    },
+    "verification": {
+      "type": "object",
+      "required": ["status"],
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "enum": ["pass", "fail", "skipped"],
+          "description": "Raw status from agent. Orchestrator may normalize to attested_pass or not_reproducible."
+        },
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Verification commands that were run."
+        },
+        "evidence_summary": {
+          "type": "string",
+          "description": "Human-readable description of verification evidence."
+        },
+        "machine_evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["command", "exit_code"],
+            "properties": {
+              "command": { "type": "string" },
+              "exit_code": { "type": "integer" }
+            }
+          }
+        }
+      }
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "enum": ["workspace", "patch", "commit", "review"],
+          "description": "workspace = direct local changes, patch = unified diff, commit = git commit, review = no code changes"
+        },
+        "ref": {
+          "type": ["string", "null"],
+          "description": "Git SHA, patch path, or null for review-only."
+        },
+        "diff_summary": {
+          "type": "string"
+        }
+      }
+    },
+    "proposed_next_role": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]+$|^human$",
+      "description": "Role that should work next. Must be in routing allowlist or 'human'."
+    },
+    "phase_transition_request": {
+      "type": ["string", "null"],
+      "description": "If the agent believes the phase should advance, name the target phase."
+    },
+    "run_completion_request": {
+      "type": ["boolean", "null"],
+      "description": "Set to true only in the final phase when the run should complete. Mutually exclusive with phase_transition_request."
+    },
+    "needs_human_reason": {
+      "type": ["string", "null"],
+      "description": "If status is needs_human, explain why."
+    },
+    "cost": {
+      "type": "object",
+      "properties": {
+        "input_tokens": { "type": "integer", "minimum": 0 },
+        "output_tokens": { "type": "integer", "minimum": 0 },
+        "usd": { "type": "number", "minimum": 0 }
+      }
+    }
+  }
+}

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

@@ -1,59 +1,20 @@
-export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '.') {
-  const logFile = config.log || 'log.md';
-  const talkFile = config.talk_file || 'TALK.md';
-  const maxClaims = config.rules?.max_consecutive_claims || 2;
-  const verifyCmd = config.rules?.verify_command || null;
-  const stateFile = config.state_file || 'state.md';
-  const historyFile = config.history_file || 'history.jsonl';
-  const useSplit = config.state_file || config.history_file;
+import {
+  buildReadSection,
+  buildWriteSection,
+  buildVerifySection,
+  buildRulesSection,
+  buildPlanningDocsSection,
+} from './prompt-core.js';
 
+export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '.') {
   const agentIds = Object.keys(config.agents);
   const myIndex = agentIds.indexOf(agentId);
 
-  const readSection = useSplit
-    ? `READ THESE FILES:
-- "${stateFile}" — the living project state. Read fully. Primary context.
-- "${historyFile}" — turn history. Read last 3 lines for recent context.
-- "${talkFile}" — team handoff updates. Read the latest 5 entries.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`
-    : `READ THESE FILES:
-- "${logFile}" — the message log. Read last few messages.
-- "${talkFile}" — team handoff updates. Read the latest 5 entries.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`;
-
-  const writeSection = useSplit
-    ? `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Update "${stateFile}" — OVERWRITE with current project state.
-c. Append ONE line to "${historyFile}":
-   {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
-d. Append ONE handoff entry to "${talkFile}" with:
-   Turn, Status, Decision, Action, Risks/Questions, Next owner.
-   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].
-e. Update state.json if phase or blocked status changed.`
-    : `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Append ONE message to ${logFile}:
-   ---
-   ### [${agentId}] (${agentDef.name}) | Turn N
-   **Status:** Current project state.
-   **Decision:** What you decided and why.
-   **Action:** What you did. Commands, files, results.
-   **Next:** What the next agent should focus on.
-c. Append ONE handoff entry to "${talkFile}" with:
-   Turn, Status, Decision, Action, Risks/Questions, Next owner.
-   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].
-d. Update state.json if phase or blocked status changed.`;
-
-  const verifySection = verifyCmd
-    ? `
-VERIFY (mandatory before release):
-Run: ${verifyCmd}
-If it FAILS: fix the problem. Run again. Do NOT release with failing verification.
-If it PASSES: report the result. Then release.`
-    : '';
+  const readSection = buildReadSection(config, { includeTalk: true });
+  const writeSection = buildWriteSection(agentId, agentDef, config, { includeTalk: true });
+  const verifySection = buildVerifySection(config);
+  const rulesSection = buildRulesSection(agentId, config);
+  const planningDocs = buildPlanningDocsSection();
 
   return `You are "${agentId}" — ${agentDef.name}.
 
@@ -70,22 +31,7 @@ PROJECT ROOT (strict boundary):
 
 ---
 
-PROJECT DOCUMENTATION (.planning/ folder):
-
-These files give you project context. Read the ones relevant to your role.
-
-- .planning/PROJECT.md — Vision, constraints, stack decisions. PM writes this.
-- .planning/REQUIREMENTS.md — Scoped requirements with acceptance criteria. PM writes this.
-- .planning/ROADMAP.md — Phased delivery plan. PM maintains this.
-- .planning/research/ — Domain research, prior art, technical investigation.
-- .planning/phases/ — Per-phase plans (PLAN.md), reviews (REVIEW.md), test results (TESTS.md), bugs (BUGS.md).
-- .planning/qa/TEST-COVERAGE.md — Which features are tested and how. QA maintains this.
-- .planning/qa/BUGS.md — Open and fixed bugs with reproduction steps. QA maintains this.
-- .planning/qa/UX-AUDIT.md — UX checklist and visual/usability issues. QA maintains this.
-- .planning/qa/ACCEPTANCE-MATRIX.md — Requirements mapped to test status. QA maintains this.
-- .planning/qa/REGRESSION-LOG.md — Fixed bugs and their regression tests.
-
-When your role requires it, CREATE or UPDATE these files.
+${planningDocs}
 
 GET SHIT DONE FRAMEWORK (mandatory):
 - Plan in waves and phases (not ad hoc tasks).
@@ -140,10 +86,6 @@ TURN MODE (single turn only, referee wakes you again later):
 ---
 
 CRITICAL RULES:
-- Never write files or code without holding the lock. Reading is always allowed.
-- One git commit per turn: "Turn N - ${agentId} - description"
-- Max ${maxClaims} consecutive turns. If you have held the lock ${maxClaims} times in a row, do a short turn and release.
-- ALWAYS release the lock. A stuck lock blocks the entire team.
-- ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.
+${rulesSection}
 - This session is SINGLE-TURN. After release, STOP and wait for the referee to wake you again.`;
 }

package/src/lib/seed-prompt.js

@@ -1,46 +1,17 @@
-export function generateSeedPrompt(agentId, agentDef, config) {
-  const logFile = config.log || 'log.md';
-  const maxClaims = config.rules?.max_consecutive_claims || 2;
-  const verifyCmd = config.rules?.verify_command || null;
-  const stateFile = config.state_file || 'state.md';
-  const historyFile = config.history_file || 'history.jsonl';
-  const useSplit = config.state_file || config.history_file;
-
-  const stateSection = useSplit
-    ? `READ THESE FILES EVERY TURN:
-- "${stateFile}" — the living project state. Read fully. Primary context.
-- "${historyFile}" — turn history. Read last 3 lines for recent context.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`
-    : `READ THESE FILES EVERY TURN:
-- "${logFile}" — the message log. Read last few messages.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`;
-
-  const writeSection = useSplit
-    ? `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Update "${stateFile}" — OVERWRITE with current project state.
-c. Append ONE line to "${historyFile}":
-   {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
-d. Update state.json if phase or blocked status changed.`
-    : `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Append ONE message to ${logFile}:
-   ---
-   ### [${agentId}] (${agentDef.name}) | Turn N
-   **Status:** Current project state.
-   **Decision:** What you decided and why.
-   **Action:** What you did. Commands, files, results.
-   **Next:** What the next agent should focus on.
-c. Update state.json if phase or blocked status changed.`;
+import {
+  buildReadSection,
+  buildWriteSection,
+  buildVerifySection,
+  buildRulesSection,
+  buildPlanningDocsSection,
+} from './prompt-core.js';
 
-  const verifySection = verifyCmd
-    ? `\nVERIFY (mandatory):
-Before releasing the lock, run: ${verifyCmd}
-If it FAILS: fix the problem. Run again. Do NOT release with failing verification.
-If it PASSES: report the result. Then release.`
-    : '';
+export function generateSeedPrompt(agentId, agentDef, config) {
+  const readSection = buildReadSection(config);
+  const writeSection = buildWriteSection(agentId, agentDef, config);
+  const verifySection = buildVerifySection(config);
+  const rulesSection = buildRulesSection(agentId, config);
+  const planningDocs = buildPlanningDocsSection();
 
   return `You are "${agentId}" — ${agentDef.name}.
 
@@ -48,22 +19,9 @@ ${agentDef.mandate}
 
 ---
 
-PROJECT DOCUMENTATION (.planning/ folder):
-
-These files give you project context. Read the ones relevant to your role.
-
-- .planning/PROJECT.md — Vision, constraints, stack decisions. PM writes this.
-- .planning/REQUIREMENTS.md — Scoped requirements with acceptance criteria. PM writes this.
-- .planning/ROADMAP.md — Phased delivery plan. PM maintains this.
-- .planning/research/ — Domain research, prior art, technical investigation.
-- .planning/phases/ — Per-phase plans (PLAN.md), reviews (REVIEW.md), test results (TESTS.md), bugs (BUGS.md).
-- .planning/qa/TEST-COVERAGE.md — Which features are tested and how. QA maintains this.
-- .planning/qa/BUGS.md — Open and fixed bugs with reproduction steps. QA maintains this.
-- .planning/qa/UX-AUDIT.md — UX checklist and visual/usability issues. QA maintains this.
-- .planning/qa/ACCEPTANCE-MATRIX.md — Requirements mapped to test status. QA maintains this.
-- .planning/qa/REGRESSION-LOG.md — Fixed bugs and their regression tests.
+${planningDocs}
 
-When your role requires it, CREATE or UPDATE these files. The PM creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md on the first turn. QA creates phase test files and updates the qa/ docs every turn. Dev reads plans and writes code. Eng Director reads code and writes reviews.
+The PM creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md on the first turn. QA creates phase test files and updates the qa/ docs every turn. Dev reads plans and writes code. Eng Director reads code and writes reviews.
 
 ---
 
@@ -73,16 +31,12 @@ The AgentXchain Watch process coordinates your team. You don't poll or wait. Whe
 
 YOUR TURN:
 1. CLAIM: Write lock.json with holder="${agentId}", claimed_at=now. Re-read to confirm.
-2. READ: ${stateSection}
+2. READ: ${readSection}
 3. THINK: What did the previous agent do? What's most important for YOUR role? What's one risk?
 4. ${writeSection}${verifySection}
 5. RELEASE: Write lock.json: holder=null, last_released_by="${agentId}", turn_number=previous+1, claimed_at=null.
    THIS MUST BE THE LAST THING YOU WRITE.
 
 HARD RULES:
-- Never write without holding the lock.
-- One commit per turn: "Turn N - ${agentId} - description"
-- Max ${maxClaims} consecutive turns. If limit hit, do a short turn and release.
-- ALWAYS release the lock. A stuck lock kills the whole team.
-- ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.`;
+${rulesSection}`;
 }