Skip to content

[Architecture] General conditional work contracts: five-axis separation, anti-monolith schema invariant, acceptance-authority model #53

Description

@Sequela02

Parent and status

Objective

Make Kiln's governed-work contract model domain-neutral in its base by enforcing that the five separable axes of a work contract — intent, capability/identity, process/phase, evidence, assurance/acceptance — are never owned by a single token. Bind axes through explicit references, not through monolithic identifiers that silently fuse evidence with phase, route, capability, and identity.

The motivating defect is visual-reference-research (#9), which conflates all five axes into one token. This issue generalizes the lesson: the contract model must forbid the next monolith by construction, admit domain-specific overlays without baking them into the base, and resolve completion authority through a typed acceptance decision rather than through worker self-assessment or tool invocation.

Kiln's governing thesis is:

Kiln is a governed control plane for assigning, executing, reviewing, and reconciling work across agents, tools, runtimes, and human operators.

A capable token that fuses five axes is not governed merely because its tools are authorized and its final evidence is replayable. The contract must represent each axis as a separate field with its own validation, bind them through explicit references, and resolve completion through a typed acceptance decision that may require independent review depending on policy.

Decision requested

Determine whether Kiln should extend canonical Work Governance with a versioned, hash-bound general work-contract schema owned by Core, enforced by Runtime, and projected across every supported surface.

The review should decide:

  1. whether the five-axis separation (intent, capability/identity, process, evidence, assurance/acceptance) is the correct minimal partition, or whether temporal context and risk triggers deserve promotion to first-class axes;
  2. whether routeBinding is an execution binding outside the five axes (Kiln-general but not domain-general) or a sub-field of capability/identity;
  3. whether the anti-monolith invariant is enforceable as a typed schema rule, a config validator, a runtime admission gate, or a combination;
  4. how the acceptance-authority model resolves completion claims when self-assessment is insufficient;
  5. which research and paired benchmark evidence is required before selecting defaults or making efficiency claims.

Motivation

The monolithic-token defect (root evidence)

#9 inventory (204 occurrences of visual-reference-research + 27 of browser-qa + 13 of implied visual-researcher across 28 files) proved that a single token can fuse five axes:

  1. evidence typeKilnWorkGovernanceEvidence literal member;
  2. workflow phaseManagedInvocationPhaseId 1:1-mapped from the evidence id;
  3. route selectorphaseRoutes["visual-reference-research"] key;
  4. capability bundleDEFAULT_EVIDENCE_REALIZATION["visual-reference-research"] = ["read","glob","grep"];
  5. implied agent identitytaskAffinityForPhase("visual-reference-research") = ["research","frontend-design"].

No other evidence id in Kiln carries all five. The others group into semantic phases (surface-diagnosis, planning, implementation-verification, managed-review-closeout) without a dedicated route key, a 1:1 evidence→phase mapping, or an implied identity. The overloading encourages repeating the pattern: the next time Kiln needs to govern a new kind of work, the easiest path is to mint another monolithic token.

Self-assessment is not completion authority

Note 31 (AI-harness research) identified self-assessment as the dominant failure mode across OSWorld (best model 12.24% vs human 72.36%), WebArena (14.41% vs 78.24%), and the Anthropic long-running agent harness. Note 33 (cross-domain completion-authority research) confirmed from human governance: self-attestation may be admissible evidence for explicitly low-risk, reversible, or informal work, but it must not be labelled independent verification nor acquire implicit acceptance authority.

Kiln today treats browser-tool invocation as the success signal for the visual-reference-research obligation (governed-turn-outcome.ts:398-408), which is exactly the conflation the issue targets: a tool invocation is a capability, not completion evidence, and never acceptance authority.

Cross-domain convergence

Note 32 surveyed contract theory (Hart & Holmström 2016 Nobel), construction (FIDIC: plan→permit→build→inspect→occupy), medicine (clinical pathways, non-prescriptive), law (adversarial system exists because the dimensions must separate), audit (ISA 500 / PCAOB AS 1105: evidence-provenance hierarchy), ISO 9001:2015 (risk-based thinking, no fixed lifecycle), CMMI V3.0 (independent appraisal), and open-source CLAs. The five-axis separation recurs across every surveyed domain. The conflation evidence===phase===route===capability===identity does not appear in any non-programming governance domain.

Advisor decision (comment 5188557099)

The final advisor verdict: option C — implement #9 visual-specific with the schema constraint, open a separate general issue. The five-axis partition is the minimal defensible partition today. routeBinding is Kiln-general but not domain-general. Review independence is conditional (the universal rule is to declare completion claim, admissible evidence, and acceptance authority; if policy requires independence and no eligible reviewer exists, completion fails closed). The anti-monolith invariant is sound with a necessary refinement: a contract binds axes through explicit references; a token does not own them implicitly.

Current Kiln state

Kiln already has the correct architectural foundation for the axes individually:

  • GoalRun owns objective, authority envelope, route policy, evidence requirements, lifecycle, and closeout (packages/core/src/work-governance/goal-run.ts);
  • WorkItem owns scope identity, workflow/risk classification, dependencies, attempts, evidence, verification gates, pause requirements, and residual risk (packages/core/src/work-governance/work-item.ts);
  • managed invocations preserve profile, provider/model route, authority, context mode, child identity, terminal state, handoff, usage, resources, and replay evidence;
  • work-governance policy selects direct versus orchestrated execution and requires evidence before closeout;
  • context governance bounds the active working set;
  • evidence-realization.ts maps evidence requirements to required tool capabilities;
  • governed-turn-outcome.ts enforces turn-level completion gates;
  • phase-recovery.ts builds phase-specific recovery contracts;
  • [Work Governance] managed_agent.invoke is not surfaced in kiln run sessions, so the orchestrate posture cannot be honored #50 made kiln run sessions admit managed_agent.invoke under read_only with child-authority bounding, and records a structured capabilityGap when delegation is required but unavailable or unused;
  • [Architecture/Security] Make trusted-execution integrity reachable: operator authorization, effective-runtime observation, permanent-limitation acceptance #52 is producing operator trusted-authorization (authorizedBy, authorizedAt, scope, revocable) and effective-runtime observation — both are precedents for axis separation.

However, repository inspection shows that the canonical work contract does not currently enforce:

  • a typed schema where each axis is a separate field with its own validation;
  • an anti-monolith invariant that rejects a token owning semantic authority over more than one axis;
  • a completionClaim / acceptanceDecision distinction that separates "the worker declared done" from "the resolved acceptance policy ratified it";
  • a routeBinding field that is execution binding outside the five axes;
  • a domain-overlay mechanism that admits domain-specific controls (safety gates, inspection, custody, stamps, waiting periods) without baking them into the base;
  • an incomplete-contract default that treats silence as unresolved, not permissive.

Proposed architecture direction for investigation

The exact schema is intentionally not prescribed, but the review should evaluate these canonical concepts under the existing Work Governance bounded context.

1. Five-axis typed schema

A versioned, hash-bound work-contract schema owned by Core, enforced by Runtime, projected across every surface. The five axes:

Axis Owns Open question
Intent objective, behavioral acceptance criteria, permitted effects, non-goals, scope envelope is "scope envelope" a sub-field or its own axis?
Capability / identity who or what is responsible; qualifications/tools/capabilities; licensing is routeBinding separable or subsumed?
Process / phase lifecycle stages; phase transitions; stopping conditions declarative (config) or imperative (runtime state machine)?
Evidence what was observed or produced; provenance (producer, subject/target, method, observedAt, version/freshness, scope/coverage, integrity, verdict, limitations, supersession, redaction) full audit hierarchy or Kiln subset?
Assurance / acceptance independent verification of completion; reviewer independence level; acceptance gate universal or conditional? (note 33 settles: conditional)

Candidate axes NOT promoted (per advisor decision): temporal context (metadata distributed across axes); risk triggers (inputs to the policy resolver, not a first-class axis).

2. Route binding outside the five axes

routeBinding is Kiln-general but not domain-general. It is an execution binding: provider/model/runtime/tool/subagent resolved against the five-axis constraints. It must be a separate field, not a sub-field of capability/identity, and never a source of canonical semantics for any axis.

3. Anti-monolith invariant

No single contract token may be the canonical source of semantics for more than one axis. Links between axes must be explicit, validated references.

A contract binds axes together; a token does not. Composite profiles and references are permitted; implicit semantic ownership is not. An evidence id must not be 1:1-mapped to a phase id, a phaseRoute key, a capability bundle, and an agent identity at the same time.

The invariant must be enforceable. The review should determine whether it lives in the Core type system, config validation, runtime admission, or a combination.

4. Completion-claim and acceptance-decision

A worker (agent, child, human operator) may emit a completionClaim. Only the resolved acceptance policy may produce an acceptanceDecision. The two are distinct states and distinct actors:

  • claimed — the worker declared done;
  • verified — evidence satisfies the policy gates;
  • accepted — the resolved acceptance authority ratified the claim;
  • final — no supersession remains possible.

Self-assessment is not acceptance authority. Tool invocation is not completion evidence. Absence of error is not acceptance.

5. Conditional review independence

Review independence is conditional (note 33). The universal rule is to declare completion claim, admissible evidence, and acceptance authority. If policy requires independence and no eligible reviewer exists, completion fails closed. Independence is selected by consequence, detectability, reversibility, externality, information asymmetry, and mandate — not by a fixed universal rule.

6. Domain-overlay mechanism

The base is domain-neutral. Domain-specific controls (safety gates, inspection, custody, stamps, waiting periods, insurance/bonding) are admitted as versioned, executable Kiln-native overlays, not imported ISO taxonomies. An overlay adds types, rules, gates, and validators on top of the base. The pattern is conceptual ISO (AS9100/IATF 16949/ISO 13485); the mechanism is Kiln-native.

7. Incomplete-contract defaults

Silence on an axis means unresolved, not permissive. A declared overlay or policy may complete defaults. Without resolution, dispatch or acceptance blocks according to the axis. Never infer review, authority, or completion from executor identity, tool invocation, or absence of error.

Cross-surface, cross-harness, and cross-provider invariants

  • Core owns canonical contract schema and state; Runtime owns admission, accounting, transitions, and terminal truth.
  • GUI, TUI, CLI, SDK, MCP, and replay only project the canonical state; they do not own contract policy.
  • Direct providers and native harness adapters report capabilities and evidence; they do not own contract, review, or acceptance policy.
  • Harness capability degradation produces a typed pause or admitted alternative route, never simulated compliance in prose.
  • Provider changes do not reset contract lineage, evidence, or acceptance state.
  • No hidden retry, route reassignment, or acceptance reinterpretation occurs after commitment.
  • Unknown evidence, missing provenance, or unsupported review remains explicit.
  • A child cannot lend contract authority, scope, acceptance authority, or unused budget to another child.
  • Surface-local configuration may narrow canonical limits but cannot widen them without an admitted operator decision.

Required research before design approval

The architecture review must include:

  1. a repository-wide inventory of existing goal, work-item, attempt, managed invocation, evidence, context, cancellation, timeout, replay, and benchmark contracts, proving which axes are already separated and which are conflated;
  2. an explicit bounded-context and dependency-direction proposal showing why the work belongs in existing Work Governance rather than a new control plane;
  3. primary-source research on AI-harness approaches to the five axes (Anthropic, OpenAI, Google/Gemini CLI, Claude Code, Codex, OpenCode — note 31 already covers this; verify currency);
  4. primary-source research on cross-domain governance (notes 32/33 already cover this; verify currency);
  5. a capability matrix for Codex direct/native, OpenCode direct/native, Claude Code native, Gemini CLI native, and Kiln-owned surfaces;
  6. threat modeling for axis collapse (token monolith recurrence), acceptance-authority bypass (self-assessment as authority), contract-reset via route/provider change, fabricated evidence, stale acceptance, and adapter-local policy drift;
  7. a paired benchmark design that freezes task, repository baseline, provider/model, harness/adapter version, authority/tool catalog, context policy, acceptance criteria, and scorer set, recorded in the benchmark-publication contract.

Tests-first implementation order

  1. Add failing Core tests for the five-axis schema, anti-monolith invariant, routeBinding separation, completionClaim/acceptanceDecision distinction, and incomplete-contract unresolved defaults.
  2. Add a failing Runtime integration proving that a contract with a monolithic token (evidence===phase===route===capability===identity) is rejected at admission with a typed reason.
  3. Add a failing Runtime integration proving that a completionClaim without a resolved acceptanceDecision blocks closeout.
  4. Migrate the first concrete instance ([Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9 visual) to the new schema, proving that the visual contract still works and no longer fuses axes.
  5. Add the second concrete instance (managed-agent/provider-routing change) proving that a non-visual contract separates route, executor capability, evidence, review, and acceptance without screenshots.
  6. Add the domain-overlay mechanism with one overlay (e.g., the managed-agent overlay) and prove it adds gates without modifying the base.
  7. Project contract state through records, history, replay, and all operator surfaces with portable sanitized fixtures.
  8. Update architecture and the long-term vision only after focused tests, affected tests, workspace typecheck/build, git diff --check, and independent high review.

Required deterministic scenarios

  1. A contract with a monolithic token (evidence id = phase id = route key = capability bundle = identity hint) is rejected at admission with an explicit anti-monolith reason.
  2. A contract with five separate axes and explicit references is admitted and traverses intent→process→evidence→acceptance.
  3. A completionClaim emitted by the worker without a resolved acceptanceDecision blocks closeout.
  4. A completionClaim ratified by an independent reviewer produces accepted; a completionClaim denied produces rejected; a completionClaim with no eligible reviewer and policy-requiring-independence fails closed.
  5. A routeBinding referencing an ineligible executor (capability mismatch, authority mismatch) is rejected before dispatch.
  6. A domain overlay adds a gate (e.g., provider-routing requires adversarial review) that blocks acceptance until satisfied; removing the overlay returns to base behavior.
  7. An incomplete contract (silent on review) is unresolved and blocks dispatch or acceptance according to the axis, with no inference from executor identity or tool invocation.
  8. Concurrent work cannot reset contract lineage, evidence provenance, or acceptance state.
  9. Replay and every surface explain contract state, axis bindings, completion claim, acceptance decision, and residual risk without secrets.
  10. The [Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9 visual contract migrated to the new schema produces the same governed-work outcomes as today without fusing axes.
  11. The managed-agent/provider-routing contract separates route, executor capability, evidence, review, and acceptance without screenshots.
  12. Migration of historical evidence ids (visual-reference-research, browser-qa) to the new contracts is forward-only; new writes cannot emit the old monolithic ids; a temporary migration reader converts historical evidence without enabling new legacy writes.

Completion criteria

  • Independent audit ratifies or explicitly amends this contract before implementation.
  • Core owns one provider-neutral five-axis work-contract schema with routeBinding, completionClaim, and acceptanceDecision as separate typed fields.
  • The anti-monolith invariant is enforceable (Core type, config validation, runtime admission, or combination) and rejects a token owning semantic authority over more than one axis.
  • routeBinding is an execution binding outside the five axes, never a source of canonical semantics for any axis.
  • A completionClaim is not an acceptanceDecision; only the resolved acceptance policy produces authority.
  • Self-assessment, tool invocation, and absence of error never acquire implicit acceptance authority.
  • Review independence is conditional; policy may require independence and fail closed when no eligible reviewer exists.
  • The domain-overlay mechanism adds types, rules, gates, and validators without modifying the base.
  • Silence on an axis is unresolved, not permissive.
  • Two bounded instances validate the model: visual [Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9 and managed-agent/provider-routing change.
  • All 12 deterministic scenarios pass with portable synthetic fixtures.
  • Focused suites, affected packages, full tests, typecheck, build, E2E, teardown, and git diff --check pass on the exact candidate.
  • Independent reviews have no unresolved high or medium slice-caused findings.
  • Stable architecture and the long-term vision match executable behavior.
  • The explicit closeout comment records every required evidence item and residual risk.

Non-goals

  • No ontología para construcción/medicina/derecho; Kiln governs software work today; domain overlays are admitted, not pre-built.
  • No workflow DSL universal; phases are declarative contracts, not a programming language.
  • No marketplace de overlays; overlays are versioned executable config, not installable plugins.
  • No full audit hierarchy (ISA 500 / PCAOB AS 1105) imported wholesale; use the Kiln subset until a real consumer demands more.
  • No nueva provider abstraction; routeBinding uses existing provider/model/runtime resolution.
  • No migración de todos los perfiles existentes en este issue; migration is per-instance, starting with [Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9 visual.
  • No compatibility layer indefinida; historical readers are one-way and temporary; new writes cannot emit old monolithic ids.
  • No implementation before architecture and benchmark review approve a bounded slice.

Residual risk

  • Two-instance generalization: five axes and the anti-monolith invariant are validated against two software instances only (visual [Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9, provider-routing). A third instance may reveal that the partition is incomplete. The schema is provisional until a third instance validates. Do not claim operational universality from two cases.
  • No causal benchmark: no benchmark isolates the anti-monolith invariant as a causal variable for outcomes. Decomposition, grounding, and external-verification evidence supports it directionally but does not prove it.
  • Cross-domain self-assessment multiplier: no reliable cross-domain multiplier of self-assessment defect rates exists; note 33 acknowledges this. Conditional independence is a defensible policy, not a measured constant.
  • Five axes are not proven final: they are the minimal defensible partition today. Six or seven axes would promote cross-cutting concerns to premature entities.
  • Cloned harness evidence is a snapshot: note 31's harness details are point-in-time observations, not permanent product capabilities.
  • Domain-overlay mechanism is novel: concept follows ISO, but Kiln-native enforcement is untested. Overlay drift, versioning conflicts, and base/overlay interaction need threat modeling.

Delivery constraints

  • This issue does not authorize implementation.
  • Begin with independent architecture/research review.
  • Any later implementation branch must start from dev and target a dedicated integration branch.
  • Keep contracts provider-neutral and delete obsolete paths instead of preserving speculative compatibility layers.
  • Use synthetic portable fixtures for deterministic CI; live provider/harness proof remains explicit, bounded, and separately authorized.
  • [Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9 visual-specific implementation proceeds independently and must satisfy the schema invariant; this issue ratifies the invariant as a cross-cutting rule after the second instance validates.
  • Do not merge as part of the initial implementation task.

Final architecture rule

A contract binds axes together; a token does not. A worker may claim completion; only the resolved acceptance policy may make that claim authoritative.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions