@kontextmind/kxm 0.6.0

package/examples/vnext/.kxm/workflows/default.yaml

@@ -0,0 +1,92 @@
+schema: kxm.workflow.v1
+description: Minimal local plan, implement, verify, and summarize workflow.
+coordinator: coordinator
+limits:
+  maxTransitions: 8
+  maxRunDurationMs: 14400000
+  maxAgentTimeMs: 21600000
+steps:
+  - id: plan
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: plan
+        kind: artifact
+    timeoutMs: 1200000
+    on:
+      passed: implement
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: implement
+    kind: agent
+    agent: implementer
+    maxAttempts: 3
+    repositories:
+      control: read
+      api: write
+      web: write
+    assignments:
+      allowedAgents:
+        - implementer
+      minimum: 1
+      target: 1
+      maximum: 2
+      maxParallel: 1
+      maxAttemptsPerAssignment: 2
+      maxWriteRepositories: 1
+    requiredEvidence:
+      - key: implementation-diff
+        kind: artifact
+    timeoutMs: 3600000
+    on:
+      passed: verify
+      failed:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: verify
+    kind: gate
+    gate: test
+    maxAttempts: 3
+    repositories:
+      api: write
+      web: write
+    requiredEvidence:
+      - key: local-gates
+        kind: gate
+    timeoutMs: 3600000
+    on:
+      passed: ready
+      implementation-failure:
+        target: implement
+        maxTransitions: 3
+      failed:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: ready
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: summary
+        kind: assignment-result
+    timeoutMs: 900000
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      blocked:
+        target: $terminal
+        terminalStatus: failed

package/examples/vnext/.kxm/workflows/fix.yaml

@@ -0,0 +1,376 @@
+schema: kxm.workflow.v1
+description: Prove, plan, implement, independently review, verify, and prepare a local fix delivery.
+coordinator: coordinator
+limits:
+  maxTransitions: 28
+  maxRunDurationMs: 43200000
+  maxAgentTimeMs: 86400000
+  maxModelCost: 40
+  currency: USD
+reproOracle:
+  stageId: repro-review
+  evidenceKey: repro
+planHash:
+  stageId: final-plan
+  evidenceKey: plan
+requirePlanHash:
+  - implement
+  - local-verify
+  - delivery
+steps:
+  - id: intake
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    description: Classify expected and actual behavior, affected surfaces, and reproduction hints.
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: classification
+        kind: assignment-result
+    timeoutMs: 900000
+    on:
+      passed: repro-explore
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: repro-explore
+    kind: agent
+    agent: planner
+    maxAttempts: 3
+    description: Identify the reporter-path production callable and design a production-coupled reproduction.
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: diagnosis
+        kind: assignment-result
+    timeoutMs: 1800000
+    on:
+      passed: repro-write
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: repro-write
+    kind: agent
+    agent: reproducer
+    maxAttempts: 3
+    description: Write a failing test against the diagnosis-named production seam; production files remain unchanged.
+    repositories:
+      control: read
+      api: write
+      web: write
+    assignments:
+      allowedAgents:
+        - reproducer
+      minimum: 1
+      target: 1
+      maximum: 1
+      maxParallel: 1
+      maxAttemptsPerAssignment: 2
+      maxWriteRepositories: 1
+    requiredEvidence:
+      - key: repro
+        kind: artifact
+    timeoutMs: 3600000
+    on:
+      passed: repro-review
+      failed:
+        target: repro-write
+        maxTransitions: 2
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: repro-review
+    kind: moa
+    agent: critic-1
+    maxAttempts: 3
+    description: Verify reporter-path coupling, failure causality, expected behavior, and absence of production edits.
+    model:
+      tag: critic
+      capabilities:
+        - structured-output
+    repositories:
+      control: read
+      api: read
+      web: read
+    assignments:
+      allowedAgents:
+        - critic-1
+        - critic-2
+        - critic-3
+      minimum: 2
+      target: 3
+      maximum: 3
+      maxParallel: 3
+      maxAttemptsPerAssignment: 2
+      distinctBy:
+        - provider
+    join:
+      strategy: all-settled
+      minimumPassed: 2
+      cancelRemaining: false
+    requiredEvidence:
+      - key: repro
+        kind: artifact
+      - key: review
+        kind: assignment-result
+        producerPolicy:
+          minimumProducers: 2
+          eligibleAgents:
+            - critic-1
+            - critic-2
+          acceptedStatuses:
+            - passed
+    timeoutMs: 1800000
+    on:
+      passed: plan
+      repro_invalidated:
+        target: repro-write
+        maxTransitions: 3
+      quorum-not-met:
+        target: $terminal
+        terminalStatus: failed
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: plan
+    kind: agent
+    agent: planner
+    maxAttempts: 3
+    description: Plan the smallest change that makes the immutable reproduction pass.
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: plan
+        kind: artifact
+    timeoutMs: 1800000
+    on:
+      passed: critics
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: critics
+    kind: moa
+    agent: critic-1
+    maxAttempts: 3
+    description: Independently review the plan for correctness, scope, security, and regression risk.
+    model:
+      tag: critic
+      capabilities:
+        - structured-output
+    repositories:
+      control: read
+      api: read
+      web: read
+    assignments:
+      allowedAgents:
+        - critic-1
+        - critic-2
+        - critic-3
+      minimum: 2
+      target: 3
+      maximum: 3
+      maxParallel: 3
+      maxAttemptsPerAssignment: 2
+      distinctBy:
+        - provider
+    join:
+      strategy: all-settled
+      minimumPassed: 2
+      cancelRemaining: false
+    requiredEvidence:
+      - key: critique
+        kind: assignment-result
+        producerPolicy:
+          minimumProducers: 2
+          eligibleAgents:
+            - critic-1
+            - critic-2
+          acceptedStatuses:
+            - passed
+    timeoutMs: 1800000
+    on:
+      passed: final-plan
+      plan_invalidated:
+        target: plan
+        maxTransitions: 3
+      quorum-not-met:
+        target: $terminal
+        terminalStatus: failed
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: final-plan
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    description: Incorporate critique and capture the final immutable plan hash.
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: plan
+        kind: artifact
+    timeoutMs: 1200000
+    on:
+      passed: approval
+      plan_invalidated:
+        target: plan
+        maxTransitions: 2
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: approval
+    kind: approval
+    maxAttempts: 8
+    description: A human approves the hashed plan before implementation.
+    requiredEvidence:
+      - key: signoff
+        kind: approval
+    timeoutMs: 86400000
+    on:
+      passed: implement
+      rejected:
+        target: plan
+        maxTransitions: 3
+      cancelled:
+        target: $terminal
+        terminalStatus: cancelled
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: implement
+    kind: agent
+    agent: implementer
+    maxAttempts: 4
+    description: Implement only the approved plan while preserving the reproduction oracle.
+    repositories:
+      control: read
+      api: write
+      web: write
+    assignments:
+      allowedAgents:
+        - implementer
+      minimum: 1
+      target: 1
+      maximum: 2
+      maxParallel: 1
+      maxAttemptsPerAssignment: 2
+      maxWriteRepositories: 1
+    requiredEvidence:
+      - key: diff
+        kind: artifact
+      - key: repro
+        kind: artifact
+        reusableAcrossAttempts: true
+    timeoutMs: 3600000
+    on:
+      passed: local-verify
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: local-verify
+    kind: gate
+    gate: test
+    maxAttempts: 4
+    description: Run repository-defined gates and the unchanged reproduction oracle.
+    repositories:
+      api: write
+      web: write
+    requiredEvidence:
+      - key: gates
+        kind: gate
+      - key: repro
+        kind: artifact
+        reusableAcrossAttempts: true
+    timeoutMs: 3600000
+    on:
+      passed: delivery
+      implementation-failure:
+        target: implement
+        maxTransitions: 4
+      plan_invalidated:
+        target: plan
+        maxTransitions: 2
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: delivery
+    kind: gate
+    gate: scm-delivery
+    maxAttempts: 2
+    description: Create a unique run branch and pull request plus the non-atomic repository delivery manifest; never merge automatically.
+    repositories:
+      control: read
+      api: write
+      web: write
+    requiredEvidence:
+      - key: delivery-manifest
+        kind: artifact
+      - key: mr
+        kind: receipt
+    timeoutMs: 1800000
+    on:
+      passed: ci-watch
+      failed:
+        target: $terminal
+        terminalStatus: failed
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: ci-watch
+    kind: wait
+    signal: ci-review
+    maxAttempts: 6
+    description: Wait for required CI and review state using a receipt-queryable adapter.
+    requiredEvidence:
+      - key: ci
+        kind: receipt
+    timeoutMs: 86400000
+    on:
+      passed: ready-for-human-acceptance
+      failure:
+        target: implement
+        maxTransitions: 4
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: ready-for-human-acceptance
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    description: Summarize the oracle, approved plan hash, diff, gates, CI, and delivery receipts for final human acceptance.
+    repositories:
+      control: read
+      api: read
+      web: read
+    requiredEvidence:
+      - key: summary
+        kind: assignment-result
+    timeoutMs: 900000
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      blocked:
+        target: $terminal
+        terminalStatus: failed

package/examples/vnext/.kxm/workflows/improve.yaml

@@ -0,0 +1,57 @@
+schema: kxm.workflow.v1
+description: Propose improvements from telemetry routing records and create candidates.
+coordinator: coordinator
+limits:
+  maxTransitions: 8
+  maxRunDurationMs: 14400000
+  maxAgentTimeMs: 21600000
+steps:
+  - id: report
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    repositories:
+      control: read
+    requiredEvidence:
+      - key: candidate
+        kind: artifact
+    timeoutMs: 1200000
+    on:
+      passed: delivery
+      blocked:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: delivery
+    kind: gate
+    gate: scm-delivery
+    maxAttempts: 2
+    repositories:
+      api: write
+    requiredEvidence:
+      - key: delivery-manifest
+        kind: artifact
+    timeoutMs: 1800000
+    on:
+      passed: ready
+      failed:
+        target: $terminal
+        terminalStatus: failed
+
+  - id: ready
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    repositories:
+      control: read
+    requiredEvidence:
+      - key: summary
+        kind: assignment-result
+    timeoutMs: 900000
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      blocked:
+        target: $terminal
+        terminalStatus: failed

package/examples/vnext/README.md

@@ -0,0 +1,53 @@
+# KXM vNext complete project example
+
+> This is a planned-contract fixture used by configuration loader tests, not a
+> workflow activated or executed by the current v0.5 Runtime.
+
+The fixture demonstrates one authoritative project root, two member
+repositories, minimal individual resources, bounded dirty snapshots,
+provider-tagged models, an ordered workflow with typed back-edges, MOA join
+rules, and representative durable records.
+
+```text
+examples/vnext/
+├── .kxm/
+│   ├── project.yaml
+│   ├── agents/
+│   ├── models/
+│   ├── workflows/default.yaml
+│   ├── workflows/fix.yaml
+│   └── project/env.yaml
+├── repositories/
+│   ├── api/.kxm/repo/
+│   └── web/.kxm/repo/
+└── records/
+```
+
+Identity for agents, models, and workflows comes from the filename. For
+example, `.kxm/agents/reviewer.yaml` defines agent `reviewer`.
+
+The workflow is sequential at the top level:
+
+```text
+intake → repro-explore → repro-write → repro-review (MOA)
+                              ▲              │
+                              └── invalid ───┘
+  → plan → critics (MOA) → final-plan → approval
+     ▲           │                           │
+     └─ invalid ─┘                           ▼
+  → implement → local-verify → delivery → CI/review wait → ready
+        ▲              │                             │
+        └── failure ───┴─────────────────────────────┘
+```
+
+`default.yaml` is the no-MOA, local-only initial workflow. `fix.yaml` preserves
+the current `/fix` controls: an immutable reproduction oracle, approved-plan
+hash, required plan hash for mutation/delivery stages, bounded back-edges,
+producer policies, delivery receipt, and CI/review wait. The Runtime, not the
+coordinator, enforces transition, assignment, provider diversity, timeout, and
+join bounds.
+
+`test/contracts-vnext.test.ts` parses every YAML file and validates it plus the
+JSON records against `schemas/vnext`. Production loader tests copy the fixture
+to temporary control and member Git worktrees because committed fixtures cannot
+contain nested `.git` metadata.

package/examples/vnext/records/assignment-result-recorded.json

@@ -0,0 +1,63 @@
+{
+  "schema": "kxm.run-event.v1",
+  "eventId": "evt_01JRESULT00000000000000000",
+  "eventType": "assignment.result_recorded",
+  "projectId": "prj_01JPROJECT00000000000000000",
+  "runId": "run_01JRUN00000000000000000000",
+  "homeRuntimeId": "runtime_01JRUNTIME000000000000000",
+  "sequence": 24,
+  "commandId": "cmd_01JRESULTCOMMAND0000000000",
+  "occurredAt": "2026-09-01T22:12:10.000Z",
+  "recordedAt": "2026-09-01T22:12:10.003Z",
+  "monotonicNs": "6112234000000",
+  "configRevision": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+  "memoryRevision": "ctxrev_01JMEMORY0000000000000000",
+  "executorPolicyRevision": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
+  "toolPolicyRevision": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
+  "payload": {
+    "workflowId": "fix",
+    "status": "result_recorded",
+    "outcome": "implemented",
+    "resultClass": "outcome",
+    "summary": "Added single-flight token refresh and regression coverage.",
+    "stepId": "implement",
+    "stepAttempt": 1,
+    "assignmentId": "assignment_01JASSIGNMENT00000000000",
+    "attemptId": "attempt_01JATTEMPT0000000000000",
+    "agentId": "implementer",
+    "instanceNo": 1,
+    "scopeEpoch": 1,
+    "executor": {
+      "id": "local",
+      "kind": "local",
+      "executorVersion": "1.0.0",
+      "harness": "pi",
+      "harnessVersion": "0.84.4"
+    },
+    "model": {
+      "profile": "implementation",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4-6",
+      "tags": ["implementation"]
+    },
+    "evidenceRefs": [
+      {
+        "id": "evidence_01JEVIDENCE000000000000",
+        "kind": "test-result",
+        "hash": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+        "status": "passed"
+      }
+    ],
+    "timing": {
+      "durationMs": 730000,
+      "agentMs": 730000
+    },
+    "usage": {
+      "inputTokens": 18200,
+      "outputTokens": 3400,
+      "cost": 1.42,
+      "currency": "USD",
+      "costKind": "estimated"
+    }
+  }
+}

package/examples/vnext/records/assignment-result.json

@@ -0,0 +1,46 @@
+{
+  "schema": "kxm.assignment-result.v1",
+  "projectId": "prj_01JPROJECT00000000000000000",
+  "runId": "run_01JRUN00000000000000000000",
+  "stepId": "implement",
+  "stepAttempt": 1,
+  "assignmentId": "assignment_01JASSIGNMENT00000000000",
+  "attemptId": "attempt_01JATTEMPT0000000000000",
+  "status": "passed",
+  "outcome": "implemented",
+  "summary": "Added single-flight token refresh and production-coupled regression coverage.",
+  "evidenceRefs": [
+    {
+      "id": "evidence_01JEVIDENCE000000000000",
+      "kind": "test-result",
+      "hash": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+      "status": "passed"
+    }
+  ],
+  "repositoryOutputs": [
+    {
+      "repositoryId": "api",
+      "baseCommit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "contentSnapshotHash": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+      "outputCommit": "cccccccccccccccccccccccccccccccccccccccc",
+      "changes": {
+        "repositoryId": "api",
+        "added": ["test/Auth/RefreshConcurrencyTest.cs"],
+        "modified": ["src/Auth/RefreshService.cs"]
+      }
+    }
+  ],
+  "timing": {
+    "startedAt": "2026-09-01T22:00:00.000Z",
+    "finishedAt": "2026-09-01T22:12:10.000Z",
+    "durationMs": 730000,
+    "agentMs": 730000
+  },
+  "usage": {
+    "inputTokens": 18200,
+    "outputTokens": 3400,
+    "cost": 1.42,
+    "currency": "USD",
+    "costKind": "estimated"
+  }
+}