@dailephd/my-frontend-observer 0.9.0 → 0.10.0

package/docs/plans/v0.10-implementation-plan.md

@@ -0,0 +1,1509 @@
+# v0.10 Implementation Plan — Full Visual Human–LLM Frontend Change Workflow
+
+## 1. Status and authority
+
+This document is the frozen concrete implementation plan for
+`my-frontend-observer` v0.10.
+
+It was created during v0.10 version-start planning after reviewing:
+
+- `docs/PROJECT_DESCRIPTION.md`;
+- `docs/PROJECT_MILESTONES.md`;
+- `docs/ROADMAP.md`;
+- `docs/CURRENT_STATE.md`;
+- `docs/ARCHITECTURE.md`;
+- `docs/CONTRACTS.md`;
+- `docs/WORKFLOWS.md`;
+- the frozen v0.8, v0.8.1, v0.9, and v0.9.1 plans;
+- the read-only Observer v0.10 architecture/seam reconnaissance at tagged
+  `v0.9.1`;
+- the read-only `my-dev-kit-orchestrator@1.3.3` seam reconnaissance used to
+  settle the cross-project ownership boundary.
+
+The Observer reconnaissance used the published
+`@dailephd/my-dev-kit@1.12.3` and established the current v0.9.1 owners for
+project workflow, `checkProject`, canonical Chromium capture, correction
+preparation/review, annotation persistence, contract promotion, reference
+materialization, and bounded-context projection.
+
+The orchestrator reconnaissance independently resolved the same published
+`@dailephd/my-dev-kit@1.12.3` and established that
+`my-dev-kit-orchestrator` owns run/stage lifecycle, prompts, readiness,
+correction routing, artifact staleness, judge integrity, and final-report
+eligibility, but does not execute coding agents, edit source, run Observer,
+perform runtime/reference evaluation, or own baseline/reference approval.
+
+This document governs v0.10 implementation scope, architecture, public and
+internal contracts, batch order, and validation expectations unless the user
+explicitly revises it.
+
+This document is planning authority only. It does not prove that any v0.10
+batch has been implemented. Actual implementation and release state remain
+owned by repository evidence and `docs/CURRENT_STATE.md`.
+
+The package remains `0.9.1` until a separate release-preparation workflow
+explicitly changes it after implementation, documentation reconciliation, and
+pre-release readiness.
+
+## 2. Version objective
+
+Complete the visual communication branch by combining the already released:
+
+- v0.7 correction/reference loop;
+- v0.8 viewer;
+- v0.8.1 project workflow and canonical `check` surface;
+- v0.9 dual-context structured annotation;
+
+into one complete human–LLM frontend-change workflow.
+
+Two human entry modes must coexist.
+
+Actual-frontend-driven:
+
+```text
+human views a captured runtime frontend
+→ annotates requested visual change
+→ confirms structured runtime intent
+→ executable change scope is frozen
+```
+
+Reference-driven:
+
+```text
+human selects an approved external visual reference
+→ views reference beside current runtime frontend
+→ annotates reference intent
+→ confirms reference requirements
+→ explicitly binds reference regions to runtime targets
+→ executable reference scope is frozen
+```
+
+Both converge on:
+
+```text
+frozen visual-change scope
+→ bounded runtime/reference evidence
+→ bounded static evidence when supplied by the external coordination layer
+→ coding-agent handoff
+→ external coding agent changes target source
+→ Observer captures the new runtime state
+→ canonical check runs
+→ comparison + contract evaluation + reference fidelity run as applicable
+→ immutable correction-attempt history is recorded
+→ human accepts, requests another correction, or abandons
+→ optional baseline/reference governance actions remain explicit
+```
+
+v0.10 does not turn Observer into a source editor, coding-agent executor,
+workflow orchestrator, or autonomous image-to-code system.
+
+## 3. Frozen cross-project responsibility split
+
+### 3.1 Observer owns visual/product semantics
+
+Observer remains the canonical owner of:
+
+- runtime observations;
+- screenshots and rendered evidence;
+- external-reference evidence;
+- reference applicability and runtime binding;
+- annotation and confirmation;
+- frontend contracts and contract evaluation;
+- reference fidelity;
+- project-level `check` result semantics;
+- visual-change request/attempt identity;
+- immutable visual-change history;
+- final human disposition for the visual change;
+- baseline/reference approval and supersession operations.
+
+### 3.2 my-dev-kit remains the static-evidence owner
+
+Observer must not duplicate:
+
+- repository indexing;
+- symbol graphs;
+- dependency graphs;
+- architecture analysis;
+- static source ownership inference;
+- bounded source retrieval.
+
+v0.10 may consume bounded static evidence through the existing context/correlation
+boundary, but Observer must not invoke or embed a second my-dev-kit runtime.
+
+### 3.3 my-dev-kit-orchestrator remains the workflow lifecycle owner
+
+Orchestrator may coordinate:
+
+- run and stage progression;
+- generated prompts;
+- context readiness;
+- implementation/test/verification artifact lifecycle;
+- correction routing;
+- downstream staleness;
+- judge integrity;
+- final-report eligibility.
+
+Observer must not reimplement those lifecycle concepts.
+
+Orchestrator workflow PASS remains distinct from Observer product approval.
+
+### 3.4 External coding agent remains the source editor
+
+Neither Observer nor the v0.10 workflow artifact may edit target source.
+
+The source-edit boundary remains:
+
+```text
+Observer visual-change evidence / handoff
+→ external coding agent or orchestrator-managed prompt workflow
+→ target source changes
+→ Observer rerender/check
+```
+
+### 3.5 Lab remains optional
+
+`my-dev-kit-lab` is not a production dependency and is not required for every
+normal visual change.
+
+It may be used later for ecosystem compatibility, tutorial, regression, or
+release-readiness validation.
+
+## 4. Frozen version-start architecture decisions
+
+### 4.1 One new persisted Observer evidence family
+
+v0.10 introduces exactly one new persisted Observer-owned evidence family for
+workflow/history traceability:
+
+```text
+VisualChangeWorkflowArtifact
+artifactKind: my-frontend-observer/visual-change-workflow
+schemaVersion: 1.0.0
+```
+
+Its responsibility is narrow:
+
+- freeze the exact visual-change request scope;
+- retain immutable attempt history;
+- connect existing canonical evidence by identity/reference;
+- retain final human disposition;
+- optionally retain an external coordinator reference.
+
+It must not become a second:
+
+- observation artifact;
+- comparison artifact;
+- evaluation artifact;
+- frontend contract;
+- external-reference artifact;
+- visual annotation artifact;
+- bounded-agent-context artifact;
+- orchestrator run log.
+
+Canonical evidence is referenced, not copied wholesale.
+
+### 4.2 Existing canonical schemas remain unchanged
+
+v0.10 does not plan a version bump for:
+
+- observation schema `1.2.0`;
+- comparison schema `1.0.0`;
+- frontend contract schema `1.0.0`;
+- evaluation artifact schema `1.0.0`;
+- bounded-agent-context schema `1.0.0`;
+- external-reference schema `1.0.0`;
+- visual annotation schema `1.0.0`;
+- Viewer protocol `1.3.0` unless an actual protocol-incompatible change is
+  discovered during implementation.
+
+Adding the new visual-change artifact family does not require modifying those
+existing families.
+
+If implementation discovers a concrete incompatibility, stop the affected
+batch and revise this plan before changing an existing schema/protocol version.
+
+### 4.3 Project-aware Viewer is the human visual workflow entry point
+
+Normal v0.10 human interaction continues through:
+
+```text
+my-frontend-observer view
+```
+
+The project-aware Viewer gains a Visual Change workspace.
+
+Standalone:
+
+```text
+my-frontend-observer view --root <evidence-root>
+```
+
+remains read-only.
+
+Do not add a second graphical application.
+
+### 4.4 Both entry modes use one workflow/history model
+
+`VisualChangeWorkflowArtifact.entryMode` is exactly:
+
+```text
+actual-frontend
+reference
+```
+
+The two modes differ only in how the frozen request scope is constructed.
+
+After scope confirmation, both use the same:
+
+- handoff boundary;
+- external edit boundary;
+- canonical `check` path;
+- immutable attempt record;
+- human review/disposition model.
+
+### 4.5 Canonical post-edit evaluation remains `checkProject`
+
+The normal post-edit acceptance path remains the existing canonical project
+check implementation.
+
+The v0.10 Viewer or application service must call the same
+`checkProject` owner used by:
+
+```text
+my-frontend-observer check <baseline> --json
+```
+
+Do not recreate:
+
+- before/after comparison;
+- frontend-contract verdicts;
+- reference fidelity;
+- unexpected-change handling;
+- overall PASS / FAIL / REVIEW_REQUIRED / BLOCKED precedence.
+
+The machine-facing CLI command remains available and its existing behavior
+without a visual workflow remains unchanged.
+
+### 4.6 Visual workflow activation is explicit
+
+Creating a visual-change workflow artifact does not silently mutate project
+acceptance state.
+
+Before the canonical check loop can evaluate workflow-specific executable
+scope, the user must explicitly activate the workflow's relevant project
+acceptance inputs through one bounded project-aware operation.
+
+Activation may set only the already-supported project acceptance inputs needed
+for the workflow:
+
+- the promoted per-change contract for actual-frontend mode;
+- the selected approved reference and explicit binding input for reference
+  mode.
+
+Activation is not approval.
+
+The workflow revision must record enough project-relative before/after
+acceptance state to make the change auditable and to support explicit restore.
+
+No activation operation may modify baseline/reference artifacts themselves.
+
+### 4.7 Reference selection does not require a second project reference registry
+
+Approved references remain discoverable through the existing evidence index.
+
+The reference-driven workflow freezes one exact approved reference identity and
+one explicit binding set in the workflow artifact.
+
+v0.10 does not introduce a second multi-reference approval registry merely for
+selection.
+
+Selecting a reference for one workflow is distinct from:
+
+- importing it;
+- approving it;
+- superseding it.
+
+### 4.8 Bindings remain explicit
+
+Reference-region ↔ runtime-target bindings are never inferred from:
+
+- matching names;
+- geometry;
+- visual proximity;
+- annotation overlap.
+
+The visual-change workflow may persist the exact bounded binding declarations
+needed to reproduce its request because there is currently no separate
+canonical binding artifact family.
+
+### 4.9 Correction attempts are Observer-domain evidence, not orchestrator stage attempts
+
+Orchestrator stage artifacts are mutable, path-based, and may be regenerated
+during correction.
+
+Therefore they are not the authority for immutable visual correction history.
+
+Observer persists an immutable visual-change attempt record for every checked
+candidate.
+
+An orchestrator run may be referenced by ID, but its mutable stage files do not
+replace Observer attempt identity/history.
+
+### 4.10 Orchestrator integration is optional and reference-based
+
+v0.10 must not add `my-dev-kit-orchestrator` as a runtime dependency.
+
+A visual workflow may carry an optional external coordination reference:
+
+```text
+provider: my-dev-kit-orchestrator
+runId: <opaque run id>
+packageVersion: <optional version>
+```
+
+Observer does not:
+
+- read orchestrator run folders as canonical evidence;
+- mutate orchestrator lifecycle state;
+- decide orchestrator judge verdicts;
+- treat final-report PASS as product approval.
+
+The first v0.10 integration should use the existing file/CLI/report boundary.
+Do not create a new orchestrator public lifecycle API unless a later concrete
+implementation blocker proves it necessary.
+
+### 4.11 Final human acceptance is an Observer action
+
+Workflow completion and product acceptance remain distinct.
+
+A human may accept a visual-change attempt only when the latest canonical
+Observer check result is `PASS`.
+
+`FAIL`, `BLOCKED`, and `REVIEW_REQUIRED` cannot be silently accepted as a
+successful v0.10 final state.
+
+Final human acceptance records a disposition on the workflow history.
+
+It does not automatically:
+
+- approve a baseline;
+- approve a reference;
+- supersede a reference;
+- activate a contract.
+
+Those remain separate explicit governance operations.
+
+### 4.12 Scope changes create a new request identity
+
+Changing any frozen executable request input after attempts have begun creates
+a new visual-change request identity.
+
+Examples include:
+
+- changing the confirmed annotation;
+- changing the promoted contract;
+- selecting a different approved reference;
+- changing reference bindings;
+- changing the canonical baseline observation used to define the request.
+
+Do not append attempts produced under materially different request scope to the
+same request identity.
+
+A new workflow revision may point to an earlier workflow artifact for history,
+but its new request identity and attempt sequence remain explicit.
+
+## 5. VisualChangeWorkflowArtifact contract
+
+Exact helper names may follow repository conventions. The semantic ownership and
+rules below are frozen.
+
+### 5.1 Constants
+
+Conceptually:
+
+```ts
+export const VISUAL_CHANGE_WORKFLOW_ARTIFACT_KIND =
+  'my-frontend-observer/visual-change-workflow' as const;
+
+export const VISUAL_CHANGE_WORKFLOW_SCHEMA_VERSION = '1.0.0' as const;
+
+export const MAX_VISUAL_CHANGE_ATTEMPTS = 20;
+```
+
+The attempt bound prevents indefinite unbounded history growth inside one
+artifact lineage.
+
+### 5.2 Request scope
+
+Conceptually:
+
+```ts
+type VisualChangeEntryMode =
+  | 'actual-frontend'
+  | 'reference';
+
+interface VisualChangeBaselineRef {
+  observationId: string;
+  requestId: string;
+}
+
+interface VisualChangeActualScope {
+  entryMode: 'actual-frontend';
+  annotationId: string;
+  changeContractId: string;
+}
+
+interface VisualChangeReferenceScope {
+  entryMode: 'reference';
+  annotationId: string;
+  approvedReferenceId: string;
+  approvedReferenceRequestId: string;
+  bindings: ExternalReferenceRuntimeBindingDeclaration[];
+}
+
+type VisualChangeScope =
+  | VisualChangeActualScope
+  | VisualChangeReferenceScope;
+```
+
+The workflow also freezes:
+
+- canonical baseline observation identity;
+- persistent baseline contract identity when configured;
+- exact project change-contract identity when applicable;
+- exact selected approved-reference identity when applicable;
+- exact binding declarations when applicable.
+
+Mutable aliases and absolute paths are not request identity.
+
+### 5.3 Request and revision identity
+
+`visualChangeRequestId` is deterministic over canonical semantic request scope.
+
+It must include, as applicable:
+
+- entry mode;
+- canonical baseline observation identity;
+- confirmed annotation identity;
+- promoted per-change contract identity and clause content identity;
+- selected approved reference request/instance identity;
+- explicit binding declarations;
+- configured persistent baseline contract identity relevant to evaluation.
+
+Repeated canonical promotion of semantically equivalent runtime intent may
+produce the same per-change `contractRequestId`, but every promotion produces
+a fresh `contractId`. Because the visual-change request freezes the exact
+promoted per-change contract instance, `contractId` remains part of
+`visualChangeRequestId`. A new promotion therefore produces a new
+`visualChangeRequestId` even when its `contractRequestId` is semantically
+equivalent to an earlier promotion.
+
+`contractRequestId` expresses semantic contract-request equivalence.
+`contractId` expresses exact immutable contract-instance identity.
+`visualChangeRequestId` expresses the frozen visual-change request bound to
+that exact contract instance. v0.10 must not deduplicate, reuse, or silently
+substitute an earlier promoted contract merely to preserve a
+`visualChangeRequestId`.
+
+It excludes:
+
+- timestamps;
+- output directories;
+- Viewer handles;
+- browser ports;
+- absolute paths;
+- orchestrator run-folder paths.
+
+`visualChangeWorkflowId` is a fresh persisted instance identity.
+
+A new artifact revision uses:
+
+```text
+supersedesVisualChangeWorkflowId
+```
+
+and never rewrites its parent.
+
+### 5.4 Attempt identity
+
+v0.10 adds one visual-workflow attempt identity valid for both entry modes:
+
+```text
+visualChangeAttemptId
+= deterministic hash(
+    visualChangeRequestId,
+    candidateObservationId
+  )
+```
+
+The same request plus the same candidate observation must produce the same
+attempt identity.
+
+A different candidate observation must produce a different attempt identity.
+
+Reference-driven attempts may additionally retain the existing v0.7
+`referenceCorrectionAttemptId` for cross-version traceability.
+
+Do not replace the v0.7 identity.
+
+### 5.5 Attempt record
+
+Conceptually:
+
+```ts
+interface VisualChangeAttemptRecord {
+  visualChangeAttemptId: string;
+  priorVisualChangeAttemptId?: string;
+
+  candidateObservation: {
+    observationId: string;
+    requestId: string;
+    artifactRef: string;
+  };
+
+  check: VisualChangeCheckSnapshot;
+
+  referenceCorrectionAttemptId?: string;
+
+  coordination?: {
+    provider: 'my-dev-kit-orchestrator';
+    runId: string;
+    packageVersion?: string;
+  };
+
+  review: {
+    state: 'pending' | 'correction-requested' | 'accepted' | 'abandoned';
+    decidedAt?: string;
+  };
+
+  recordedAt: string;
+}
+```
+
+`artifactRef` is project-relative and portable.
+
+### 5.6 Check snapshot
+
+The attempt stores a bounded normalized snapshot of the canonical
+`CheckWorkflowResult`.
+
+It must preserve enough identity/status evidence to establish exactly what was
+evaluated without copying full comparison/evaluation/reference artifacts.
+
+At minimum preserve:
+
+- overall check status;
+- baseline observation ID;
+- candidate observation ID;
+- comparison ID and project-relative artifact reference when produced;
+- contract evaluation ID/reference when produced;
+- active baseline/per-change contract identities;
+- reference ID when applicable;
+- reference-fidelity state;
+- failed/unavailable contract clause identifiers or bounded counts according
+  to the existing check contract;
+- failed/unavailable reference requirement identifiers or bounded counts
+  according to the existing check contract;
+- unexpected-change summary already exposed by check;
+- blocker codes/reasons.
+
+Do not persist absolute operational paths from CLI JSON.
+
+The snapshot is traceability evidence only. The referenced canonical artifacts
+remain authoritative.
+
+### 5.7 Activation record
+
+A workflow may include an explicit project-acceptance activation record.
+
+It records project-relative before/after values required to show:
+
+- which per-change contract was activated;
+- which approved reference/binding configuration was activated;
+- when activation occurred;
+- whether an explicit restore later occurred.
+
+Activation does not imply approval.
+
+### 5.8 Human disposition
+
+A workflow is not accepted merely because a check passed.
+
+The human review operation explicitly records:
+
+```text
+pending
+correction-requested
+accepted
+abandoned
+```
+
+Rules:
+
+- `accepted` requires the latest attempt check status to be `PASS`;
+- `correction-requested` may follow a non-passing or passing attempt;
+- `abandoned` ends the human workflow without approving baseline/reference;
+- a new correction attempt after `correction-requested` must point to the
+  prior visual-change attempt ID;
+- no attempt may be silently overwritten.
+
+### 5.9 Governance references
+
+After final acceptance, optional explicit governance actions may be recorded by
+identity/reference:
+
+- baseline approval artifact;
+- approved/superseding external-reference artifact;
+- restored/replaced project acceptance state.
+
+The workflow artifact records these results only after the existing canonical
+governance services succeed.
+
+It never performs them implicitly.
+
+## 6. Persistence architecture
+
+Follow the established immutable-artifact pattern.
+
+Expected ownership:
+
+```text
+src/domain/visualChangeWorkflow.ts
+src/domain/visualChangeWorkflowIdentity.ts
+src/artifacts/visualChangeWorkflowArtifactWriter.ts
+src/artifacts/visualChangeWorkflowArtifactReader.ts
+src/application/visualChangeWorkflowPersistenceService.ts
+```
+
+The writer must:
+
+1. validate the complete workflow artifact;
+2. derive the final directory from `visualChangeWorkflowId`;
+3. refuse overwrite of an existing final directory;
+4. write through a sibling temporary directory;
+5. write `manifest.json`;
+6. atomically rename the temporary directory;
+7. remove temporary output on failure.
+
+No screenshot, source image, observation manifest, contract manifest, comparison
+artifact, evaluation artifact, or external-reference image is copied into the
+workflow directory.
+
+Reference-mode binding declarations may be written as bounded workflow-owned
+input when needed by the existing project check/reference-evaluation path.
+
+Managed layout:
+
+```text
+.frontend-observer/
+  evidence/
+    visual-changes/
+      <visualChangeWorkflowId>/
+        manifest.json
+        bindings.json        # reference mode only, when required
+```
+
+The workflow reader must validate all references structurally and fail closed on
+unsafe project-relative paths.
+
+## 7. Project acceptance activation
+
+### 7.1 No hidden activation
+
+Creating or saving a workflow does not change project acceptance configuration.
+
+### 7.2 Actual-frontend activation
+
+Actual mode requires a canonical per-change contract produced through the v0.9
+promotion path.
+
+The user explicitly activates that contract through the existing project
+change-contract activation owner.
+
+If another per-change contract is currently active, the UI must disclose the
+replacement before the user confirms it.
+
+### 7.3 Reference activation
+
+Reference mode requires:
+
+- lifecycle `approved`;
+- exact applicability/compatibility semantics;
+- explicit binding declarations.
+
+Add one narrow application service that activates the selected approved
+reference and binding input in the already-existing project acceptance
+configuration.
+
+It must not approve the reference.
+
+It must preserve the previous project-relative reference configuration in the
+workflow activation record.
+
+### 7.4 Restore
+
+A workflow may offer an explicit restore action that reapplies the recorded
+pre-activation project acceptance values.
+
+Restore is not automatic on failure or abandonment.
+
+## 8. Coding-agent handoff contract
+
+v0.10 adds a pure bounded handoff projection, not a new persisted evidence
+family.
+
+Conceptually:
+
+```ts
+interface VisualChangeAgentHandoff {
+  visualChangeRequestId: string;
+  visualChangeWorkflowId: string;
+  entryMode: VisualChangeEntryMode;
+
+  confirmedScope: ...;       // canonical references only
+  runtimeEvidence: ...;      // bounded canonical references
+  referenceEvidence?: ...;   // bounded canonical references
+  boundedAgentContext?: BoundedAgentContext;
+
+  expectedPostEditCheck: {
+    baseline: string;
+    command: 'check';
+    json: true;
+  };
+
+  externalCoordination?: {
+    provider: 'my-dev-kit-orchestrator';
+    runId: string;
+  };
+}
+```
+
+Rules:
+
+- reuse existing `BoundedAgentContext` unchanged when supplied/constructed
+  through the existing v0.6 owner;
+- do not add visual-workflow fields to the bounded-agent-context schema solely
+  for convenience;
+- reference mode may reuse `prepareReferenceCorrection` and its deterministic
+  review identity;
+- actual mode projects the confirmed contract/runtime scope through the
+  existing bounded-context machinery;
+- static/source evidence remains externally produced;
+- handoff preparation never edits target source;
+- handoff preparation never starts or drives an orchestrator run.
+
+The handoff must make the required post-edit acceptance operation explicit:
+
+```text
+my-frontend-observer check <baseline> --json
+```
+
+## 9. Viewer read model
+
+Extend evidence discovery/classification for the new artifact family.
+
+Bounded index metadata should include:
+
+- workflow ID;
+- request ID;
+- entry mode;
+- baseline observation ID;
+- confirmed annotation ID;
+- selected reference ID when applicable;
+- attempt count;
+- latest attempt status;
+- latest human review state;
+- superseded workflow ID when present.
+
+Full history remains on-demand.
+
+Add one visual-change view projection that resolves:
+
+```text
+workflow
+→ baseline observation
+→ annotation
+→ promoted contract when applicable
+→ selected approved reference when applicable
+→ attempt candidate observations
+→ comparison/evaluation/reference evidence referenced by check snapshots
+```
+
+The Viewer must treat unavailable referenced evidence honestly and must not guess
+replacement evidence.
+
+## 10. Project-aware Viewer write boundary
+
+v0.10 extends the existing project-aware authoring boundary.
+
+All new write routes require the existing:
+
+- valid initialized project;
+- loopback host boundary;
+- same-origin checks;
+- in-memory authoring capability token;
+- JSON content type;
+- body bounds;
+- no-store responses;
+- safe project-contained path validation.
+
+Standalone `view --root` remains read-only.
+
+Conceptual project-aware operations:
+
+```text
+POST /api/visual-changes
+POST /api/visual-changes/:handle/activate
+POST /api/visual-changes/:handle/prepare-handoff
+POST /api/visual-changes/:handle/check
+POST /api/visual-changes/:handle/review
+POST /api/visual-changes/:handle/restore-acceptance
+```
+
+Exact route spelling may follow existing server conventions, but these operations
+must remain distinct.
+
+Do not add generic filesystem mutation endpoints.
+
+## 11. Actual-frontend-driven workflow
+
+The first mode must implement:
+
+```text
+project-aware Viewer
+→ select runtime observation used as visual request baseline
+→ create/load runtime annotation
+→ explicitly associate marks with runtime targets/relationships
+→ confirm supported change intent
+→ promote selected confirmed intent to canonical per-change contract
+→ explicitly activate that contract
+→ create/freeze VisualChangeWorkflowArtifact
+→ prepare bounded coding-agent handoff
+→ external edit
+→ check current frontend through canonical checkProject
+→ persist immutable attempt revision
+→ inspect PASS/FAIL/REVIEW_REQUIRED/BLOCKED evidence
+→ request correction or accept
+```
+
+Rules:
+
+- only confirmed, promotable runtime intent may enter executable scope;
+- confirmed `remove` remains non-promotable under the current contract
+  vocabulary;
+- informational marks may remain in annotation but are not executable scope;
+- the selected runtime observation and contract identities are frozen into the
+  request identity;
+- a later scope change creates a new request identity.
+
+## 12. Reference-driven workflow
+
+The second mode must implement:
+
+```text
+project-aware Viewer
+→ discover/select an existing approved reference
+→ inspect reference beside current runtime frontend
+→ create/load reference annotation
+→ confirm reference regions/requirements
+→ materialize a new reference revision if needed
+→ explicitly approve that revision if the user wants it to become the selected
+  approved reference
+→ explicitly bind selected reference regions to runtime targets
+→ create/freeze VisualChangeWorkflowArtifact
+→ explicitly activate selected reference/bindings for project check
+→ prepare bounded coding-agent handoff
+→ external edit
+→ canonical checkProject
+→ persist immutable attempt revision
+→ inspect fidelity + contract + overall evidence
+→ request correction or accept
+```
+
+Rules:
+
+- workflow start requires lifecycle `approved`;
+- imported/materialized references do not qualify until explicitly approved;
+- applicability/compatibility rules remain canonical;
+- bindings remain explicit;
+- reference-fidelity PASS cannot override a contract failure;
+- no raster-to-code interpretation is introduced.
+
+## 13. Correction iteration model
+
+One visual-change request may contain up to
+`MAX_VISUAL_CHANGE_ATTEMPTS` immutable attempts.
+
+Each attempt is:
+
+```text
+same frozen request identity
++ new candidate observation
++ canonical check result
++ optional existing reference-correction attempt identity
++ optional external coordinator run reference
++ human review decision
+```
+
+The normal loop is:
+
+```text
+attempt N check
+→ FAIL / REVIEW_REQUIRED / BLOCKED
+→ human requests correction
+→ external coding-agent correction
+→ fresh candidate capture/check
+→ attempt N+1
+```
+
+No retry occurs automatically inside Observer.
+
+A failed attempt remains inspectable after later success.
+
+## 14. Human acceptance and governance
+
+### 14.1 Accept result
+
+The Viewer may enable `Accept result` only when the latest check status is
+`PASS`.
+
+Acceptance creates a new immutable workflow revision.
+
+### 14.2 Baseline governance remains separate
+
+After acceptance, the user may separately invoke the existing canonical
+baseline-approval path against the accepted candidate according to the existing
+baseline contract semantics.
+
+The workflow may record the resulting baseline artifact identity.
+
+It must not fabricate new baseline rules.
+
+### 14.3 Reference governance remains separate
+
+If reference authoring/materialization produced a successor reference, the user
+may separately approve/supersede it through the existing canonical reference
+service.
+
+The workflow may record the resulting approved reference identity.
+
+Acceptance alone does not approve or supersede a reference.
+
+### 14.4 Orchestrator workflow success remains separate
+
+An orchestrator final-report PASS may be displayed as coordination evidence when
+linked, but cannot:
+
+- mark the visual change accepted;
+- approve a baseline;
+- approve/supersede a reference;
+- activate a contract.
+
+## 15. Orchestrator compatibility boundary
+
+The initial v0.10 product implementation does not require an orchestrator code
+change.
+
+Observer exposes enough bounded handoff/reference information for an external
+caller to:
+
+1. start/continue a normal orchestrator run;
+2. provide Observer evidence to the run through existing file/report/context
+   seams;
+3. let the external coding agent perform the edit;
+4. run Observer `check <baseline> --json`;
+5. reference the resulting Observer attempt/evidence in verification/judge
+   reporting.
+
+A v0.10 compatibility test may exercise the published orchestrator CLI from a
+disposable fixture, but Observer must not depend on its internal APIs or mutable
+run-file format.
+
+If implementation proves that the existing CLI/file boundary cannot preserve
+required identity/provenance, stop and revise this plan before adding a new
+orchestrator public integration contract.
+
+## 16. PWA and acceptance-gate rule carried from v0.9.1
+
+Any test explicitly designated:
+
+```text
+HARD GATE
+SECURITY GATE
+ACCEPTANCE GATE
+```
+
+must establish every material prerequisite itself from fresh state.
+
+It must not rely on:
+
+- previous test order;
+- warmed browser/service-worker cache;
+- a reused browser profile;
+- another test's server;
+- another test's evidence fixture.
+
+Do not copy the old weak service-worker readiness expression into new gates.
+
+v0.10 does not otherwise redesign PWA caching.
+
+## 17. Implementation sequence
+
+### Batch 1 — Visual-change workflow domain, identity, persistence, and discovery
+
+#### Goal
+
+Introduce the one new persisted workflow/history family without changing
+existing evidence schemas or Viewer behavior.
+
+#### Production scope
+
+- `VisualChangeWorkflowArtifact` contract and validator;
+- request/revision/attempt identity helpers;
+- bounded attempt/history rules;
+- immutable writer/reader/persistence service;
+- project-managed `evidence/visual-changes/` layout;
+- optional workflow-owned reference binding file;
+- evidence discovery/classification metadata;
+- on-demand workflow read projection.
+
+#### Mandatory tests
+
+- schema/validator positives and negatives;
+- deterministic request identity;
+- fresh workflow revision identity;
+- deterministic attempt identity;
+- changed candidate changes attempt identity;
+- changed scope changes request identity;
+- immutable revision/supersession behavior;
+- attempt bound;
+- unsafe path/reference rejection;
+- writer cleanup on failure;
+- discovery metadata;
+- no mutation/copy of referenced canonical artifacts.
+
+#### Gate
+
+The new family persists and reloads independently while all prior artifact
+families and schemas remain unchanged.
+
+### Batch 2 — Project workflow composition, activation, and canonical check recording
+
+#### Goal
+
+Connect the new workflow history to existing project acceptance and
+`checkProject` without adding a second evaluator.
+
+#### Production scope
+
+- create/freeze actual/reference workflow application service;
+- explicit project acceptance activation;
+- explicit restore operation;
+- canonical check invocation through `checkProject`;
+- normalized check snapshot;
+- append immutable attempt revision;
+- verify check result identities match frozen request scope;
+- reject hidden scope/config drift;
+- preserve existing `check` behavior outside v0.10 workflow use.
+
+#### Mandatory tests
+
+- actual-mode scope creation;
+- reference-mode scope creation;
+- activation is explicit;
+- activation is not approval;
+- restore is explicit;
+- canonical check called once through existing owner;
+- baseline contract remains active;
+- selected workflow contract/reference is evaluated;
+- reference PASS + contract FAIL remains overall FAIL;
+- mismatched scope/config blocks attempt recording;
+- existing CLI/project check regressions remain unchanged.
+
+#### Gate
+
+A caller can create a frozen workflow, explicitly activate it, run the canonical
+check path, and persist one immutable attempt without Viewer UI.
+
+### Batch 3 — Viewer discovery, visual-change workspace, and secure API boundary
+
+#### Goal
+
+Expose the workflow/history family in the existing project-aware Viewer and add
+only the bounded write operations required by v0.10.
+
+#### Production scope
+
+- workflow metadata in `/api/index`;
+- on-demand visual-change view projection;
+- Visual Change navigation/workspace;
+- project-aware API operations for create/activate/check/review/restore;
+- reuse existing authoring token/origin/body/security guards;
+- standalone `view --root` remains read-only;
+- unavailable linked evidence displayed honestly.
+
+#### Mandatory tests
+
+- project-aware operations authorized;
+- standalone operations rejected;
+- missing/invalid/stale workflow source evidence reported honestly;
+- no arbitrary filesystem paths;
+- no token/path leakage;
+- no-store behavior;
+- existing annotation POST routes unchanged;
+- keyboard/accessibility basics for new workspace shell.
+
+#### Gate
+
+The Viewer can load and inspect a workflow artifact and exercise bounded project
+operations without yet completing either human entry mode.
+
+### Batch 4 — Actual-frontend-driven visual change flow
+
+#### Goal
+
+Complete the human runtime-screenshot entry mode from annotation through
+handoff-ready frozen executable scope.
+
+#### Production scope
+
+- choose runtime baseline/source observation;
+- reuse runtime annotation authoring;
+- confirm executable runtime intent;
+- promote selected supported intent;
+- explicit contract activation;
+- create/freeze actual-mode workflow;
+- show request identity and active scope;
+- block unsupported/unconfirmed requested scope;
+- prepare mode-independent workflow state for later handoff/check.
+
+#### Mandatory browser tests
+
+- successful actual-mode scope creation;
+- marks without explicit association stay non-executable;
+- candidate/unconfirmed intent cannot start executable workflow;
+- confirmed `remove` remains non-promotable;
+- explicit activation replaces no contract silently;
+- changing scope produces a new request identity;
+- existing annotation save/revision behavior preserved.
+
+#### Gate
+
+A human can create a frozen actual-frontend visual-change request in the Viewer
+without any external reference.
+
+### Batch 5 — Reference-driven visual change flow
+
+#### Goal
+
+Complete the reference entry mode using only approved references, explicit
+applicability/bindings, and existing reference semantics.
+
+#### Production scope
+
+- discover/select approved references from existing evidence;
+- reuse reference annotation/materialization;
+- explicit approval required for a materialized revision before workflow use;
+- explicit runtime binding authoring/selection;
+- create/freeze reference-mode workflow;
+- persist bounded binding declarations;
+- explicit project reference activation;
+- compatibility/applicability display;
+- request identity includes exact reference/binding scope.
+
+#### Mandatory browser tests
+
+- imported reference cannot start executable workflow;
+- approved reference can;
+- changing selected reference changes request identity;
+- changing bindings changes request identity;
+- name similarity never creates binding;
+- incompatible applicability blocks workflow/check;
+- activation does not approve/supersede;
+- reference and runtime coordinate systems remain separate.
+
+#### Gate
+
+A human can create a frozen reference-driven visual-change request using an
+approved reference and explicit bindings.
+
+### Batch 6 — Coding-agent handoff and optional orchestrator correlation
+
+#### Goal
+
+Produce one bounded external implementation handoff for either entry mode while
+preserving project boundaries.
+
+#### Production scope
+
+- pure `VisualChangeAgentHandoff` projection;
+- actual mode uses existing bounded context/project contract evidence;
+- reference mode reuses existing `prepareReferenceCorrection` where
+  applicable;
+- retain/reference deterministic v0.7 review identity;
+- optional external coordinator reference
+  (`my-dev-kit-orchestrator` run ID/version);
+- no orchestrator package/runtime dependency;
+- Viewer exposes/copies/downloads bounded handoff;
+- exact required post-edit `check <baseline> --json` operation is included.
+
+#### Mandatory tests
+
+- actual and reference handoff projections bounded/deterministic;
+- existing `BoundedAgentContext` schema unchanged;
+- no target source read/write;
+- no orchestrator execution;
+- no absolute orchestrator run path persisted;
+- optional run reference round-trips;
+- reference handoff preserves protected/preserved constraints;
+- producer/static evidence remains externally owned.
+
+#### Compatibility proof
+
+Run one disposable integration proof against the current published
+`my-dev-kit-orchestrator` CLI/file boundary without importing orchestrator
+internals.
+
+The proof must show that Observer evidence can be referenced in a run while
+Observer remains the runtime/reference evaluator and orchestrator remains the
+workflow lifecycle owner.
+
+#### Gate
+
+A coding agent or external orchestrator workflow can receive one bounded
+traceable handoff without direct artifact-path reconstruction by the human.
+
+### Batch 7 — Correction loop, immutable attempt history, and human acceptance
+
+#### Goal
+
+Complete repeated correction and explicit human review/governance.
+
+#### Production scope
+
+- Viewer action to run canonical project check after an external edit;
+- persist immutable attempt record;
+- show complete attempt timeline;
+- correction-requested action;
+- next attempt links to prior attempt;
+- reference mode retains existing reference-correction attempt identity;
+- accepted only on latest canonical PASS;
+- abandoned state;
+- explicit restore action;
+- optional recording of later baseline/reference governance results;
+- no automatic approval or retry.
+
+#### Mandatory browser/integration tests
+
+- attempt 1 FAIL -> correction requested -> attempt 2 PASS;
+- attempt 1 remains inspectable byte-for-byte;
+- candidate IDs/attempt IDs remain distinct;
+- protected regression fails even when requested/reference goal succeeds;
+- reference fidelity PASS + contract FAIL remains overall FAIL;
+- BLOCKED/REVIEW_REQUIRED cannot be accepted;
+- orchestrator PASS reference cannot cause Observer acceptance;
+- acceptance does not approve baseline/reference;
+- explicit governance action references are recorded only after canonical
+  services succeed.
+
+#### Gate
+
+Both visual entry modes can complete a human-reviewed correction cycle with
+immutable attempt history and explicit acceptance.
+
+### Batch 8 — Integrated acceptance, packed-candidate proof, and implementation documentation
+
+#### Goal
+
+Prove the complete v0.10 product surface as one integrated system and prepare
+for the separate documentation-reconciliation/readiness workflows.
+
+#### Required integrated scenarios
+
+1. Successful actual-frontend-driven visual change.
+2. Successful reference-driven design-replication change.
+3. Measurable actionable reference/candidate failure.
+4. Requested visual change succeeds locally but introduces a protected or
+   preserved regression -> overall FAIL.
+5. Reference fidelity passes while an active contract fails -> overall FAIL.
+6. Two-attempt correction history: first failure retained, second PASS.
+7. Human acceptance on PASS.
+8. Explicit baseline/reference governance remains separate.
+9. Optional orchestrator run reference remains traceable without becoming
+   product approval.
+10. Standalone Viewer remains read-only.
+11. Existing v0.9 annotation, v0.8 Viewer, v0.8.1 project workflow, and v0.7
+    correction behavior remain regression-safe.
+
+#### Browser acceptance
+
+Add one deterministic real-Chromium v0.10 integrated acceptance suite using the
+existing demo/fixture substrate where appropriate.
+
+Any test labeled `ACCEPTANCE GATE` must establish all material prerequisites
+from fresh state.
+
+#### Packed candidate
+
+Extend the existing same-candidate pre-release smoke architecture additively.
+
+Add a v0.10 packed workflow smoke that uses only the installed package and
+proves:
+
+- the new artifact reader/writer surface is packaged;
+- project-aware Viewer visual-change routes are present;
+- actual and reference workflow creation works;
+- at least one correction attempt is persisted;
+- acceptance rules hold;
+- prior evidence remains immutable;
+- no authoring token, note text, absolute project path, or local orchestrator
+  path leaks into the smoke summary.
+
+Do not create a second candidate tarball or parallel release matrix.
+
+#### Documentation
+
+Update current implementation documentation only after the integrated behavior
+exists.
+
+Do not mark v0.10 published.
+
+#### Gate
+
+All v0.10 implementation batches are complete and the version is ready for the
+separate hardened documentation/implementation-completeness workflow.
+
+## 18. Cross-batch invariants
+
+Every batch must preserve:
+
+1. Observer never edits target source.
+2. Canonical Chromium capture remains single-owner.
+3. `checkProject` remains the one project post-edit evaluation owner.
+4. Existing comparison, contract, relationship, reference, fidelity, and
+   bounded-context engines are reused.
+5. Visual annotations remain evidence, not contracts.
+6. Promotion remains separate from activation.
+7. Materialization remains separate from reference approval.
+8. Workflow creation remains separate from project acceptance activation.
+9. Workflow PASS/human acceptance remains separate from baseline/reference
+   approval.
+10. Orchestrator lifecycle remains externally owned.
+11. No existing canonical evidence schema is changed without an explicit plan
+    revision.
+12. Existing evidence remains immutable.
+13. Workflow revisions and attempts are immutable.
+14. Reference/runtime/static/annotation/workflow identities remain distinct.
+15. Missing/unavailable/ambiguous/incompatible evidence is never fabricated.
+16. Standalone `view --root` remains read-only.
+17. Project-aware write routes remain narrow and security-guarded.
+18. No automatic retry, coding-agent execution, baseline approval, or reference
+    approval is introduced.
+19. New acceptance/security gates are independently runnable from fresh state.
+20. Generated/local integration state remains outside the npm package.
+
+## 19. Version-wide validation
+
+After Batch 8, implementation validation must include the repository's complete
+current validation chain:
+
+```text
+npm run typecheck
+npm run lint
+npm test
+npm run test:browser
+npm run test:security
+npm run build
+npm run check:docs
+git diff --check
+npm pack --dry-run
+```
+
+Also run:
+
+- the v0.10 integrated browser acceptance suite;
+- the installed packed v0.10 workflow smoke;
+- any focused compatibility proof required for the external orchestrator
+  boundary.
+
+Do not treat this implementation validation as formal release readiness.
+
+After implementation passes, follow the established workflow:
+
+```text
+implementation complete
+→ hardened documentation + implementation-completeness reconciliation
+→ pre-release readiness / cross-platform / security
+→ release prep
+→ publication only after explicit user approval
+```
+
+## 20. Explicit v0.10 exclusions
+
+v0.10 does not include:
+
+- Observer editing application source;
+- built-in LLM/provider execution;
+- autonomous coding-agent execution;
+- automatic retry loops;
+- automatic baseline approval;
+- automatic reference approval/supersession;
+- automatic contract activation without explicit human action;
+- raster-to-code generation;
+- OCR/CV segmentation;
+- automatic binding from geometry/name similarity;
+- a second comparison engine;
+- a second contract evaluator;
+- a second reference-fidelity engine;
+- a second bounded-context engine;
+- a second orchestrator lifecycle;
+- a generic public orchestrator lifecycle API unless a concrete implementation
+  blocker forces a later plan revision;
+- a new cross-project shared package merely for symmetry;
+- changing existing evidence schema versions without proven need;
+- multi-user/server-hosted workflow state;
+- cloud synchronization;
+- public-internet canonical test fixtures.
+
+## 21. Prompt count and implementation order
+
+The implementation order is frozen as eight context-sharing batches:
+
+```text
+Batch 1
+Visual-change domain / identity / persistence / discovery
+
+Batch 2
+Project composition / activation / canonical check attempt recording
+
+Batch 3
+Viewer workspace / secure project-aware API
+
+Batch 4
+Actual-frontend-driven entry mode
+
+Batch 5
+Reference-driven entry mode
+
+Batch 6
+Coding-agent handoff / optional orchestrator correlation
+
+Batch 7
+Correction loop / immutable history / human acceptance
+
+Batch 8
+Integrated acceptance / packed candidate / implementation docs
+```
+
+Do not combine later-batch work into an earlier batch merely because adjacent
+owners are already open.
+
+Do not split release readiness, release preparation, or publication into these
+implementation batches.
+
+After each passing batch, the next coding-agent prompt must use the current
+repository state and this frozen plan as authority.
+
+If implementation evidence shows that a frozen architecture decision is
+incorrect or impossible, stop and revise this document explicitly before
+continuing.