agentxchain 2.1.1 → 2.2.0

package/README.md

@@ -8,11 +8,11 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 
 ## Docs
 
-- [Quickstart](https://agentxchain.dev/docs/quickstart.html)
-- [CLI reference](https://agentxchain.dev/docs/cli.html)
-- [Adapter reference](https://agentxchain.dev/docs/adapters.html)
-- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol.html)
-- [Why governed multi-agent delivery matters](https://agentxchain.dev/why.html)
+- [Quickstart](https://agentxchain.dev/docs/quickstart/)
+- [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Adapter reference](https://agentxchain.dev/docs/adapters/)
+- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
+- [Why governed multi-agent delivery matters](https://agentxchain.dev/why/)
 
 ## Install
 
@@ -90,6 +90,7 @@ agentxchain step
 | `approve-transition` | Approve a pending human-gated phase transition |
 | `approve-completion` | Approve a pending human-gated run completion |
 | `validate` | Validate governed kickoff wiring, a staged turn, or both |
+| `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the read-only governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives |
 | `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
 
@@ -124,6 +125,21 @@ agentxchain step
 4. The assigned role writes `.agentxchain/staging/<turn_id>/turn-result.json`.
 5. The orchestrator validates and either accepts, rejects, advances phase, pauses for approval, or completes the run.
 
+## Protocol Conformance
+
+AgentXchain ships a conformance kit under `.agentxchain-conformance/`. Use it to prove a runner or fork still implements the governed workflow contract:
+
+```bash
+agentxchain verify protocol --tier 3 --target .
+```
+
+Useful flags:
+
+- `--tier 1|2|3`: maximum conformance tier to verify
+- `--surface <name>`: isolate one surface such as `state_machine`, `dispatch_manifest`, or `coordinator`
+- `--format json`: emit a machine-readable report for CI
+- `--target <path>`: point at the root containing `.agentxchain-conformance/capabilities.json`
+
 Important governed files:
 
 ```text
@@ -175,10 +191,10 @@ Requires:
 ## Links
 
 - [agentxchain.dev](https://agentxchain.dev)
-- [Quickstart](https://agentxchain.dev/docs/quickstart.html)
-- [CLI reference](https://agentxchain.dev/docs/cli.html)
-- [Adapter reference](https://agentxchain.dev/docs/adapters.html)
-- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol.html)
+- [Quickstart](https://agentxchain.dev/docs/quickstart/)
+- [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Adapter reference](https://agentxchain.dev/docs/adapters/)
+- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
 - [GitHub](https://github.com/shivamtiwari93/agentXchain.dev)
 - [Legacy Protocol v3 spec](https://github.com/shivamtiwari93/agentXchain.dev/blob/main/PROTOCOL-v3.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/lib/reference-conformance-adapter.js

@@ -13,6 +13,9 @@ import { validateStagedTurnResult } from './turn-result-validator.js';
 import { finalizeDispatchManifest, verifyDispatchManifest } from './dispatch-manifest.js';
 import { getDispatchTurnDir } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
+import { validateCoordinatorConfig, normalizeCoordinatorConfig } from './coordinator-config.js';
+import { projectRepoAcceptance, evaluateBarriers } from './coordinator-acceptance.js';
+import { readBarriers, saveCoordinatorState, readCoordinatorHistory } from './coordinator-state.js';
 
 const VALID_DECISION_CATEGORIES = ['implementation', 'architecture', 'scope', 'process', 'quality', 'release'];
 const FULL_STAGE_PIPELINE = ['schema', 'assignment', 'artifact', 'verification', 'protocol'];
@@ -213,6 +216,69 @@ function materializeFixtureWorkspace(fixture) {
   };
 }
 
+// ── Tier 3: Multi-workspace materialization ─────────────────────────────────
+
+function materializeTier3Workspace(fixture) {
+  const root = mkdtempSync(join(tmpdir(), 'agentxchain-conformance-multi-'));
+  const setup = fixture.setup || {};
+
+  // Write coordinator config
+  if (setup.coordinator_config) {
+    writeJson(join(root, 'agentxchain-multi.json'), setup.coordinator_config);
+  }
+
+  // Materialize governed repo roots
+  for (const [repoId, repoSetup] of Object.entries(setup.repos || {})) {
+    const repoPath = join(root, repoSetup.path || `./repos/${repoId}`);
+    mkdirSync(join(repoPath, '.agentxchain'), { recursive: true });
+
+    // Write repo-local agentxchain.json
+    if (repoSetup.config) {
+      writeJson(join(repoPath, 'agentxchain.json'), repoSetup.config);
+    }
+
+    // Write repo-local state
+    if (repoSetup.state) {
+      const repoConfig = repoSetup.config || {};
+      const inflatedRepoConfig = inflateConfig(repoConfig);
+      const repoState = inflateState(repoSetup.state, inflatedRepoConfig);
+      writeJson(join(repoPath, '.agentxchain', 'state.json'), repoState);
+    }
+
+    // Write repo-local history
+    if (repoSetup.history) {
+      writeJsonl(join(repoPath, '.agentxchain', 'history.jsonl'), repoSetup.history);
+    }
+
+    // Write repo-local files
+    for (const [filePath, content] of Object.entries(repoSetup.files || {})) {
+      const absPath = join(repoPath, filePath);
+      mkdirSync(dirname(absPath), { recursive: true });
+      writeFileSync(absPath, content);
+    }
+  }
+
+  // Write coordinator multirepo state if provided
+  if (setup.coordinator_state || setup.barriers) {
+    const multiDir = join(root, '.agentxchain', 'multirepo');
+    mkdirSync(multiDir, { recursive: true });
+
+    if (setup.coordinator_state) {
+      writeJson(join(multiDir, 'state.json'), setup.coordinator_state);
+    }
+
+    if (setup.barriers) {
+      writeJson(join(multiDir, 'barriers.json'), setup.barriers);
+    }
+
+    // Write coordinator history
+    writeJsonl(join(multiDir, 'history.jsonl'), setup.coordinator_history || []);
+    writeJsonl(join(multiDir, 'barrier-ledger.jsonl'), setup.barrier_ledger || []);
+  }
+
+  return root;
+}
+
 function isAssertionObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value) && typeof value.assert === 'string';
 }
@@ -699,6 +765,74 @@ function executeFixtureOperation(workspace, fixture) {
   }
 }
 
+function executeTier3Operation(fixture) {
+  const root = materializeTier3Workspace(fixture);
+  try {
+    const operation = fixture.input.operation;
+
+    if (operation === 'validate_coordinator_config') {
+      const configPath = join(root, 'agentxchain-multi.json');
+      const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+      const validation = validateCoordinatorConfig(raw);
+      if (!validation.ok) {
+        const firstError = validation.errors[0] || '';
+        let errorType = 'invalid_coordinator_config';
+        if (firstError.startsWith('workstream_cycle:')) {
+          errorType = 'workstream_cycle';
+        }
+        return { result: 'error', error_type: errorType, errors: validation.errors };
+      }
+      return { result: 'success', errors: [] };
+    }
+
+    if (operation === 'project_repo_acceptance') {
+      const args = fixture.input.args;
+      const configPath = join(root, 'agentxchain-multi.json');
+      const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+      const normalized = normalizeCoordinatorConfig(raw);
+
+      // Resolve repo paths against the materialized workspace
+      for (const [repoId, repo] of Object.entries(normalized.repos)) {
+        const resolvedPath = join(root, repo.path);
+        normalized.repos[repoId] = { ...repo, resolved_path: resolvedPath };
+      }
+      normalized.repo_order = Object.keys(normalized.repos);
+
+      const stateDir = join(root, '.agentxchain', 'multirepo');
+      const state = JSON.parse(readFileSync(join(stateDir, 'state.json'), 'utf8'));
+
+      const projectionResult = projectRepoAcceptance(
+        root, state, normalized,
+        args.repo_id, args.accepted_turn, args.workstream_id,
+      );
+
+      if (!projectionResult.ok) {
+        let errorType = 'projection_failed';
+        if (projectionResult.error && projectionResult.error.includes('Cross-repo write violation')) {
+          errorType = 'cross_repo_write_violation';
+        }
+        return { result: 'error', error_type: errorType, error: projectionResult.error };
+      }
+
+      // Evaluate barriers after projection
+      const barrierResult = evaluateBarriers(root, state, normalized);
+
+      return {
+        result: 'success',
+        projection_ref: projectionResult.projection_ref,
+        barrier_effects: projectionResult.barrier_effects || [],
+        barrier_snapshot: Object.fromEntries(
+          Object.entries(barrierResult.barriers).map(([id, b]) => [id, { status: b.status }]),
+        ),
+      };
+    }
+
+    return { result: 'error', error_type: 'unsupported_operation', operation };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
 function compareActualToExpected(fixture, actual) {
   if (matchExpected(fixture.expected, actual)) {
     return buildPass(actual);
@@ -707,6 +841,13 @@ function compareActualToExpected(fixture, actual) {
 }
 
 export function runReferenceFixture(fixture) {
+  // Tier 3 fixtures use multi-workspace materialization; route before creating a Tier 1/2 workspace
+  const operation = fixture.input?.operation;
+  if (operation === 'validate_coordinator_config' || operation === 'project_repo_acceptance') {
+    const actual = executeTier3Operation(fixture);
+    return compareActualToExpected(fixture, actual);
+  }
+
   const workspace = materializeFixtureWorkspace(fixture);
   try {
     const actual = executeFixtureOperation(workspace, fixture);