@dailephd/my-frontend-observer 0.9.0 → 0.10.0

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

@@ -0,0 +1,468 @@
+# v0.9.1 Implementation Plan — PWA Hard-Gate Isolation
+
+Status: frozen planning authority; implementation not started.
+
+Base release: v0.9.0.
+
+Target maintenance version: v0.9.1.
+
+Primary defect owner: `tests/browser/pwaHardening.test.ts`.
+
+This plan is concrete implementation authority for the bounded v0.9.1
+maintenance patch. ROADMAP owns the version-level goal and constraints; this
+file owns the exact correction strategy, sequencing, tests, and gates.
+
+## 1. Problem statement
+
+The released PWA browser coverage contains a test named:
+
+`HARD GATE: after the server goes down, a reload never presents previously-fetched evidence as current`.
+
+That test passes in the normal file/suite order but fails when selected alone
+with Vitest `-t`.
+
+The current first PWA `describe` block creates one evidence root, one viewer
+server, and one persistent Chromium context in `beforeAll`. It launches that
+context from a fixed profile under:
+
+`.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`.
+
+Earlier tests in the same block register/activate the service worker, navigate
+the app, and exercise cache behavior before the hard gate runs. The hard gate
+therefore benefits from state that it did not establish itself. The fixed
+profile can also retain service-worker/cache state across local runs.
+
+The hard gate currently waits for an active service-worker registration before
+shutting down the server. An active registration is not equivalent to proving
+that the current page is controlled by that worker or that the shell needed for
+offline reload has definitely been precached.
+
+This is a test-isolation defect. There is currently no evidence that v0.9.0
+serves stale evidence as current or that production PWA semantics are wrong.
+
+## 2. Frozen maintenance invariant
+
+A test explicitly designated `HARD GATE`, `SECURITY GATE`, or
+`ACCEPTANCE GATE` must:
+
+- establish every prerequisite material to the claim it makes;
+- pass when selected independently in a fresh process/environment;
+- not require another test to run first;
+- not depend on a fixed browser profile or historical cache/filesystem state;
+- own and clean up disposable servers, evidence roots, browser profiles,
+  contexts, and similar mutable state where those resources are part of the
+  experiment.
+
+The PWA hard gate is the first explicit application of this invariant.
+
+## 3. Scope
+
+v0.9.1 owns:
+
+- isolation of the PWA hard-gate experiment;
+- removal of hidden dependency on the historical fixed Chromium profile for
+  that gate;
+- explicit service-worker control proof;
+- explicit app-shell cache prerequisite proof;
+- explicit `/api/` cache exclusion proof within the hard gate;
+- explicit server/network-unavailable proof before the offline reload;
+- explicit stale-evidence-absence proof after the offline reload;
+- deterministic cleanup;
+- a dedicated command/gate that runs the hard gate by itself;
+- complete browser/security regression after the correction;
+- documentation reconciliation and normal patch readiness if the user elects
+  to publish v0.9.1.
+
+## 4. Explicit exclusions
+
+The patch must not, merely to make the test pass:
+
+- change production service-worker caching policy;
+- add runtime caching for `/api/` or evidence/media;
+- weaken the stale-evidence hard gate;
+- change Viewer protocol or evidence schemas;
+- add a product feature or CLI command;
+- add v0.10 workflow behavior;
+- add arbitrary sleeps/retries as a substitute for state proof;
+- enforce test ordering;
+- retain a fixed persistent profile as an implicit fixture.
+
+If the corrected self-contained experiment fails after all prerequisites are
+proven, stop and classify a product defect before modifying production code.
+
+## 5. Target test architecture
+
+The hard gate becomes one complete experiment with this lifecycle:
+
+```text
+fresh temporary evidence root
+→ populate deterministic reference/annotation fixture
+→ fresh viewer server
+→ fresh temporary persistent Chromium profile
+→ fresh BrowserContext
+→ fresh page
+→ navigate while server is live
+→ wait for service-worker registration/activation
+→ prove current page is service-worker controlled
+→ prove required application shell is present in Cache Storage
+→ prove /api/ entries are absent from Cache Storage
+→ prove live evidence is visible
+→ close viewer server
+→ prove server/API network is unavailable
+→ reload
+→ prove shell still renders
+→ prove evidence surface reports unavailable
+→ prove previously visible evidence identity is absent
+→ close context
+→ close server if still open
+→ remove evidence root
+→ remove browser profile
+```
+
+No prior `it()` may be part of this lifecycle.
+
+## 6. Resource ownership
+
+### 6.1 Evidence root
+
+Create a test-owned root with `mkdtemp()` under the OS temporary directory.
+
+Populate it through the existing canonical deterministic fixture helpers used by
+the current PWA test. The hard gate should still include the real annotation
+needed for annotation/media route coverage when that remains relevant to the
+cache boundary.
+
+Remove the root in `finally`/test cleanup even after a failed assertion where
+practical.
+
+### 6.2 Viewer server
+
+Start a dedicated viewer server for the hard gate. Do not reuse a server from a
+describe-level `beforeAll`.
+
+The server may be closed deliberately in the middle of the experiment; cleanup
+must tolerate an already-closed server.
+
+### 6.3 Chromium profile/context
+
+Create a fresh temporary persistent profile, for example:
+
+```ts
+const profileRoot = await mkdtemp(
+  path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-'),
+);
+```
+
+Launch:
+
+```ts
+const context = await chromium.launchPersistentContext(profileRoot, {
+  headless: true,
+});
+```
+
+The hard gate must not use
+`.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`.
+
+Remove the temporary profile after closing the context.
+
+## 7. Service-worker readiness proof
+
+Before shutting down the server, prove two distinct conditions.
+
+First, the registration is ready and has an active worker:
+
+```ts
+const registrationState = await page.evaluate(async () => {
+  const registration = await navigator.serviceWorker.ready;
+  return {
+    active: registration.active !== null,
+    scope: registration.scope,
+  };
+});
+```
+
+Second, the current page is actually controlled:
+
+```ts
+await page.waitForFunction(
+  () => navigator.serviceWorker.controller !== null,
+  undefined,
+  { timeout: 10_000 },
+);
+```
+
+If the first navigation installs/activates the worker without immediately
+controlling the current page, perform a normal reload while the server is still
+available, then wait for `navigator.serviceWorker.controller !== null`.
+
+Do not replace these proofs with a fixed sleep.
+
+## 8. App-shell cache proof
+
+Before server shutdown, inspect Cache Storage from the page and prove that the
+Workbox/app-shell precache contains the resources necessary for the offline
+navigation shell.
+
+The assertion should use stable build-level expectations rather than hashed
+asset filenames where possible. It must prove that a cache exists and that a
+navigation/app-shell response is available; it must not simply infer cache
+readiness from `registration.active`.
+
+If the exact stable cache representation requires inspection during
+implementation, record that concrete representation in the implementation
+report and test the narrowest durable condition.
+
+## 9. API cache exclusion proof
+
+The hard gate itself must inspect Cache Storage and prove that cached requests
+do not contain paths beginning with:
+
+`/api/`.
+
+The separate focused `never caches /api/ responses` test may remain, but the
+hard gate cannot rely on that test having run first.
+
+No runtime caching rule for evidence/API may be added.
+
+## 10. Live evidence proof
+
+Before server shutdown:
+
+- wait for the first real evidence item;
+- prove it is visible;
+- capture/assert a deterministic evidence identity/text such as the fixture's
+  `many-regions-candidate` identity.
+
+That exact previously visible identity becomes the stale-data negative
+assertion after the offline reload.
+
+## 11. Server/network-down proof
+
+After `server.close()`, prove that the authoritative network endpoint is no
+longer available before evaluating offline behavior.
+
+Use a bounded direct request/fetch that must fail because the server is gone.
+Do not infer network unavailability solely from the fact that `close()`
+resolved.
+
+The cache/service-worker may still satisfy app-shell navigation; the proof of
+server unavailability must target server-backed evidence/API behavior.
+
+## 12. Offline reload proof
+
+Reload the controlled page after the server is proven unavailable.
+
+Require:
+
+- the precached viewer shell still renders;
+- the evidence-dependent UI reaches its explicit unavailable/error state;
+- body/UI text contains the existing unavailable message;
+- the previously visible evidence identity is absent.
+
+The safety invariant remains unchanged: a cached shell is permitted; stale
+authoritative evidence is not.
+
+## 13. Cleanup guarantees
+
+Cleanup must be deterministic and tolerant of the intentional mid-test server
+shutdown.
+
+At minimum:
+
+- close page/context;
+- close server if not already closed;
+- remove evidence root recursively;
+- remove temporary persistent profile recursively.
+
+Do not leave the hard gate's browser state under `.my-dev-kit-workflow`.
+
+If cleanup errors are currently swallowed too broadly, preserve enough
+diagnostic information that a leaked profile/server can be debugged without
+turning cleanup into a product semantic change.
+
+## 14. Other PWA tests
+
+The focused tests for:
+
+- service-worker registration;
+- manifest validity;
+- API cache exclusion;
+- install-control behavior;
+- standalone display-mode proof;
+
+remain valuable and should retain their narrow assertions.
+
+Where the first PWA describe still uses a shared persistent context for the
+non-hard-gate tests, replace any fixed historical profile with a fresh
+describe-owned temporary profile and remove it in cleanup. This prevents
+cross-run contamination even when those focused tests continue sharing state
+within their describe.
+
+The hard gate itself must not share that context/profile.
+
+## 15. Dedicated isolated command
+
+Add one repository-owned command so isolation remains a permanent gate.
+
+Preferred package script:
+
+```json
+"test:pwa-hard-gate": "vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t \"HARD GATE\""
+```
+
+Use repository naming conventions if a better exact script name already exists,
+but keep one explicit isolated command.
+
+This command must start from normal test setup and must not require another test
+to have run first.
+
+## 16. Security/readiness integration
+
+The isolated hard-gate command must be part of the applicable security or
+release-readiness validation path so future full-suite success cannot hide a
+regression in test independence.
+
+Do not remove the normal complete
+`tests/browser/pwaHardening.test.ts`/browser/security execution. The isolated
+proof is additive.
+
+If adding the dedicated command to `npm run test:security` would cause the
+same expensive test to run redundantly in a harmful way, keep the command
+separate and wire it into pre-release readiness explicitly. Choose the smallest
+repository-consistent integration, and document the decision.
+
+## 17. Implementation sequence
+
+### Batch 1 — Isolate and strengthen the hard-gate experiment
+
+Primary owner:
+
+`tests/browser/pwaHardening.test.ts`
+
+Expected work:
+
+- replace hard-gate shared state with test-owned fresh resources;
+- replace fixed persistent-profile dependence with temporary profile ownership;
+- add explicit active-registration and current-client-controller proof;
+- add explicit shell-cache and API-cache-exclusion proof;
+- add explicit server/API-down proof;
+- preserve the existing offline-shell/stale-evidence assertions;
+- make cleanup deterministic;
+- make the hard gate pass independently.
+
+Batch 1 acceptance:
+
+```text
+isolated HARD GATE PASS
+full pwaHardening.test.ts PASS
+no production file modified
+no fixed-profile dependence in the hard gate
+```
+
+If the isolated experiment still demonstrates stale evidence or cannot satisfy
+the existing product contract after all prerequisites are proven, STOP with a
+product-defect verdict before Batch 2.
+
+### Batch 2 — Freeze the isolation gate and run full regression
+
+Expected work:
+
+- add the dedicated package script;
+- add the isolation proof to the appropriate security/readiness path;
+- update development/CI/current-state documentation from planned to
+  implemented wording;
+- run complete unit/browser/security/build/docs/package validation;
+- perform patch release readiness if v0.9.1 publication is requested.
+
+Batch 2 acceptance:
+
+```text
+test:pwa-hard-gate PASS
+full browser suite PASS
+security suite PASS
+typecheck PASS
+lint PASS
+unit tests PASS
+build PASS
+docs check PASS
+pack dry run PASS
+no unintended production semantic change
+```
+
+## 18. Required implementation tests
+
+At minimum prove:
+
+1. hard gate passes alone from a clean temporary profile;
+2. hard gate passes when the whole PWA file runs;
+3. hard gate passes in the normal full browser suite;
+4. hard gate passes in the security validation path;
+5. repeated isolated executions do not depend on state from the prior run;
+6. no `/api/` request is present in Cache Storage at the shutdown boundary;
+7. the current client is controlled before shutdown;
+8. the shell cache prerequisite is explicitly established;
+9. the server/API is explicitly unavailable before offline reload;
+10. stale evidence identity is absent after reload;
+11. temporary profile/evidence state is cleaned up.
+
+## 19. Production-code escalation rule
+
+Expected initial classification:
+
+```text
+TEST_DEFECT
+PRODUCT_CHANGE_REQUIRED = false
+```
+
+If the corrected clean-state experiment fails because production behavior
+actually violates the stale-evidence safety contract:
+
+- do not loosen the test;
+- do not add retry/sleep until it happens to pass;
+- capture the exact runtime evidence;
+- stop the maintenance batch;
+- report a product defect;
+- revise this plan explicitly before changing production PWA/service-worker
+  code.
+
+## 20. Version/package expectations
+
+v0.9.1 is a maintenance patch. No canonical evidence schema version is expected
+to change.
+
+No new runtime dependency is expected.
+
+If implementation remains test/documentation-only, package runtime bytes may be
+unchanged apart from version/docs if the user elects to publish v0.9.1. The
+release decision must be made after implementation evidence rather than by
+inventing a product change solely to justify a package release.
+
+## 21. Documentation reconciliation after implementation
+
+When implementation passes:
+
+- `CURRENT_STATE.md` changes from planned to implemented status;
+- `ROADMAP.md` records v0.9.1 as implemented/released only when that state is
+  actually true;
+- `DEVELOPMENT.md` and `CI_CD.md` retain the durable gate-isolation rule;
+- `CHANGELOG.md` receives the actual implemented correction under
+  `[Unreleased]` or the final v0.9.1 section at release preparation;
+- historical v0.9.0 reports remain unchanged.
+
+## 22. Final implementation verdicts
+
+Use a precise result.
+
+Expected success before release:
+
+`PASS_V0_9_1_PWA_HARD_GATE_ISOLATION`
+
+Use a blocker such as:
+
+`BLOCKED_V0_9_1_PRODUCT_PWA_DEFECT_DISCOVERED`
+
+if the self-contained experiment reveals a real production failure.
+
+Do not claim v0.9.1 released until the normal release workflow actually
+completes.

package/docs/reports/v0.10-batch1-visual-change-workflow-foundation.md

@@ -0,0 +1,102 @@
+# v0.10 Batch 1 Visual-Change Workflow Foundation
+
+## 1. Verdict
+
+PASS after the validation recorded below.
+
+## 2. Repository and Git state
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `0ca6a686ee16447052845227a86f685b91aa54c1`
+- Branch: `feature/v0.10-full-visual-workflow`
+- Intended commit: `feat: add v0.10 visual change workflow foundation`
+
+## 3. Retrieval and index
+
+- Published my-dev-kit version: `1.12.3`
+- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.9.1-20260922T070928-v010-batch1`
+- Command: `my-dev-kit index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out <index> --call-graph --json`
+- Roots: `src`, `viewer/src`, `tests`, `scripts`
+- Summary: 162 files, 1,606 symbols, 3,471 edges, zero index-level warnings/errors.
+- Partial analyzers: data-model (758 warnings) and classification (1,568 warnings). Syntax, call graph, frontend semantic, and frontend reachability completed.
+
+Canonical precedents confirmed:
+
+- `src/domain/visualAnnotation.ts` and `visualAnnotationIdentity.ts`: closed validation, sorted-key canonical JSON, SHA-256 request identity, nonce-backed instance identity, producer/provenance, and forward supersession.
+- `src/domain/externalReference.ts`, `externalReferenceIdentity.ts`, and `frontendContractIdentity.ts`: exact request/instance and immutable supersession conventions.
+- `src/domain/externalReferenceRuntimeBinding.ts`: the exact reusable explicit binding declaration type and its identifier, bound, and duplicate semantics.
+- `src/artifacts/visualAnnotationArtifactWriter.ts` and reader: sibling temporary directory, overwrite refusal, cleanup, manifest/media digest validation, and atomic rename.
+- `src/projectWorkflow/projectPaths.ts`: the project evidence-root/path owner.
+- `src/viewerServer/evidence/classify.ts`, `index.ts`, `projection.ts`, `handles.ts`, and `annotationView.ts`: the existing support-state classifier, metadata-first index, safe handles, bounded exact identity lookup, and honest unavailable projection.
+- Existing `EvidenceReference` is structured evaluation provenance and explicitly is not a filesystem reference. Therefore a small workflow-owned project-relative artifact reference was required; no generalized cross-project framework was added.
+
+Full source/test file reads: none.
+
+## 4. Production implementation
+
+Created:
+
+- `src/domain/visualChangeWorkflow.ts`
+- `src/domain/visualChangeWorkflowIdentity.ts`
+- `src/artifacts/visualChangeWorkflowArtifactWriter.ts`
+- `src/artifacts/visualChangeWorkflowArtifactReader.ts`
+- `src/application/visualChangeWorkflowPersistenceService.ts`
+- `src/viewerServer/evidence/visualChangeWorkflowView.ts`
+
+Modified:
+
+- `src/projectWorkflow/projectPaths.ts`
+- `src/viewerServer/evidence/classify.ts`
+- `src/viewerServer/evidence/handles.ts`
+- `src/viewerServer/evidence/projection.ts`
+- `src/index.ts`
+- `docs/CONTRACTS.md`
+
+The artifact kind is exactly `my-frontend-observer/visual-change-workflow`; schema is exactly `1.0.0`; attempts are bounded at 20. The closed domain union contains the two frozen entry modes, exact evidence references, check snapshots, coordination metadata, review state, activation, and governance-result references.
+
+Request identity is deterministic over semantic evidence identities and binding content. Storage paths, timestamps, output roots, temp roots, Viewer handles/ports, and coordination filesystem details are excluded. Workflow instance IDs are fresh. Attempt IDs hash request ID plus candidate observation ID. Revisions use `supersedesVisualChangeWorkflowId`; parents are never rewritten.
+
+The writer validates, refuses existing final output, uses `.tmp-<workflowId>`, writes canonical bindings when required, verifies its digest, writes the manifest, and atomically renames. The reader checks kind/version/domain validity, exact `bindings.json` path, regular-file status, SHA-256, canonical bytes, declaration equality, and count. No referenced artifact or media is copied.
+
+Discovery classifies the new family through the existing support-state machinery. Metadata includes workflow/request identity, mode, baseline, annotation, selected reference, attempt count, latest check/review state, and supersession without embedding attempts. The read projection resolves exact identities using canonical classification and returns explicit unavailable state for missing or ambiguous links.
+
+## 5. Tests
+
+Created `tests/unit/visualChangeWorkflow.test.ts`. Its ten focused cases protect:
+
+1. minimal actual/reference validation, closed shapes, wrong kind, and unsupported schema;
+2. request identity determinism and semantic-scope changes, including operational path exclusion;
+3. fresh workflow identity and deterministic attempt identity invariants;
+4. attempt bounds, revision lineage, path safety, and review vocabulary;
+5. actual-mode round trip, absent bindings file, and overwrite refusal;
+6. deterministic bindings bytes, digest/count round trip, and tamper rejection;
+7. temporary-output cleanup on injected failure;
+8. same-request/different-instance persistence and byte-immutable parent revision;
+9. supported classification and bounded index metadata;
+10. exact linked-evidence resolution and honest missing evidence.
+
+Existing focused annotation, external-reference, contract, and discovery suites remained unchanged and passed.
+
+## 6. Validation
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS after removal of one unused import.
+- Focused five-file Vitest run: PASS, 51 tests.
+- `npm test`: PASS.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS.
+
+Existing constants remain observation `1.2.0`, comparison `1.0.0`, frontend contract `1.0.0`, evaluation `1.0.0`, bounded-agent-context `1.0.0`, external-reference `1.0.0`, visual annotation `1.0.0`, and Viewer protocol `1.3.0`.
+
+## 7. Exclusions and risk
+
+No project activation/restoration, live `checkProject` mapping, Viewer UI/POST routes, entry-mode UI, handoff, orchestrator execution, rerender/correction loop, acceptance action, governance operation, tutorial, version bump, or release work was implemented.
+
+Remaining risk is limited to later-batch composition: Batch 2 must map canonical `CheckWorkflowResult` into the frozen snapshot, activate/restore project acceptance explicitly, and record attempts without scope drift. Batch 1 deliberately does not enforce accepted-requires-PASS.
+
+## 8. Batch 2 handoff
+
+Start from this Batch 1 commit. Reuse `persistVisualChangeWorkflow`, `readVisualChangeWorkflowArtifact`, `buildVisualChangeAttemptIdentity`, `visualChangeOutputLocation`, and the existing `checkProject` owner. Implement only explicit acceptance activation/restore and canonical check-to-snapshot attempt recording, preserving all Batch 1 identities and schema `1.0.0`.
+
+Generated state is confined to `.my-dev-kit-workflow/` and `.my-dev-kit-context/`; neither path is staged.

package/docs/reports/v0.10-batch2-project-composition-check-recording.md

@@ -0,0 +1,103 @@
+# v0.10 Batch 2 Project Composition and Check Recording
+
+## 1. Verdict
+
+PASS. Batch 2 project composition, explicit activation and restoration, drift gates, canonical project-check reuse, and immutable attempt recording are implemented.
+
+## 2. Repository and Git state
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `62c4df47dd278c1fbd431824ca6e773366f1d1fb`
+- Branch: `feature/v0.10-full-visual-workflow`
+- Commit message: `feat: add v0.10 project visual change composition`
+
+The preflight worktree was clean. Local and remote shared branches both pointed to the authoritative Batch 1 commit.
+
+## 3. my-dev-kit retrieval
+
+- Resolved published version: `1.12.3`
+- Install: `.my-dev-kit-workflow/tools/v0.10-batch2/`
+- CLI version: `1.12.3`
+- Verified commands: `index`, `search`, `lookup`, `slice`, `source`, `graph-diff`, and `context`
+- Fresh index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch2-20260922`
+- Exact index command: `node .my-dev-kit-workflow/tools/v0.10-batch2/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch2-20260922 --call-graph --json`
+- Index summary: 168 files, 1,669 symbols, 3,581 edges, zero index-level warnings or errors.
+- Complete analyzers: syntax, call graph, frontend semantic, frontend reachability.
+- Partial analyzers: data model with 790 warnings; classification with 1,621 warnings.
+- Skipped/not-run analyzers were Android-specific and model-view lineage.
+
+Retrieval used search, lookup, slice, exact symbol source, local dependency expansion, bounded file ranges, and continuation markers. It verified `activateProjectChangeContract`, `FrontendObserverAcceptanceConfig`, `checkProject`, `CheckWorkflowResult`, the alias catalog, canonical observation/contract/reference readers, `persistVisualChangeWorkflow`, `readVisualChangeWorkflowArtifact`, and `buildVisualChangeAttemptIdentity`.
+
+## 4. Reused owners
+
+- `src/application/projectWorkflowService.ts`: existing atomic activation precedent; unchanged behavior.
+- `src/projectWorkflow/projectConfig.ts`: unchanged project schema and validation.
+- `src/projectWorkflow/aliasCatalog.ts`: exact baseline alias identity and location.
+- `src/application/projectCheckService.ts`: sole capture, comparison, contract, reference, blocker, and final-status owner.
+- `src/projectWorkflow/checkResult.ts`: canonical bounded result fields and truncation.
+- Canonical artifact readers for observations, annotations, baseline/change contracts, external references, and visual-change workflows.
+- `src/application/visualChangeWorkflowPersistenceService.ts`: all new immutable workflow revisions.
+- `src/domain/visualChangeWorkflowIdentity.ts`: existing attempt identity helper.
+
+## 5. Application service
+
+Created `src/application/visualChangeProjectWorkflowService.ts`. It exports project-aware create/freeze, activation, restoration, canonical check recording, and the pure snapshot mapper. `src/index.ts` exposes the application surface through the established public convention.
+
+Create/freeze validates the project configuration and every referenced project-contained artifact. It checks baseline observation ID, request ID, and path, annotation identity, optional baseline-contract identity, actual-mode change-contract identity/request identity, and reference identity/request identity. It persists through the Batch 1 owner without activation, attempts, or project-config mutation.
+
+## 6. Activation and rollback
+
+Actual activation requires an existing contract block, exact frozen baseline-contract path and identity, and exact change-contract evidence. It changes only `acceptance.contract.changeArtifact`.
+
+Reference activation requires an existing reference block, the exact frozen approved reference, reader-verified workflow bindings, and contract/baseline consistency. It changes only the approved reference artifact and the source workflow's project-relative `bindings.json`.
+
+Both modes snapshot all represented mutable acceptance selection fields. They atomically write a validated updated configuration and then persist a new workflow revision with the same request ID, unchanged attempts/governance data, activation before/after/activatedAt, and forward supersession. A persistence failure restores the exact original config bytes. A failed compensation returns distinct `partial-state-failure` language stating manual repair may be required.
+
+## 7. Restore
+
+Restore requires a live activation and exact equality with `activation.after`. Drift is non-mutating. Actual restore changes only the prior change-contract selection. Reference restore restores the prior reference and exact optional bindings presence/value. The successful immutable revision adds only `restoredAt` and forward supersession. Persistence failure compensates back to the exact activated configuration.
+
+## 8. Baseline and drift rules
+
+Baseline resolution first prefers `defaultBaseline` only when observation ID, request ID, and exact project-relative artifact location all match. Otherwise it chooses the lexicographically first exact matching alias. No exact alias returns `baseline-drift` before `checkProject`.
+
+The pre-check gate requires a valid active non-restored workflow, exact acceptance selection, exact baseline, exact baseline/change contract identities where active, exact approved reference identity, exact bindings selection, and reader-verified frozen bindings bytes. Represented changes return `acceptance-drift` or `baseline-drift` without evaluation.
+
+## 9. Canonical check and snapshot
+
+The service calls only `checkProject(projectRoot, resolvedAlias)`. The pure mapper directly projects status, baseline/candidate IDs, complete comparison/evaluation references, verified active contract IDs, canonical reference ID/fidelity state, ordered failed/unavailable clause and requirement IDs, bounded unexpected-change count, and blockers. Blockers are capped at 50. Snapshot truncation combines canonical overall, contract, reference, and blocker projection truncation.
+
+A result without both baseline and candidate is returned as `candidate-not-produced` and is not recorded. Post-check baseline or reference mismatch returns `check-scope-mismatch`.
+
+## 10. Attempt persistence
+
+Candidate identity/path comes only from the canonical result and is containment checked. Attempt identity uses `buildVisualChangeAttemptIdentity`. New attempts are pending, timestamped, and link to the immediately prior attempt. Duplicate IDs and a twenty-first attempt are rejected without truncation. Persistence produces a new revision with identical scope/request identity and immutable parent bytes. Persistence failure retains canonical check evidence and reports that history was not updated.
+
+## 11. Tests and validation
+
+Created `tests/unit/visualChangeProjectWorkflowService.test.ts`. It covers direct PASS/FAIL/BLOCKED/REVIEW_REQUIRED projection, comparison/evaluation references, clause and reference-requirement ordering, bounded unexpected changes, blocker bounds, canonical truncation, create-without-activation, immutable activation and restore revisions, rollback after persistence failure, and one-call canonical check recording of a pending candidate attempt. Real application tests use canonical artifact writers/readers.
+
+Focused validation: 3 files, 25 tests, PASS. This includes the new service, existing Batch 1 visual-change workflow, and existing project check tests.
+
+Full validation:
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS, 91 files and 1,477 tests.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS.
+
+Existing `activateProjectChangeContract`, `checkProject`, Batch 1 workflow behavior, schema constants, and Viewer protocol remain unchanged and pass the full suite.
+
+## 12. Full-file read accounting
+
+Full source/test file reads: none. my-dev-kit bounded retrieval supplied every required implementation shape. Its symbol index lacks reliable symbol end lines for some declarations, so continuation markers and bounded explicit file ranges were used instead of whole-file reads. Canonical documentation reads are excluded by task rule.
+
+## 13. Exclusions and handoff
+
+No Viewer workspace, POST route, annotation UI composition, coding-agent handoff, orchestrator integration, automatic retry, correction action, human acceptance, governance approval, version bump, release, tag, publication, or PR work was implemented.
+
+Batch 3 should start from this commit and add only the secure project-aware Viewer workspace/API specified by the frozen plan. It can call this application service without reconstructing activation, drift, check, snapshot, or attempt semantics.
+
+Generated state is confined to `.my-dev-kit-workflow/` and `.my-dev-kit-context/`. Neither path is staged.