@dailephd/my-frontend-observer 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -2,7 +2,15 @@
 
 ## [Unreleased]
 
-Future development.
+## 0.10.0 - 2026-09-23
+
+Shipped the full Visual Change workflow in the project-aware Viewer. People
+can start from an actual frontend or approved reference, confirm and explicitly
+activate scope, and prepare a bounded coding-agent handoff. Immutable check
+attempts support correction; human acceptance requires the latest canonical
+check to PASS, while governance remains separate. Installed-package and Viewer
+support are included. Security and PWA boundaries remain intact: Observer does
+not edit source or grant automatic approval.
 
 ## 0.9.1 - 2026-09-21
 

package/README.md

@@ -1,6 +1,6 @@
 # my-frontend-observer
 
-## Common project workflow (v0.9.1)
+## Common project workflow (v0.10.0)
 
 ```powershell
 my-frontend-observer init --url http://127.0.0.1:3000 --target app=#app
@@ -17,21 +17,29 @@ my-frontend-observer view
 `1`, `2`, or `3` for `PASS`, `FAIL`, `REVIEW_REQUIRED`, or `BLOCKED`.
 Canonical hashes remain available in viewer details and persisted provenance,
 but are not normal workflow command inputs. The existing low-level commands
-remain supported. v0.9.1 is the current published release.
+remain supported. v0.10.0 is the current release.
 
-v0.9.1 is a maintenance release that hardens independent PWA security-gate
-validation without changing production PWA behavior.
+v0.10.0 completes the Visual Change workflow described below.
 
 `my-frontend-observer` is the local-first rendered browser/runtime evidence
 producer in the my-dev-kit ecosystem. Its durable product purpose is defined
 in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md). Whole-ecosystem
 composition is documented in the [my-dev-kit ecosystem guide](https://github.com/dailephd/my-dev-kit/blob/main/docs/ECOSYSTEM_DEVELOPMENT_WORKFLOWS.md), including the [command-surface compatibility map](https://github.com/dailephd/my-dev-kit/blob/main/docs/ECOSYSTEM_DEVELOPMENT_WORKFLOWS.md#915-command-surface-compatibility-map).
 
+From a project-aware `view` session, a human can begin from an actual runtime
+capture
+or an approved reference, explicitly confirm structured visual intent, create
+and activate a frozen workflow, prepare a bounded handoff, let an external
+actor edit source, run the canonical `check <baseline> --json`, request another
+correction or accept the latest PASS, and optionally record separately created
+governance results. Observer never edits source, and acceptance never silently
+approves a baseline or reference.
+
 ## Current status
 
-`v0.9.1`, PWA Hard-Gate Isolation and Reproducible Security Acceptance, is the
-current published release. It preserves the `v0.9.0` Human Visual Annotation
-and Design-Intent Capture release and builds on `v0.8.1`, Project Workflow CLI and
+`v0.10.0`, Full Visual Human–LLM Frontend Change Workflow, is the current
+release. It preserves the `v0.9.1` PWA hard-gate isolation and the `v0.9.0`
+Human Visual Annotation and Design-Intent Capture releases and builds on `v0.8.1`, Project Workflow CLI and
 Human-Readable Evidence Aliases, `v0.8.0`, Interactive Local Observation
 Viewer, and `v0.7.0`, End-to-End Coding-Agent Frontend Change
 Review, `v0.6.0`, Bounded Agent Context and Native my-dev-kit Ecosystem
@@ -349,8 +357,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.9.1 are
-  released; v0.10 remains future.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.10 are
+  released.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/application/visualChangeAgentHandoffService.d.ts

@@ -0,0 +1,28 @@
+import type { BoundedAgentContextArtifact } from '../domain/boundedAgentContext.js';
+import type { VisualChangeAgentHandoff, VisualChangeExternalCoordination } from '../domain/visualChangeAgentHandoff.js';
+export type PrepareVisualChangeAgentHandoffFailureCode = 'workflow-invalid' | 'workflow-inactive' | 'workflow-restored' | 'acceptance-drift' | 'baseline-drift' | 'evidence-unavailable' | 'reference-not-evaluable' | 'unsupported-context' | 'context-mismatch' | 'bounded-context-failed' | 'invalid-handoff' | 'review-required' | 'workflow-accepted' | 'workflow-abandoned';
+export type PrepareVisualChangeAgentHandoffResult = {
+    ok: true;
+    handoff: VisualChangeAgentHandoff;
+} | {
+    ok: false;
+    code: PrepareVisualChangeAgentHandoffFailureCode;
+    reason: string;
+};
+export interface PrepareVisualChangeAgentHandoffInput {
+    projectRoot: string;
+    workflowManifestPath: string;
+    context: {
+        status: 'none';
+    } | {
+        status: 'unsupported-version';
+        foundSchemaVersion: string;
+    } | {
+        status: 'valid';
+        artifact: BoundedAgentContextArtifact;
+    };
+    generatedAt: string;
+    producerVersion: string;
+    coordination?: VisualChangeExternalCoordination;
+}
+export declare function prepareVisualChangeAgentHandoff(input: PrepareVisualChangeAgentHandoffInput): Promise<PrepareVisualChangeAgentHandoffResult>;

package/dist/application/visualChangeAgentHandoffService.js

@@ -0,0 +1,111 @@
+import path from 'node:path';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { readExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactReader.js';
+import { readPerChangeContract, readPersistentBaselineContract } from '../artifacts/frontendContractArtifactReader.js';
+import { projectBoundedAgentContext } from '../domain/boundedAgentContextProjection.js';
+import { evaluateReferenceCandidateFidelity } from '../domain/externalReferenceFidelity.js';
+import { prepareReferenceCorrection } from '../domain/referenceCorrectionWorkflow.js';
+import { VISUAL_CHANGE_AGENT_HANDOFF_KIND, VISUAL_CHANGE_AGENT_HANDOFF_VERSION, isValidVisualChangeAgentHandoff } from '../domain/visualChangeAgentHandoff.js';
+import { resolveContainedAcceptancePath } from '../projectWorkflow/checkAcceptance.js';
+import { prepareActiveVisualChangeWorkflow, readProjectVisualChangeCycle } from './visualChangeProjectWorkflowService.js';
+const fail = (code, reason) => ({ ok: false, code, reason });
+function manifest(projectRoot, portable) { const resolved = resolveContainedAcceptancePath(projectRoot, portable); return resolved.ok ? path.join(resolved.path, 'manifest.json') : undefined; }
+function contextCoherent(context, scope) {
+    if (!context.sources.observationIds.includes(scope.baselineObservation.observationId))
+        return false;
+    if (scope.entryMode === 'actual-frontend')
+        return (context.sources.baselineContractId === undefined || context.sources.baselineContractId === scope.baselineContract.baselineId) && (context.sources.changeContractId === undefined || context.sources.changeContractId === scope.changeContract.contractId);
+    return (context.sources.baselineContractId === undefined || context.sources.baselineContractId === scope.baselineContract?.baselineId) && (context.sources.referenceId === undefined || context.sources.referenceId === scope.approvedReference.referenceId) && (context.sources.referenceRequestId === undefined || context.sources.referenceRequestId === scope.approvedReference.referenceRequestId);
+}
+export async function prepareVisualChangeAgentHandoff(input) {
+    const preflight = await readProjectVisualChangeCycle(input.projectRoot, input.workflowManifestPath);
+    if (!preflight.ok)
+        return fail('workflow-invalid', preflight.reason);
+    if (preflight.cycle === 'review-required')
+        return fail('review-required', 'the latest attempt requires explicit human review before another handoff');
+    if (preflight.cycle === 'accepted')
+        return fail('workflow-accepted', 'accepted workflow is terminal');
+    if (preflight.cycle === 'abandoned')
+        return fail('workflow-abandoned', 'abandoned workflow is terminal');
+    const ready = await prepareActiveVisualChangeWorkflow(input.projectRoot, input.workflowManifestPath);
+    if (!ready.ok) {
+        const mapping = { 'activation-not-configured': 'workflow-inactive', 'activation-already-restored': 'workflow-restored', 'acceptance-drift': 'acceptance-drift', 'baseline-drift': 'baseline-drift', 'workflow-invalid': 'workflow-invalid', 'workflow-reference-invalid': 'evidence-unavailable' };
+        return fail(mapping[ready.code] ?? 'evidence-unavailable', ready.reason);
+    }
+    if (input.context.status === 'unsupported-version')
+        return fail('unsupported-context', `supplemental context schema ${input.context.foundSchemaVersion} is unsupported`);
+    const { projectRoot, workflow, config, baselineAlias } = ready.context;
+    const scope = workflow.scope;
+    const baselinePath = manifest(projectRoot, scope.baselineObservation.artifactPath);
+    const baselineRead = baselinePath === undefined ? undefined : await readObservationArtifact(baselinePath);
+    if (baselineRead === undefined || !baselineRead.ok)
+        return fail('evidence-unavailable', 'frozen baseline observation is unavailable');
+    const observation = baselineRead.artifact;
+    let baselineContract;
+    if (scope.baselineContract !== undefined) {
+        const file = manifest(projectRoot, scope.baselineContract.artifactPath);
+        const read = file === undefined ? undefined : await readPersistentBaselineContract(file);
+        if (read === undefined || !read.ok)
+            return fail('evidence-unavailable', 'frozen baseline contract is unavailable');
+        baselineContract = read.contract;
+    }
+    let activeChangeContract;
+    if (config.acceptance?.contract !== undefined) {
+        const file = manifest(projectRoot, config.acceptance.contract.changeArtifact);
+        const read = file === undefined ? undefined : await readPerChangeContract(file);
+        if (read === undefined || !read.ok)
+            return fail('evidence-unavailable', 'active change contract is unavailable');
+        activeChangeContract = read.contract;
+    }
+    let confirmedScope;
+    let primary;
+    let trace;
+    if (scope.entryMode === 'actual-frontend') {
+        if (baselineContract === undefined)
+            return fail('evidence-unavailable', 'actual workflow baseline contract is unavailable');
+        const changeFile = manifest(projectRoot, scope.changeContract.artifactPath);
+        const changeRead = changeFile === undefined ? undefined : await readPerChangeContract(changeFile);
+        if (changeRead === undefined || !changeRead.ok)
+            return fail('evidence-unavailable', 'frozen change contract is unavailable');
+        confirmedScope = { entryMode: 'actual-frontend', annotationId: scope.annotationId, baselineObservation: { observationId: observation.observationId, requestId: observation.requestId }, baselineContract: { baselineId: baselineContract.baselineId, clauses: baselineContract.clauses }, changeContract: { contractId: changeRead.contract.contractId, contractRequestId: changeRead.contract.contractRequestId, clauses: changeRead.contract.clauses } };
+        const projected = projectBoundedAgentContext({ generatedAt: input.generatedAt, producerVersion: input.producerVersion, projectionProfile: 'frontend-change-review', observation, baseline: baselineContract, change: changeRead.contract, focusTargetIds: [] });
+        if (!projected.ok)
+            return fail('bounded-context-failed', projected.reason);
+        primary = projected.artifact;
+    }
+    else {
+        const referenceFile = manifest(projectRoot, scope.approvedReference.artifactPath);
+        const referenceRead = referenceFile === undefined ? undefined : await readExternalReferenceArtifact(referenceFile);
+        if (referenceRead === undefined || !referenceRead.ok)
+            return fail('evidence-unavailable', 'approved reference is unavailable');
+        const reference = referenceRead.artifact;
+        const fidelityResult = evaluateReferenceCandidateFidelity(reference, observation, scope.bindings);
+        if (!fidelityResult.ok || fidelityResult.evaluation.state === 'not-evaluated')
+            return fail('reference-not-evaluable', fidelityResult.ok ? 'canonical reference fidelity is not evaluated' : fidelityResult.reason);
+        const coherentBaseline = baselineContract !== undefined && baselineContract.sourceObservation.observationId === observation.observationId ? baselineContract : undefined;
+        if (baselineContract !== undefined && coherentBaseline === undefined)
+            trace = { status: 'not-applicable', reason: 'baseline-contract-source-mismatch' };
+        else if (coherentBaseline !== undefined && activeChangeContract !== undefined) {
+            const correction = prepareReferenceCorrection({ reference, baselineObservation: observation, currentObservation: observation, baselineContract: coherentBaseline, changeContract: activeChangeContract, bindingDeclarations: scope.bindings, generatedAt: input.generatedAt, producerVersion: input.producerVersion, projectionProfile: 'frontend-change-review' });
+            if (!correction.ok)
+                return fail('reference-not-evaluable', correction.reason);
+            if (correction.status !== 'handoff-ready')
+                return fail('reference-not-evaluable', 'canonical reference correction is blocked');
+            trace = { status: 'available', reviewRequestId: correction.reviewRequestId };
+        }
+        else
+            trace = { status: 'not-applicable', reason: 'project-contract-context-not-configured' };
+        const projected = projectBoundedAgentContext({ generatedAt: input.generatedAt, producerVersion: input.producerVersion, projectionProfile: 'frontend-change-review', observation, fidelity: fidelityResult.evaluation, focusTargetIds: [...new Set(scope.bindings.map((binding) => binding.runtimeTarget))], ...(coherentBaseline === undefined ? {} : { baseline: coherentBaseline }), ...(activeChangeContract === undefined ? {} : { change: activeChangeContract }) });
+        if (!projected.ok)
+            return fail('bounded-context-failed', projected.reason);
+        primary = projected.artifact;
+        confirmedScope = { entryMode: 'reference', annotationId: scope.annotationId, baselineObservation: { observationId: observation.observationId, requestId: observation.requestId }, approvedReference: { referenceId: reference.referenceId, referenceRequestId: reference.referenceRequestId, requirements: reference.requirements ?? [] }, bindings: scope.bindings, ...(coherentBaseline === undefined ? {} : { baselineContract: { baselineId: coherentBaseline.baselineId, clauses: coherentBaseline.clauses } }), ...(activeChangeContract === undefined ? {} : { activeChangeContract: { contractId: activeChangeContract.contractId, contractRequestId: activeChangeContract.contractRequestId, clauses: activeChangeContract.clauses } }) };
+    }
+    const supplemental = input.context.status === 'valid' ? input.context.artifact : undefined;
+    if (supplemental !== undefined && !contextCoherent(supplemental, confirmedScope))
+        return fail('context-mismatch', 'supplemental context does not match the frozen workflow evidence');
+    const verificationPlan = ['Edit target source outside Observer.', `Run my-frontend-observer check ${baselineAlias} --json.`, 'The check captures a fresh current observation and evaluates active contracts.', 'A machine PASS still requires later explicit human review/acceptance.', ...(scope.entryMode === 'reference' ? ['The same approved reference and explicit bindings are re-evaluated.', 'Reference fidelity does not override active frontend-contract failures.'] : [])];
+    const handoff = { handoffKind: VISUAL_CHANGE_AGENT_HANDOFF_KIND, handoffVersion: VISUAL_CHANGE_AGENT_HANDOFF_VERSION, visualChangeRequestId: workflow.visualChangeRequestId, visualChangeWorkflowId: workflow.visualChangeWorkflowId, entryMode: scope.entryMode, confirmedScope, boundedAgentContext: primary, ...(supplemental === undefined ? {} : { supplementalContext: supplemental }), ...(trace === undefined ? {} : { referenceCorrection: trace }), verificationPlan, expectedPostEditCheck: { command: 'check', baselineAlias, json: true }, ...(input.coordination === undefined ? {} : { externalCoordination: input.coordination }) };
+    return isValidVisualChangeAgentHandoff(handoff) ? { ok: true, handoff } : fail('invalid-handoff', 'constructed handoff failed canonical validation');
+}
+//# sourceMappingURL=visualChangeAgentHandoffService.js.map

package/dist/application/visualChangeAgentHandoffService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualChangeAgentHandoffService.js","sourceRoot":"","sources":["../../src/application/visualChangeAgentHandoffService.ts"],"names":[],"mappings":"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"}

package/dist/application/visualChangeProjectWorkflowService.d.ts

@@ -0,0 +1,95 @@
+import type { VisualChangeActivationRecord, VisualChangeAttemptRecord, VisualChangeCheckSnapshot, VisualChangeScope, VisualChangeWorkflowArtifact } from '../domain/visualChangeWorkflow.js';
+import type { CheckWorkflowResult } from '../projectWorkflow/checkResult.js';
+import type { FrontendObserverProjectConfig } from '../projectWorkflow/projectConfig.js';
+import { checkProject } from './projectCheckService.js';
+import { persistVisualChangeWorkflow, type PersistVisualChangeWorkflowOptions } from './visualChangeWorkflowPersistenceService.js';
+export type VisualChangeProjectWorkflowFailureCode = 'project-config-invalid' | 'workflow-invalid' | 'workflow-reference-invalid' | 'activation-not-configured' | 'activation-already-restored' | 'baseline-drift' | 'acceptance-drift' | 'check-scope-mismatch' | 'candidate-not-produced' | 'duplicate-attempt' | 'attempt-limit-reached' | 'project-config-write-failure' | 'workflow-persistence-failure' | 'partial-state-failure' | 'review-required' | 'workflow-accepted' | 'workflow-abandoned';
+export interface VisualChangeProjectWorkflowFailure {
+    ok: false;
+    code: VisualChangeProjectWorkflowFailureCode;
+    reason: string;
+    check?: CheckWorkflowResult;
+}
+type Persist = typeof persistVisualChangeWorkflow;
+type Check = typeof checkProject;
+export interface VisualChangeProjectWorkflowDependencies {
+    persist: Persist;
+    check: Check;
+    atomicWrite(file: string, text: string): Promise<void>;
+    now(): string;
+}
+export interface CreateProjectVisualChangeWorkflowInput {
+    projectRoot: string;
+    scope: VisualChangeScope;
+    createdAt?: string;
+    dependencies?: Partial<VisualChangeProjectWorkflowDependencies>;
+}
+export type CreateProjectVisualChangeWorkflowResult = Awaited<ReturnType<Persist>> | VisualChangeProjectWorkflowFailure;
+export declare function createProjectVisualChangeWorkflow(input: CreateProjectVisualChangeWorkflowInput): Promise<CreateProjectVisualChangeWorkflowResult>;
+export declare function persistProjectVisualChangeWorkflowRevision(projectRoot: string, source: VisualChangeWorkflowArtifact, options: Omit<PersistVisualChangeWorkflowOptions, 'scope' | 'outputLocation' | 'cwd' | 'supersedesVisualChangeWorkflowId'>): Promise<import("./visualChangeWorkflowPersistenceService.js").ApplicationPersistVisualChangeWorkflowResult>;
+export interface ProjectVisualChangeMutationInput {
+    projectRoot: string;
+    workflowManifestPath: string;
+    dependencies?: Partial<VisualChangeProjectWorkflowDependencies>;
+}
+export declare function activateProjectVisualChangeWorkflow(input: ProjectVisualChangeMutationInput): Promise<{
+    ok: true;
+    visualChangeRequestId: string;
+    visualChangeWorkflowId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    bindingsPath?: string;
+} | VisualChangeProjectWorkflowFailure>;
+export declare function restoreProjectVisualChangeWorkflowAcceptance(input: ProjectVisualChangeMutationInput): Promise<{
+    ok: true;
+    visualChangeRequestId: string;
+    visualChangeWorkflowId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    bindingsPath?: string;
+} | VisualChangeProjectWorkflowFailure>;
+export interface VerifiedVisualChangeAcceptance {
+    activeBaselineContractId?: string;
+    activeChangeContractId?: string;
+}
+export declare function projectVisualChangeCheckSnapshot(result: CheckWorkflowResult & {
+    baseline: NonNullable<CheckWorkflowResult['baseline']>;
+    candidate: NonNullable<CheckWorkflowResult['candidate']>;
+}, verified: VerifiedVisualChangeAcceptance): VisualChangeCheckSnapshot;
+export interface RunProjectVisualChangeCheckInput extends ProjectVisualChangeMutationInput {
+    coordination?: VisualChangeAttemptRecord['coordination'];
+}
+export interface ActiveVisualChangeWorkflowContext {
+    projectRoot: string;
+    workflow: VisualChangeWorkflowArtifact & {
+        activation: VisualChangeActivationRecord;
+    };
+    workflowManifestPath: string;
+    config: FrontendObserverProjectConfig;
+    baselineAlias: string;
+    verifiedContractIds: {
+        baselineId?: string;
+        changeId?: string;
+    };
+}
+export declare function readProjectVisualChangeCycle(projectRootInput: string, workflowManifestPath: string): Promise<VisualChangeProjectWorkflowFailure | {
+    ok: true;
+    workflow: VisualChangeWorkflowArtifact;
+    cycle: import("../domain/visualChangeCycle.js").VisualChangeCycleState;
+}>;
+/** One readiness owner for canonical check recording and on-demand handoff preparation. */
+export declare function prepareActiveVisualChangeWorkflow(projectRootInput: string, workflowManifestPath: string): Promise<{
+    ok: true;
+    context: ActiveVisualChangeWorkflowContext;
+} | VisualChangeProjectWorkflowFailure>;
+export declare function runProjectVisualChangeCheck(input: RunProjectVisualChangeCheckInput): Promise<VisualChangeProjectWorkflowFailure | {
+    check: CheckWorkflowResult;
+    attempt: VisualChangeAttemptRecord;
+    ok: true;
+    visualChangeRequestId: string;
+    visualChangeWorkflowId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    bindingsPath?: string;
+}>;
+export {};