@kontextmind/kxm 0.6.0

package/docs/vnext/validation.md

@@ -0,0 +1,335 @@
+# Configuration and contract validation
+
+KXM uses deterministic validation for configuration, commands, events, and
+results. A model may explain an error but MUST NOT decide whether invalid input
+is accepted.
+
+## YAML parser profile
+
+YAML is parsed as a data format compatible with JSON Schema.
+
+Required parser restrictions:
+
+- one document per file;
+- custom tags disabled;
+- duplicate mapping keys rejected;
+- aliases disabled by default or bounded to a small implementation constant;
+- bounded document bytes, nesting depth, scalar length, collection length, and key count;
+- strings preserved as strings where the schema requires them;
+- no object construction or executable types.
+
+The `schema` field is required. For agent, model, and workflow files, identity is
+the normalized filename without `.yaml`; an in-document identity field is
+forbidden.
+
+## Validation pipeline
+
+### 1. Parse validation
+
+Reject malformed YAML, duplicate keys, forbidden tags, alias expansion, invalid
+UTF-8, and resource-limit violations.
+
+### 2. JSON Schema validation
+
+Validate against the exact schema identity under `schemas/vnext`. Unknown fields
+are rejected unless a schema explicitly defines an extension map.
+
+### 3. Path and identity validation
+
+- normalize to forward-slash repository-relative paths;
+- reject backslashes, traversal, absolute host paths, Windows device names,
+  destination-invalid characters, empty segments, and trailing dots/spaces in
+  portable configuration;
+- reject case-folding identity collisions;
+- reject Windows reserved names and destination-incompatible paths;
+- require path-derived IDs to match the canonical identifier grammar;
+- stop project discovery at the nearest Git worktree boundary and require the
+  authoritative project root to equal that boundary;
+- require every `required` repository binding to resolve an exact matching
+  `repo.yaml` at that repository's authoritative Git worktree root;
+- reject portable `pathHint` values whose existing components traverse a
+  symlink/junction or whose real path escapes the control project root;
+- treat out-of-tree member bindings as absolute Runtime-local input, never
+  portable YAML, while the control binding is always the project root;
+- persist explicit member bindings only after complete bundle validation in an
+  exact, bounded host record keyed by the canonical control-root path; reject
+  corrupt, linked, unknown, control-rebinding, or project-mismatched records.
+
+#### Managed-template reconciliation
+
+A project created by the built-in initializer records an exact, bounded
+`kxm.template-provenance.v1` manifest. SHA-256 covers the UTF-8/LF file bytes;
+comments and formatting therefore count as user edits. The separate authority
+hash excludes only names/descriptions/purpose prose and conservatively includes
+repository access, tools, network, secrets, executors, gates, assignment
+ceilings, synchronization, and other executable policy.
+
+For every managed path, three-way classification compares recorded baseline
+`B`, current local bytes `L`, and pinned target bytes `T`, with absence as a
+first-class value:
+
+| Condition | Class | Automatic action |
+|---|---|---|
+| `B = L = T` | `unchanged` | None |
+| `L = T`, while `B` differs | `converged` | None |
+| `L = B`, while `T` differs | `template-only` | Replace only when the authority hash is unchanged |
+| `T = B`, while `L` differs | `user-only` | Preserve exact local bytes |
+| Otherwise | `conflict` | Preserve and report |
+
+A new managed path or deletion requires review in this slice. Provenance-free
+projects remain valid when their resources are valid, but KXM MUST NOT infer a
+baseline or adopt their files automatically.
+
+Before repair changes any project file, it constructs and validates a bounded
+shadow bundle containing user-only bytes plus the proposed safe replacements.
+The fixed sibling transaction then pins an exact plan and target artifacts; it
+backs up every replacement preimage, checks each preimage again immediately
+before atomic file replacement, and installs provenance last. It carries no
+repository-binding authority: an explicit binding is validated and made durable
+in Runtime-local state before repair mutates Git resources. The reader
+re-derives every operation file, action, source, and target from the immutable
+supported-template registry, rather than trusting a self-hash. Recovery derives
+truth from destination hashes rather than trusting the recorded phase. A target
+already present is complete, a matching preimage is pending, and any third
+value blocks without overwrite. Repair moves a verified preimage aside and uses
+a same-directory hard link as a conditional no-replace install; a path recreated
+by a non-KXM writer is preserved and blocks repair. A filesystem without local
+hard-link support fails safely. Create keeps its same-volume directory rename.
+A newer process must finish the pinned transaction before planning another
+template revision.
+
+#### Legacy configuration migration
+
+`kxm migrate plan|apply|verify` converts legacy `.kxm/config` JSON into
+validated vNext resources with an exact receipt:
+
+- Legacy files are read with byte/depth/node bounds and token-level
+  duplicate-key rejection. Symbolic links and linked `workflows/` directories
+  are never traversed for authoritative bytes.
+- The deterministic `kxm.migration-plan.v1` binds every source file by
+  sha256/bytes plus a combined `sourceDigest`, lists target resources with
+  rendered content hashes, and enumerates every ambiguity as a stable decision
+  key with its allowed values: terminal status for each legacy `$terminal`
+  edge (legacy semantics completed the run even on failure outcomes), per-edge
+  budgets for unbounded back-edges, missing global transition budgets,
+  evidence-policy strengthening from `replied` to `passed`, foreign producer
+  identities, secret-field drops, unimplemented gates, and each narrowed
+  permission ceiling. Unrecognized or unmappable fields are preserved as
+  hashed `unmapped` entries; sensitive values are hashed, never copied.
+  Identity normalization that changes a name is an explicit `renames` entry
+  applied to all bound references; case-fold collisions fail closed.
+- Apply requires a reviewed `kxm.migration-decision.v1` (or programmatic
+  resolutions) binding the exact plan: project ID, project name, and source
+  digest. Unknown keys and values outside the allowed set fail closed before
+  any write. The complete target bundle must pass exact-schema and semantic
+  validation before installation; existing target paths are never overwritten.
+- Installation uses durable writes under the project mutation lock and finishes
+  with a self-hashed `kxm.migration-receipt.v1` binding source hashes, decision
+  digest, target configuration revision, and installed resource hashes. The
+  receipt keeps the legacy inputs read-only: `loadVnextProject` accepts mixed
+  trees only through a verified receipt, and any later legacy-source edit makes
+  loading and `migrate verify` fail closed. Re-apply is an idempotent no-op.
+- `plan`, `verify`, and every `--dry-run` path perform no writes, locks,
+  staging, backups, or Runtime-local state creation.
+
+`--dry-run` may parse and classify a transaction but MUST NOT create the writer
+mutex, state directories, staging, backups, temporary files, or cleanup. Live
+mutations use a SQLite immediate transaction so process death releases the
+writer lock; the durable initialization operation, not a PID/age heuristic,
+drives recovery.
+
+### 4. Cross-reference validation
+
+Resolve:
+
+- workflow agents;
+- model profiles and tags;
+- repository IDs;
+- gates and executors;
+- secret reference names;
+- transition targets;
+- evidence keys;
+- environment scopes.
+
+References resolve within the pinned configuration bundle, never from mutable
+process state. A step model selector is intersected with each eligible agent's
+model ceiling; the raw step selector never replaces that ceiling, and an empty
+intersection is invalid. Step tool policy must preserve the agent preset and
+all agent denials, and may only narrow an explicit allowlist. Portable `values`
+reject secret-bearing variable names and any value matching a registered secret
+or deterministic credential classifier; those values must use
+`secrets[].ref`.
+
+### 5. Workflow semantic validation
+
+Reject:
+
+- undeclared or nonexistent transition targets;
+- an unbounded cycle or missing effective step/assignment attempt ceiling;
+- a back-edge without global and per-edge bounds;
+- a transition capable of bypassing a required approval/gate;
+- impossible assignment minima, targets, maxima, or join rules;
+- impossible MOA diversity;
+- producer minima beyond the eligible assignment pool or evidence policy;
+- an oracle/plan-hash stage or evidence key that does not exist;
+- a mutation/delivery stage missing from `requirePlanHash` during migration of
+  an equivalent protected workflow;
+- `first-success` on a step that is not declared safe for speculation;
+- a coordinator, agent, model, or repository request exceeding a step ceiling;
+- terminal transitions without an explicit terminal run status.
+
+### 6. Capability validation
+
+Before a run starts, resolve and pin:
+
+- exact harness and executor versions;
+- exact model selections;
+- required provider authentication readiness;
+- tool preset versions;
+- repository bindings;
+- required LFS objects;
+- secret reference availability without reading values into configuration.
+
+A configured fallback is pinned only if selected before the first dispatch for
+that assignment. A failed live model session is not silently continued on a
+different model.
+
+### 7. Permission-diff validation
+
+Compare the new resolved bundle with the trusted revision. Flag increases in:
+
+- repository write scope;
+- tool or shell capability;
+- secret grants;
+- executor/network scope;
+- synchronization content;
+- shared external effects;
+- model-created assignment ceilings;
+- automatic delivery behavior.
+
+Permission expansion requires an explicit reviewed trust action. Formatting or
+description-only changes do not.
+
+#### Structured projections and the `kxm trust` gate
+
+The implemented workflow projects every resource into deterministic,
+field-addressed authority entries (`vnextAuthorityEntries`) covering the
+categories above, then diffs two complete bundles into a
+`kxm.permission-diff.v1` report. Every change is classified conservatively:
+
+- ordered lattices: repository access (`none` < `read` < `write`), network
+  (`none` < `provider-only` < `restricted` < `host`), snapshot untracked
+  content (`tracked-only` < `ask` < `bounded`);
+- budgets: raising any numeric limit expands; lowering narrows; mixed
+  directions expand;
+- evidence quorums: lowering `minimumProducers`, removing an eligible
+  producer, or introducing/lowering a degradation floor expands; raising the
+  quorum narrows; adding a producer without touching the floor is neutral;
+- secret grants: a new grant expands; removal narrows; making a grant
+  optional narrows, requiring one expands; any other grant change expands;
+- transitions, tools, executors, models, sync policy, gates, delivery, and
+  resource shape have no conservative order: any change expands and requires
+  review;
+- resource additions expand; removals narrow; prose-only changes
+  (name/description/purpose/instructions) surface as neutral and never
+  require review.
+
+`kxm trust diff [--base <rev>]` prints the report; `kxm trust check`
+(--base defaults to `HEAD`) exits non-zero when any expansion exists, so an
+authority-bearing change cannot merge without a reviewed Git change. Base
+revisions are pinned to their tree SHA once, materialized from Git into a
+temporary shadow with a sanitized environment (every member repository is
+resolved at the same revision in its own history; a member that does not
+resolve it fails closed with `trust_scope_unsupported`), and every Git tree
+entry is segment-validated and containment-checked before any write. Template
+repair blocks authority-bearing template updates and now enriches the
+`template_policy_review_required` issue with the exact field-level diff.
+
+### 8. Snapshot validation
+
+For every run:
+
+1. resolve the validated configuration bundle;
+2. compute `configRevision`;
+3. record each repository base commit;
+4. build the normalized dirty-content manifest;
+5. compute `contentSnapshotHash`;
+6. materialize the worktree;
+7. recompute and compare hashes before dispatch.
+
+A mismatch fails before agent execution.
+
+## Atomic editor save
+
+The CLI, standard TUI, and Pi editor use the same service:
+
+```text
+edit temporary file
+→ parse and validate resource
+→ validate complete project
+→ compute permission diff
+→ show resolved preview and Git diff
+→ atomically replace original
+```
+
+An invalid edit never replaces the original. Existing runs retain their pinned
+revision.
+
+## Schema evolution
+
+- Every document names an exact schema.
+- Readers reject schemas newer than their supported range.
+- Additive fields require explicit schema support; `additionalProperties` is
+  false by default.
+- Semantic changes require a new schema identity and migration.
+- Events are immutable; a correction appends a compensating event.
+- Projections record their schema and rebuild version.
+
+## Machine-verifiable fixture
+
+[`test/core/contracts-vnext.test.ts`](../../test/core/contracts-vnext.test.ts) parses the
+committed YAML example with the restricted parser profile and validates each
+resource plus representative event/result/delivery/candidate records against
+the committed JSON Schemas.
+
+## Gate registry foundation
+
+Projects with gate steps must declare `.kxm/gates.yaml`:
+
+```yaml
+schema: kxm.gate-registry.v1
+gates:
+  test:
+    kind: command
+    argv: [npm, test]
+    timeoutMs: 3600000
+  report:
+    kind: artifacts-exist
+    paths: [reviews/result.json]
+```
+
+Command definitions require literal `argv` (1–64 nonempty strings, each at
+most 4096 characters) and integer `timeoutMs` from 1 to 2147483647. The first
+argument must be a bare executable name or an absolute POSIX path; relative
+paths such as `./test.sh` and directory names `.` and `..` refuse. Optional
+`cwd` can only be `control`.
+`env`, `shell`, and undeclared fields refuse. Artifact paths use the shared
+portable relative-path grammar beneath `.kxm/assets`; `.` and traversal refuse.
+Artifact definitions have no timeout. `kind: reserved` registers an id without
+claiming executable support. Registries contain 1–64 named definitions.
+
+Workflow gate steps accept `expect: pass` (default) or `expect: fail`.
+Non-gate `expect` is invalid. Use `implementation-failure` and `repro-missing`
+for gate outcomes; their old underscore spellings are rejected. The former
+`registeredGates` caller option and `kxm.gates.v1` identity are also rejected.
+A project without gate steps may omit the registry.
+
+These are configuration and compilation contracts. Gate execution, artifact
+containment checks, timeout settlement, and attempt-bound evidence remain D3
+follow-up work; a valid definition does not mean the engine can execute it.
+Registry changes alter the full configuration/tool-policy hashes. Permission
+review treats only numeric timeout decreases as narrowing; other definition
+changes and removal of a gate or registry require review. Explicit default
+`expect: pass` is neutral. New projects use `v4-registry`; historical template
+bytes and provenance remain unchanged. Existing projects must explicitly
+review and add a registry before using gate workflows.

package/docs/webhook-workflows.md

@@ -0,0 +1,240 @@
+# Webhook workflows and long-lived agents
+
+KXM can turn a signed Jira, GitHub, or generic webhook into a durable prompt for a long-lived coordinator. The hub verifies the original request body, deduplicates provider retries, records the workflow before acknowledging it, and queues the prompt even when a previously registered coordinator is temporarily offline.
+
+## How the runtime behaves
+
+```text
+Jira webhook ── HMAC + delivery ID ──> Hub ── durable workflow + message
+                                             │
+                                             └── Pi coordinator
+                                                   ├── peer planning/review
+                                                   ├── checkpoints and retries
+                                                   ├── evidence journal
+                                                   ├── external wait ── signed result ──┐
+                                                   └── final result <── resumed prompt ─┘
+```
+
+The coordinator must register at least once before a webhook can target it. An unknown target returns HTTP 409, which causes Jira Cloud to retry. A known but offline target retains the queued workflow until it reconnects.
+
+The hub stores a SHA-256 payload hash and the rendered coordinator prompt, not the complete raw webhook body. Keep prompt templates narrow so they copy only the issue fields the agent needs.
+
+## Configure the Jira example
+
+The included [`jira-development.json`](../.kxm/config/workflows/jira-development.json) workspace configuration models this path:
+
+1. Jira issue enters **In Progress**.
+2. Reproduce the defect and create deterministic evidence.
+3. Plan with one agent or three independent strong planners, then synthesize their best ideas.
+4. Review and revise the plan.
+5. Implement with explicit ownership.
+6. Run lint, build/typecheck, security, and Playwright gates.
+7. Reproduce repository and CodeRabbit-style review gates.
+8. Update documentation.
+9. Push and watch required checks with `kxm gate github watch`; warnings and failures retry the same stage for correction until its attempt limit is exhausted.
+10. Merge only when policy and authorization allow it.
+11. Update Jira with links and evidence.
+12. Produce an evidence-backed improvement backlog.
+
+Load it without storing its secret in the JSON file:
+
+```powershell
+$env:JIRA_WEBHOOK_SECRET = "replace-with-a-high-entropy-secret"
+$env:WORKFLOW_SIGNAL_SECRET = "replace-with-a-separate-callback-secret"
+$env:KXM_WEBHOOK_WORKFLOWS_FILE = ".kxm/config/workflows/jira-development.json"
+kxm hub start
+```
+
+Configure Jira to send `jira:issue_updated` to:
+
+```text
+https://your-kxm-host.example/v1/webhooks/jira-development
+```
+
+Set the same secret when creating the Jira webhook. The endpoint requires `X-Hub-Signature` using SHA-256 and `X-Atlassian-Webhook-Identifier`. The stable delivery identifier makes Jira retries idempotent. Terminate TLS and restrict ingress before exposing the endpoint beyond a trusted network.
+
+Webhook authentication authorizes only workflow creation. The Jira-update stage requires a separate authorized Jira tool, MCP server, CLI, or automation callback in the coordinator's harness. Do not place Jira API credentials in the workflow definition or prompt.
+
+## Run a long-lived Pi coordinator
+
+Install the Pi package, then configure a stable identity that matches the workflow target:
+
+```powershell
+$env:KXM_SERVER_URL = "http://127.0.0.1:7331"
+$env:KXM_AUTH_TOKEN = "product-project-token"
+$env:KXM_PROJECT = "product"
+$env:KXM_AGENT_NAME = "coordinator"
+$env:KXM_AGENT_PURPOSE = "Coordinates Jira development workflows and quality gates"
+$env:KXM_WORKDIR = "D:\work\product-repository"
+kxm agent worker --session-isolation workflow
+```
+
+Workflow isolation is explicit during the upgrade-compatible release and begins fresh scoped storage on first use. The worker launches Pi in headless RPC mode, keeps stdin open, preserves its active bound session by default, and restarts with bounded exponential backoff. Run the worker itself under the operating system's service manager for boot startup, resource limits, log collection, and crash policy. Set `KXM_WORKER_CONTINUE=false` only when every process restart should create a fresh Pi session.
+
+## Workflow definition fields
+
+| Field | Meaning |
+|---|---|
+| `id` | URL-safe workflow identifier |
+| `source` | `jira`, `github`, or `generic` |
+| `project` | Hub project containing the coordinator |
+| `target` | Stable coordinator name or durable agent ID |
+| `secretEnv` | Environment variable containing the HMAC secret |
+| `signalSecretEnv` | Optional separate HMAC secret for external result callbacks |
+| `event` | Optional provider event filter |
+| `filter.path` / `filter.equals` | Optional exact JSON-path value filter |
+| `delivery` | `followUp` or `steer` |
+| `ttlMs` | Time allowed for the coordinator prompt |
+| `promptTemplate` | Prompt with `{{nested.payload.path}}` substitutions |
+| `stages` | Ordered gates with instructions, evidence requirements, and attempt limits |
+| `stages[].evidencePolicies` | Optional per-requirement peer provenance and quorum rules |
+
+Each stage may set `area` to route automatic warnings and failures into `harness`, `gates`, `implementation`, `workflow`, `documentation`, `security`, or `other`. It defaults to `workflow`.
+
+An `evidencePolicies` key must match one canonical `requiredEvidence` identity.
+A `peer-reply` policy declares a `minProducers`, one or more
+`eligibleAgents`, and `acceptedStatuses: ["replied"]`. Eligible names or IDs
+must already be known in the workflow project. The hub resolves them to stable
+producer IDs when the run starts and fails closed if the coordinator is
+included or the unique resolved set cannot satisfy the configured minimum.
+See [Peer provenance and quorum gates](provenance-gates.md) for the complete
+schema and command-first example.
+
+Use `KXM_WEBHOOK_WORKFLOWS` for inline JSON or `KXM_WEBHOOK_WORKFLOWS_FILE` for a file, never both. Prefer `secretEnv` over a literal `secret`.
+
+## Pause for CI, review, merge, or Jira
+
+A coordinator should not hold an agent turn open while an external system runs for minutes or hours. On the active stage, call `kxm_workflow_wait` with:
+
+- the run and active stage IDs;
+- a stable `signalKey`, such as `github-pr-42-checks`;
+- a concise description of the expected result;
+- optional local evidence keyed by its declared requirement identity;
+- an optional timeout from one second through 30 days; the default is 24 hours.
+
+The hub changes the run and stage to `waiting`. The coordinator may then settle its current prompt without triggering the premature-settlement failure. If the deadline passes first, the run fails and records a harness error.
+
+The external system reports its result to:
+
+```text
+POST /v1/webhooks/:definitionId/runs/:runId/signals/:signalKey
+```
+
+The JSON body is:
+
+```json
+{
+  "status": "passed",
+  "summary": "All required GitHub checks passed",
+  "evidence": {
+    "github.check:ci": "conclusion:success url:https://github.example/org/repo/actions/runs/123"
+  }
+}
+```
+
+Sign the exact body bytes with SHA-256 HMAC. Supply the signature in `X-Hub-Signature-256` and a stable retry identifier in `X-GitHub-Delivery`, `X-Atlassian-Webhook-Identifier`, or `X-Mesh-Delivery-ID`. Repeating the same delivery ID and body returns minimal receipt metadata instead of checkpointing twice. Reusing a delivery ID for a different signal or body returns HTTP 409.
+
+Use `signalSecretEnv` so CI and merge reporters do not need the secret that creates new workflows. If it is omitted, callbacks fall back to `secretEnv` for compatibility. A valid callback can checkpoint only the named run's current wait and must match its signal key.
+
+Context evidence is optional. When a callback supplies `workflow.run`,
+`workflow.stage`, or `workflow.signal`, each value must exactly match the route
+run, active waiting stage, or route signal key respectively. A mismatch returns
+HTTP 409 without advancing the run or recording a delivery receipt. Adapters
+that do not need these diagnostic keys may omit them.
+
+`passed` applies the normal evidence rule and advances or completes the run. `warning` or `failed` consumes an attempt, records an error, and queues a correction prompt when attempts remain. The run, signal receipt, optional journal entry, and optional resume message commit in one SQLite transaction before delivery. A terminal result does not create another prompt. Only the validated summary and evidence are retained; the complete callback body is not stored.
+
+Callback responses deliberately expose only status, stage, retry, completion, resumption, and duplicate metadata. They never return the workflow record, coordinator prompt, message routing, journal, or evidence. Those remain behind project and agent authentication.
+
+The repository includes a small callback sender for smoke tests and automation adapters:
+
+```powershell
+$env:KXM_SERVER_URL = "https://your-hub-host.example"
+$env:KXM_WORKFLOW_ID = "jira-development"
+$env:KXM_WORKFLOW_SIGNAL_SECRET = "replace-with-the-callback-secret"
+$env:KXM_SIGNAL_DELIVERY_ID = "github-check-run-123-attempt-1"
+node --experimental-strip-types examples/workflow-signal.ts `
+  run_123 github-pr-42-checks passed "All required checks passed" `
+  "github.check:ci=https://github.example/org/repo/actions/runs/123"
+```
+
+`examples/workflow-signal.ts` reads `KXM_SIGNAL_DELIVERY_ID` and sends it as
+`x-kxm-delivery-id`. The CLI equivalent is `kxm gate signal --delivery-id`.
+
+In a real integration, store the `runId` and `signalKey` in Jira, pull-request metadata, or the external job's inputs when the coordinator starts the wait. Treat them as routing identifiers rather than secrets.
+
+To watch GitHub checks and post that same signal, use the command-first adapter:
+
+```powershell
+$env:KXM_WORKFLOW_ID = "jira-development"
+$env:KXM_WORKFLOW_SIGNAL_SECRET = "replace-with-the-callback-secret"
+$env:GITHUB_TOKEN = "replace-with-a-checks-read-token"
+kxm gate github watch --run-id run_123 --stage-id watch --signal-key github-pr-42-checks --repo org/repo --pr 42 --required ci --timeout-ms 3600000
+```
+
+The watcher binds every result to the exact run, stage, and signal key, requests
+up to 100 check runs per GitHub page, and follows every reported page. Each
+check is reported as `github.check:<check-name>`; diagnostic context such as
+`workflow.run` never satisfies an unrelated requirement. GitHub
+`startup_failure` is a failed result. On timeout the watcher posts a signed
+`failed` signal with summary `github_watch_timeout`, then exits `4`; it never
+invents a `passed` result.
+
+Each watcher invocation creates a new bounded delivery generation and includes
+the pull-request head SHA when GitHub returned one. Transport retries within
+that invocation reuse the exact `x-kxm-delivery-id`. After a failed or timed
+out result, start a new watcher for the new workflow wait; do not reuse the old
+generated ID. Supply `--delivery-id` only when an external supervisor must
+retry the same callback attempt with a stable provider identifier. The standalone
+`kxm gate signal` command follows the same rule.
+
+## Checkpoint contract
+
+Only the assigned coordinator can read, journal, checkpoint, or wait a run. A
+passing checkpoint must provide a non-empty value for every exact
+`requiredEvidence` identity. Evidence is a JSON object rather than a list, so
+extra GitHub checks or generic context cannot replace an unrelated review,
+artifact, or retrospective requirement. Identities are normalized by trimming,
+collapsing repeated whitespace, and case-folding; normalized aliases in one
+submission are rejected as duplicates.
+
+When a requirement has a peer policy, caller-authored evidence text cannot
+satisfy it. The coordinator must create peer messages with an authorized,
+immutable `workflowContext` for the exact run, active stage, canonical
+requirement, and current 1-based attempt. A passing checkpoint or wait cites the
+resulting durable message IDs in `evidenceRefs`. The hub verifies project,
+direction, eligible target, context, correlation, non-empty replied status,
+and coherent timestamps, then counts unique producer IDs. Old, pending,
+duplicate-producer, coordinator-authored, or cross-context messages do not
+count.
+
+Evidence supplied when entering `waiting` is accumulated with a later passing
+callback. `warning` and `failed` evidence is retained in the journal for
+diagnosis but intentionally does not satisfy a later passing attempt. Those
+results remain on the active stage and return a correction instruction.
+Reaching `maxAttempts` fails the run. Settling the coordinator prompt before all
+stages pass also fails the run and records a workflow error unless the
+coordinator deliberately placed the active stage in `waiting` first.
+
+If a policy declares `degradation.minProducers`, an operator may use
+`kxm gate degrade` with the administrative token to approve that exact
+lower minimum for only the current stage attempt. The coordinator, peer agents,
+and callback secret cannot authorize degradation. Approval alone never passes
+the stage; the coordinator must still provide the required verified references.
+The reason, policy minimum, approved minimum, attempt, and any eventual degraded
+pass are retained for audit.
+
+The hub enforces stage order and requirement identity; agents remain responsible
+for the truth of submitted evidence. Repository rules, human approvals, and
+harness permissions remain authoritative for push, merge, Jira mutation, and
+other external effects.
+
+Peer quorum proves provenance inside the hub project credential boundary. It
+does not prove answer quality, truth, distinct underlying models, independent
+inference, non-collusion, or human approval.
+
+## Platform references
+
+- [Pi extension lifecycle and message injection](https://pi.dev/docs/latest/extensions)
+- [Pi headless RPC mode](https://pi.dev/docs/latest/rpc)
+- [Jira Cloud webhook signing and retry behavior](https://developer.atlassian.com/cloud/jira/software/webhooks/)