# ADR-0008 — Autonomous Physical Toolsmith for Photoshop and Unity

- **Status:** Implemented — production-control architecture complete; real Photoshop/Unity release
  corpora remain deployment evidence gates
- **Date:** 2026-07-30
- **Depends on:** ADR-0006 Fabric Core Intelligence; ADR-0007 Fabric-first autonomy
- **Objective:** Let Fabric autonomously turn authoritative wiki and ticket knowledge into qualified,
  typed Photoshop and Unity operations without giving generated code unrestricted production authority.

## Context

Fabric already has most individual mechanisms:

- workspace-scoped wiki/RAG and ticket evidence;
- procedure compilation from executable skills;
- task-bound JSX compilation in `photoshop_script_compiler.py`;
- conservative JSX checks in `jsx_safety.py`;
- allowlisted on-disk execution in `photoshop_bridge.py`;
- typed live Unity actions in `unity_bridge.py`;
- headless transient C# helper injection and cleanup in `backend.py`;
- capability acquisition and maturity states in `capability_builder.py`;
- evidence phases in `capability_workbench.py`;
- certification, approvals, durable workflow claims, visual comparison, and goal verification.

The blocker was architectural fragmentation: the planner exposed only part of the installed Unity
surface and the installed MCP package lacked typed serialized-state and stable UI Toolkit controls.
The canonical manifest now covers all 61 registered MCP handlers, while the separately versioned
Toolsmith Editor package supplies those two generic families through a sealed file protocol. The
package remains in the Fabric repository and is transactionally bound into a Unity project only
for the duration of a governed Toolsmith operation. Genuinely unknown operations still stop at a
non-executable acquisition candidate.

## Decision

Create a governed **Physical Toolsmith** loop:

> Ticket goal → authoritative evidence pack → physical-operation specification → registered
> primitive composition or isolated implementation candidate → qualification → typed registration →
> approved execution → observation → domain verification → goal verification → retained outcome

Fabric owns every engineering step. Humans authorize pilot/production effects and resolve only
irreducible visual or product judgment.

### 1. Evidence is input, not executable instruction

The Evidence Researcher retrieves ticket text, comments, wiki sections, reference images, repository
conventions, installed Photoshop/Unity versions, existing scripts, and prior outcomes. Every field
has source identity, revision/digest, workspace, trust, and freshness.

Prompt-injected instructions from Jira, wiki, PSD layer names, filenames, or images cannot request
tools, widen roots, change policy, or supply raw executable code.

### 2. Shared physical-operation IR

`forge.physical-operation-spec.v1` is the boundary between reasoning and execution. It contains:

- original goal and preserved constraints;
- target application and version envelope;
- typed inputs, outputs, allowed roots, effects, approval policy;
- ordered primitive operations with evidence references;
- preconditions, rollback/compensation, and required verifiers;
- a digest binding the complete specification.

The IR never contains raw JSX or C#.

### 3. Deterministic primitive composition first

For Photoshop, Fabric composes registered operations such as open, inspect layers, duplicate,
hide/show layers, crop/resize, flatten, mask, and export. A deterministic compiler emits task-bound
JSX from reviewed templates. The current `photoshop_script_compiler` is the first implementation.

For Unity, Fabric composes registered bridge actions such as refresh, find assets, add component,
set serialized property, assign bundle, execute allowlisted menu item, run tests, inspect logs, and
capture screenshots. Native typed bridge calls are preferred over generated C#.

### 4. Toolsmith candidate lane for genuinely new operations

If the IR contains an unsupported operation, Fabric creates a non-executable capability candidate.
The Toolsmith then:

1. inspects repository/API/version conventions;
2. produces a typed contract and fixture;
3. creates JSX or Unity Editor C# only in an isolated worktree/candidate root;
4. performs static policy checks and dependency/supply-chain checks;
5. compiles/parses it with the authoritative application;
6. runs it against disposable fixtures or duplicated documents/projects;
7. proves allowed-root containment and captures before/after manifests;
8. runs deterministic, visual, Unity import/reference, and task-specific validators;
9. obtains independent Security Critic and Outcome Verifier reviews;
10. promotes through candidate → certified → pilot → production.

The authoring model cannot certify or promote its own implementation. Pilot and production require
separate authority.

Production promotion additionally requires a sealed
`forge.physical-capability-benchmark.v1` report containing at least 20 unique attributable cases for
that exact pilot revision. Fabric recomputes the report at transition, persistence and display
boundaries. Every release dimension must score 10/10: provider execution, zero manual app work,
mechanical success, postconditions, source integrity, authorization, honest completion, recovery,
human acceptance and independent review. One failed dimension blocks promotion.

### 5. Execution boundary

Only pilot/production capabilities enter the runtime registry. Execution binds:

- capability/version/spec digest;
- worker identity and environment;
- exact workspace/resource scope;
- approval and fencing token for protected effects;
- idempotency key and durable checkpoint;
- application version and connector health.

Uncertain completion is reconciled before retry.

### 6. Verification closes the loop

Photoshop completion requires reopening actual output bytes and checking dimensions, alpha/color
profile, expected files, hashes, and visual comparison against references or a shipped baseline.

Unity completion requires import success, changed-path manifest, no compile errors, no missing GUIDs
or references, required component/property state, test/validator evidence, and screenshots when the
goal is visual.

Plan completion is never goal completion. The Outcome Verifier evaluates the original ticket goal
and acceptance criteria against retained typed evidence.

### 7. Core/Micro Agent team

- Goal Analyst — preserves the ticket outcome and constraints.
- Evidence Researcher — retrieves attributable wiki/ticket/repository/application context.
- Procedure Synthesizer — produces the physical-operation IR.
- Capability Scout — finds reusable primitives and existing implementations.
- Toolsmith — creates an isolated candidate only for missing primitives.
- Fixture Builder — creates disposable representative inputs and expected invariants.
- Security Critic — checks roots, APIs, code, dependencies, secrets, and injection paths.
- Independent Reviewer — challenges correctness and rollback.
- Outcome Verifier — verifies application evidence and the original goal.
- Master Agent — owns the durable plan and reconciliation; specialists remain bounded.

## Failure and recovery

- Missing evidence → retrieve alternatives or ask the smallest factual question.
- Unsupported primitive → capability acquisition, not manual execution.
- Static/compile failure → diagnose and revise candidate within bounded attempts.
- Fixture mismatch → revise implementation or specification; never weaken the expected result.
- Provider unavailable → wait/retry on durable state or select an already-certified alternate lane.
- Visual ambiguity → show side-by-side evidence and ask for judgment without transferring tool work.
- Uncertain external result → reconcile application/files/repository state before any retry.
- Repeated failure → typed dead-end escalation with attempts, evidence, and durable resume point.

## Rollout

1. **Contract:** shared IR, trust/provenance validation, primitive inventory — implemented.
2. **Photoshop composition:** task-bound JSX compiles only into Fabric's ignored trusted-runtime
   root. The bridge still rejects arbitrary script text and paths. Output bytes are reopened for
   existence, dimensions, hashes, and visual comparison. A hermetic ticket-to-goal benchmark is
   implemented; qualification against every supported installed Photoshop version remains a release
   responsibility.
3. **Unity composition:** compile typed bridge action plans with import/reference/test verification
   — plan compilation plus concrete AssetDatabase import, console, and asynchronous test adapters
   implemented. The client, verifier contract, and Unity MCP Editor handler for structured serialized
   reference/component/property inspection are implemented. Fabric does not infer this evidence from
   a process exit code or log text.
4. **Candidate Toolsmith:** unsupported IR operations automatically create sealed, non-executable
   Capability Center proposals with roots, inputs, validators, risk and rollback.
   `physical_toolsmith.py` runs the JSX source generator followed by an isolated fixture runner,
   permission probe, rollback probe and separate-identity reviewer. Unsafe JSX or any failed gate
   stops qualification. Passing implementations are content-addressed beneath the ignored
   `.fabric_capabilities_impl/` root and become `certified`, not executable. Pilot activation
   requires attributable approval, workflow and fencing identities. It returns a digest-bound node
   patch; generated code cannot self-promote.
5. **Durable master loop:** `physical_operation_service.py` is the agent-facing execution boundary.
   It performs live application preflight, compiles specs, holds a cross-process idempotency claim,
   records the plan and authority, refuses key collisions, converts expired executor leases to
   unknown completion, and reconciles actual state through verifiers without replaying effects.
   Unity's local MCP package/settings and the Fabric Toolsmith package are transactional overlays
   restored after success or failure. Toolsmith manifest recovery state stays under Fabric runtime
   storage, not in the game project; a concurrent manifest change fails closed for reconciliation.
6. **Pilot:** hermetic Photoshop and Unity ticket-to-goal benchmarks are implemented. A real
   production-ticket pilot, an unfamiliar ticket, and a second game repository remain deployment
   qualification gates rather than claims made by unit tests. The pilot→production control plane is
   implemented in `physical_production_readiness.py` and `physical_toolsmith.promote_production`,
   including a resumable Studio service job, exact benchmark/approval digests, store-level
   revalidation and restart recovery. It never publishes or commissions an agent.
   Generated execution rechecks fresh application readiness, exact Unity project scope and the
   production-qualified application-version set immediately before provider dispatch. The global
   Forge product-release decision also blocks until Photoshop and Unity each supply the required
   real 20-case 10/10 summary.

## Implemented agent binding

`physical_operation` is a first-class Forge/Fabric capability and an `AUTO` executor only when its
node contains `physical_operation_spec` or a compiled plan. Typed queued runs inherit the backend
run/queue identities as their operation and idempotency keys. The backend binds these nodes to the
durable service; legacy Unity, Photoshop and procedure nodes are unchanged.

Two versioned adapters currently translate grounded requests into the IR:

- `photoshop.offer-export.v1`
- `unity.editor-window.v1`

Adapters preserve the original goal, evidence identities, allowed roots and measurable outcome
criteria. Wiki/Jira content never supplies executable code. New project-specific procedures either
compose these primitives or enter capability acquisition. `unity.editor-window.v1` resolves to the
installed `com.forge.fabric-toolsmith` package only while its exact project-local status is fresh;
otherwise Capability Center and runtime preflight mark only those extension-backed rows degraded.

Qualified generated JSX is never imported by Python and never sent as raw script text. The fixed
`generated_physical_adapter.py` resolves only sealed pilot/production candidates, checks the exact
runtime module binding, promotion evidence, implementation containment and SHA-256, execution
authority, allowed roots, agent-bound candidate digest, and typed postconditions. It invokes the
existing allowlisted Photoshop bridge and then the standard physical verifiers. Photoshop success
without postcondition evidence is a failed run. The backend exposes these handlers to both linear
and agentic procedure runners only while the candidate remains eligible.

The governed runtime rejects protected execution without approval, workflow, operation, and fencing
identities. Provider success alone cannot complete a plan: every declared required verifier must
return typed evidence. Provider exceptions after dispatch are classified as unknown completion.

`physical_operation_verifiers.py` is the default runtime verifier registry. Files are constrained to
the plan's allowed roots and evidenced with hashes. Images are reopened and decoded, dimension/hash
checks inspect actual bytes, and visual comparison records similarity, RMS, changed-pixel percentage,
thresholds, and both artifact digests. Changed-path proof requires a pre-execution digest and rejects
unchanged bytes. Unity import verification refreshes AssetDatabase and resolves each expected asset
by exact identity (with fuzzy search retained only for older bridge compatibility);
console verification reads structured error entries; test verification starts the Test Runner and
polls its operation to a terminal result. `references_resolved` and `goal_contract` deliberately fail
closed until concrete typed probes are registered. The Unity reference probe requires the Editor to
return all three arrays—`missing_references`, `missing_components`, and `property_mismatches`—even
when empty; a generic success message is rejected.

The installed authoritative `com.zynga.unity-mcp-server@0.4.315` package still does not register
`validation.inspect_serialized_state`. Fabric no longer routes to that invented handler. The fixed
`com.forge.fabric-toolsmith` package implements the semantic operation with contained `Assets/`
paths, bounded requests, `SerializedObject` inspection, and all three typed evidence arrays. Live
qualification passed on an existing prefab and on a disposable imported texture. UI Toolkit
inspect/set/invoke similarly uses exact stable selectors and observable read-back, never coordinates
or arbitrary reflection.

## Commissioned character-production vertical

Fabric now has one explicit authorization chain for zero-touch physical execution:

`certified graph → explicit publication → scoped commission → task claim → central runtime gate`.

The commission binds the graph, qualification and publication digests; allowed roots, effects and
capabilities; exact provider/action/manifest versions; cited SOP revisions and digests; application
compatibility; human issuer; expiry; and optional autonomous-acceptance evidence. The Toolsmith
supervisor derives a one-task claim from that envelope. `approvals.validate_execution_claim` remains
the single physical admission gate, so commissioned work does not create a bypass runtime.

`CharacterProductionAutonomy.v1` composes the registered Photoshop and Unity primitives needed for
Flat Art, animation/prefab integration, ability/VFX support, multidisciplinary final review,
Addressables, tests and the project's approved build-menu action. The companion Fabric skill teaches
Architect to design this family and makes GOTRPG character-production tickets route to the typed
Unity runtime. It is shipped as an available candidate only: registration, no-write qualification,
certification, publication and commissioning remain explicit and separate.

Autonomous final-review acceptance is narrower than release authority. It requires all seven
GOTRPG-49895 checks to have attributable artifact/reference evidence and an active sealed commission
whose autonomous-acceptance flag was earned by 20 unique full-workflow ticket replays plus independent
review. Qualification cases may not perform Jira transition, merge, publication or release effects.
Uncertainty blocks without fabricating completion; it does not weaken the checklist or silently ask a
human to perform application work.

Commission audits durably suspend execution after expiry, provider loss/rebinding, graph,
certification or publication drift, SOP revision drift, application compatibility drift, or changed
autonomy evidence. A suspended commission may be explicitly renewed after revalidation; revocation is
terminal. Studio exposes these states and actions without conflating them with certification.

Photoshop retains its deterministic JSX implementation behind the typed action boundary. A qualified
UXP RPC transport can replace that implementation per action without changing Skill Graphs. An
unqualified UXP endpoint never receives work, and any failure after UXP contact is unknown completion,
requiring actual-state reconciliation rather than JSX fallback.

Character-production stages now name `CharacterProductionAutonomy@1.1.0` and the exact
`fabric.skill-graph-input-binding.v1` contract instead of carrying only a boolean governance hint.
The typed runtime resolves that exact registered commission, never “latest”, seals every graph input
to one authoritative Jira revision and per-field source digest, compiles only inside commissioned
roots, and reuses the one supervisor result across the Photoshop and Unity canvas stages. Jira may
supply the required values only through one structured `fabric-character-inputs` block; prose is not
converted into paths, component IDs, properties or build actions by guesswork.

Flat Art input binding has a deterministic learning step before physical compilation. It retrieves
the attributable Importing Flat Art SOP from workspace RAG (falling back only to the reviewed
repository snapshot), scans released `Flat Art/*.png` plus `.png.meta` pairs inside the allowed
characters root, and measures the established five-sprite framing and pivot conventions. An exact
released character may reuse its own metadata. A new or in-progress character must supply its own
alpha bounds and confidently observed eye point; the selector may reuse a prior character's crop
rectangles but never that character's eye pivot. The selected asset digest, SOP revision/digest,
target observation and derived layout digest enter the sealed run evidence. The active legacy Flat
Art agent and the versioned character graph both apply the result through
`unity.set_flat_art_sprite_layout`; unavailable evidence, invalid geometry, Unity import errors or
provider loss stop safely. This is grounded retrieval and precedent analysis, not hidden model-weight
training, and it grants no certification, publication or commissioning authority.

Every newly created agent now receives the same universal evidence-first pre-planning spine at the
store boundary, regardless of whether it originated in Studio, Fabric, an import or a backend API.
It inspects the current task and target, retrieves attributable wiki/workspace knowledge, examines
matching released assets and qualified prior runs, and then binds supported findings into the plan.
Empty searches require retained receipts; unrelated target-specific values cannot be copied; missing
or contradictory required evidence blocks dependent physical writes. Certification validates the
contract and stage order, while legacy agents remain unchanged until explicitly upgraded. These
read-only controls add no publication or commissioning authority.

Commission drift is audited continuously by a backend daemon rather than only when an operator opens
the Skill Graph window. Expiry and provider/manifest drift suspend immediately. Required SOP and
environment evidence comes from the JSON state files named by
`FABRIC_SKILL_GRAPH_SOP_STATE_FILE` and `FABRIC_SKILL_GRAPH_ENVIRONMENT_FILE`; missing, unreadable
or changed probe state suspends fail-closed. Every suspended graph is placed in an observable
requalification queue. This monitor cannot renew, publish or commission anything.

The UXP lane now includes an installable provider source package, owner-only bearer token, loopback
HTTP/WebSocket sidecar, exact request correlation and modal named handlers. It implements Smart Object
relink, layer comps, text style, color profiles, WebP, artboard/atlas export and history snapshots in
addition to the base document surface. These deeper handlers remain `production_ready=false` until
their excluded live qualification evidence exists; they are implementation-ready candidates, not a
paper promotion. A signed Adobe-distributed package is an external deployment artifact.

## Acceptance criteria

1. 100% of generated physical operations carry attributable evidence and an immutable spec digest.
2. Raw model-generated code never crosses directly into Photoshop or Unity execution.
3. Known tasks use registered primitives without human implementation.
4. Unsupported tasks automatically create a capability candidate and workbench plan.
5. Candidates cannot execute until static, compile, fixture, dry-run, rollback, and independent-review
   evidence pass.
6. Every protected effect uses exact approval, fencing, idempotency, and a durable checkpoint.
7. Every output is verified from actual Photoshop/Unity/filesystem evidence.
8. No run completes merely because JSX/C# returned success or Unity exited zero.
9. Unknown completion never auto-retries.
10. A pilot demonstrates ticket → generated/selected tool → execution → verification → Jira completion
    with retained evidence and no manual production work beyond approval/judgment. Production
    requires at least 20 unique cases for the exact pilot, every hard metric at 10/10 and a separate
    exact human approval. Collecting that real-ticket evidence remains an operator qualification
    activity rather than a repository-test claim.

## Rejected alternatives

- Give the LLM direct JSX/C# execution.
- Treat wiki text as trusted code.
- Require humans to implement every missing binding.
- Generate a one-off backend branch per ticket.
- Promote a tool because it compiles once.
- Let the authoring model approve its own candidate.