You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
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.
Summary
Replace the current monolithic
visual-reference-researchconcept 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:
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-researchcurrently behaves as several different things at once:Relevant current surfaces include:
packages/cli/src/application/work-governance-policy.ts;packages/cli/src/application/work-governance-workflows.ts;phaseRoutes.visual-reference-researchin global configuration and documentation;visual-reference-researchandbrowser-qa;The repository does not define a canonical builtin profile named
visual-researcher. Instead, thevisual-reference-researchtoken implicitly carries that identity and its expected tools.This coupling violates the separation required by the governed-work architecture:
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:
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
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-contextAuthoritative visual direction available to the work, such as:
It should identify provenance, authority, scope, and any freshness/version information needed for replay.
visual-explorationRequired only for exploratory work or insufficient visual direction.
It should contain at least:
This is not completion evidence for implementation.
rendered-visual-verificationVerification against the actual rendered target. This replaces the overloaded
browser-qacompletion role for visual correctness.It should record at least:
Browser execution is one possible capability used to produce this evidence; it is not the evidence type itself.
design-reviewAn 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-researchwith lifecycle phases that describe work rather than a specific technique: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:
Do not route by an implied
visual-researcheridentity or by matching special tool names.5. Conditional workflow obligations
Representative policy fixtures should include at least:
UI bug fix
implementation -> rendered verificationNo external exploration unless the work explicitly lacks necessary visual direction.
Figma/design-system implementation
context acquisition -> implementation -> rendered verificationThe authoritative source takes precedence over external references.
Exploratory visual design
context acquisition -> exploration -> implementation -> rendered verification -> design reviewUI-preserving refactor
implementation -> regression verificationNo 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;phaseRoutesentries associated with it;browser-qaas evidence, phase, route, completion signal, or compatibility alias;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:
External research should inform the contract design, not introduce vendor-specific architecture.
Migration requirements
Stage 1 — contracts and policy fixtures
Stage 2 — surface migration
Migrate all affected:
Delete:
visual-reference-researchas a monolithic concept;visual-researcherprofile contract;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:
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
Acceptance criteria
visual-reference-research, impliedvisual-researcher, vendor, or tool name remains in canonical policy.Delivery constraints
codex/cross-harness-gateway.codex/cross-harness-gateway.main.