Skip to content

[Architecture] Replace monolithic visual-reference-research with conditional visual-work contracts #9

Description

@Sequela02

Summary

Replace the current monolithic visual-reference-research concept with explicit, conditional contracts for visual intent, authoritative design context, exploration, rendered verification, and independent design review.

This is an architecture issue, not an implementation roadmap. The goal is to remove a conflated abstraction before it becomes a cross-surface compatibility boundary.

Kiln's governing doctrine is:

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

Software engineering is the first workload, not the architectural boundary. Visual work therefore needs horizontal governance primitives rather than a workflow token that simultaneously acts as evidence, phase, route selector, capability bundle, and implied specialist identity.

Problem

Repository inspection shows that visual-reference-research currently behaves as several different things at once:

  • evidence identifier;
  • workflow phase;
  • phase-route selector;
  • policy trigger;
  • capability bundle;
  • implied agent/specialist identity.

Relevant current surfaces include:

  • packages/cli/src/application/work-governance-policy.ts;
  • packages/cli/src/application/work-governance-workflows.ts;
  • phaseRoutes.visual-reference-research in global configuration and documentation;
  • UI-triggered evidence requirements including visual-reference-research and browser-qa;
  • recovery, replay, fixtures, GUI/TUI/CLI projections, and tests that depend on these names.

The repository does not define a canonical builtin profile named visual-researcher. Instead, the visual-reference-research token implicitly carries that identity and its expected tools.

This coupling violates the separation required by the governed-work architecture:

  • evidence must state what was observed or produced;
  • phases must state where work is in its lifecycle;
  • routes must identify execution targets;
  • capabilities must state what an executor can do;
  • agent identities must state who or what is responsible;
  • completion must depend on governed evidence, not model self-assessment.

Why replacement is required

A simple rename or local refactor is insufficient. The current abstraction encodes an incorrect policy assumption: that UI work generally requires external visual research.

That is false across common workloads:

  • a UI bug fix may only require implementation and rendered regression verification;
  • a Figma-directed implementation should use authoritative design context, not external inspiration research;
  • an exploratory product-design task may require external visual exploration;
  • a UI-preserving refactor should not trigger exploration at all;
  • a material visual change still requires rendered verification even when no external research is appropriate.

The architecture must select obligations from the work's visual intent and available authoritative context, rather than from the fact that the task touches a UI surface.

Canonical policy

UI work must use the strongest available authoritative design context. External visual exploration is required only when the work is explicitly exploratory or lacks sufficient visual direction. Material visual changes require verification against the rendered target. Neither research nor model self-assessment is completion evidence by itself.

Target model

1. Visual intent

Introduce an explicit visual-intent classification, conceptually:

  • none — no material visual behavior is involved;
  • preserve — existing appearance/behavior must remain stable;
  • specified — authoritative visual direction is supplied;
  • exploratory — the executor is expected to investigate and propose visual direction.

The exact schema and names should be established through architecture review, but intent must be distinct from evidence, phase, route, and agent identity.

2. Evidence contracts

Replace the current token with separate evidence types.

design-context

Authoritative visual direction available to the work, such as:

  • Figma or another design source;
  • design-system definitions;
  • screenshots supplied by an operator;
  • an existing product or rendered baseline;
  • explicit visual references supplied as requirements.

It should identify provenance, authority, scope, and any freshness/version information needed for replay.

visual-exploration

Required only for exploratory work or insufficient visual direction.

It should contain at least:

  • research question;
  • references examined;
  • rationale;
  • alternatives considered;
  • rejected alternatives where materially relevant;
  • relationship to the resulting design decision.

This is not completion evidence for implementation.

rendered-visual-verification

Verification against the actual rendered target. This replaces the overloaded browser-qa completion role for visual correctness.

It should record at least:

  • rendered target/build identity;
  • environment and viewport/device where material;
  • screenshots or equivalent observations;
  • states and interactions exercised;
  • expected versus observed result;
  • verdict;
  • residual risk or unverified states.

Browser execution is one possible capability used to produce this evidence; it is not the evidence type itself.

design-review

An independent review artifact for material design choices where policy requires a separate reviewer.

It must remain distinct from implementation self-assessment and from rendered verification.

3. Semantic phases

Replace phaseRoutes.visual-reference-research with lifecycle phases that describe work rather than a specific technique:

  • context acquisition;
  • exploration;
  • implementation;
  • rendered verification;
  • review.

Routes may be selected for a phase based on capabilities and authority, but the phase name must not encode an agent profile or tool.

4. Capability-based routing

Visual work must route by declared capabilities, for example:

  • browser interaction;
  • screenshot capture;
  • visual/multimodal input;
  • design-context access;
  • relevant application/runtime access;
  • read-only external research;
  • rendered-state interaction.

Do not route by an implied visual-researcher identity or by matching special tool names.

5. Conditional workflow obligations

Representative policy fixtures should include at least:

UI bug fix

implementation -> rendered verification

No external exploration unless the work explicitly lacks necessary visual direction.

Figma/design-system implementation

context acquisition -> implementation -> rendered verification

The authoritative source takes precedence over external references.

Exploratory visual design

context acquisition -> exploration -> implementation -> rendered verification -> design review

UI-preserving refactor

implementation -> regression verification

No exploration.

Nonvisual change

No visual workflow obligations unless actual impact classification or evidence proves otherwise.

Required investigation before implementation

Inspect the repository and inventory every use and semantic dependency of:

  • visual-reference-research;
  • phaseRoutes entries associated with it;
  • browser-qa as evidence, phase, route, completion signal, or compatibility alias;
  • UI policy triggers;
  • work-governance workflow definitions;
  • evidence declarations and projections;
  • fixtures and tests;
  • recovery and replay;
  • GUI, TUI, CLI, SDK, and operator projections;
  • documentation and examples.

Do not assume the current design is authoritative merely because it is implemented.

Review relevant current industry and research practice for governed GUI/visual agents, including primary material from major labs and credible papers/benchmarks on:

  • computer-use perception/reasoning/action loops;
  • GUI grounding and end-to-end verification;
  • screenshot/rendered-state evidence;
  • design-context integrations;
  • safety and independent evaluation of computer-use agents.

External research should inform the contract design, not introduce vendor-specific architecture.

Migration requirements

Stage 1 — contracts and policy fixtures

  • define visual intent independently from evidence and phase;
  • define the four evidence contracts above, or document justified replacements;
  • define semantic phases;
  • define capability requirements for each phase;
  • add policy fixtures for the representative workloads;
  • prove that a generic UI trigger no longer automatically requires external visual exploration;
  • document provenance, identity, replay, recovery, and redaction requirements for each evidence type.

Stage 2 — surface migration

Migrate all affected:

  • governance policy;
  • workflow definitions;
  • routing/configuration;
  • recovery and replay;
  • canonical-state projections;
  • GUI/TUI/CLI/SDK/operator surfaces;
  • documentation;
  • tests and fixtures.

Delete:

  • visual-reference-research as a monolithic concept;
  • any implied visual-researcher profile contract;
  • compatibility aliases that preserve the conflation, unless a concrete external compatibility requirement is documented.

A temporary migration reader may be acceptable only if it converts historical evidence into the new canonical contracts without allowing new writes in the old form.

Replay and recovery expectations

The replacement must be replayable and deterministic enough to answer:

  • what visual intent governed the work;
  • which design context was authoritative;
  • whether exploration was required and why;
  • which route/capabilities produced each artifact;
  • what rendered target was verified;
  • which states were exercised;
  • who or what performed independent review;
  • whether recovery preserves or supersedes prior evidence;
  • whether GUI, TUI, CLI, SDK, and replay produce the same canonical completion state.

Evidence identity, provenance, supersession, redaction, and terminal-state behavior must follow the governed-work execution doctrine in docs/architecture/governed-work-execution.md.

Non-goals

  • creating a permanent vendor-specific Figma, browser, or model abstraction;
  • requiring web research for every UI task;
  • treating screenshots alone as proof without target/build/state identity;
  • treating a browser tool invocation as evidence by itself;
  • encoding an agent profile into a phase name;
  • relying on model self-assessment as completion;
  • preserving the old abstraction solely to reduce migration work.

Acceptance criteria

  • Repository-wide inventory of the old concept and all dependent surfaces is documented.
  • Visual intent is represented independently from evidence, route, phase, and agent identity.
  • Authoritative design context is represented explicitly with provenance.
  • External visual exploration is conditional, not automatically triggered by UI work.
  • Material visual changes require rendered-target verification.
  • Independent design review is distinct from implementation and verification.
  • Routing is capability-based and provider-neutral.
  • No special-case routing by visual-reference-research, implied visual-researcher, vendor, or tool name remains in canonical policy.
  • Recovery/replay preserves evidence identity, provenance, supersession, and canonical completion.
  • GUI, TUI, CLI, SDK, operator projection, and replay agree on canonical state.
  • Fixtures prove bug-fix, specified-design, exploratory-design, preserving-refactor, and nonvisual scenarios.
  • New writes cannot emit the old monolithic evidence/phase contract.
  • Old aliases are deleted or justified by a documented external compatibility boundary.
  • Documentation states the canonical policy quoted above.

Delivery constraints

  • Work must branch from codex/cross-harness-gateway.
  • Any implementation PR must target codex/cross-harness-gateway.
  • Never commit or open this work against main.
  • Begin with an architecture/design review before implementation.
  • Prefer behavioral fixtures and cross-surface proofs over structural assertions.
  • Do not merge as part of the initial implementation task.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions