@dailephd/my-frontend-observer 0.8.1

package/docs/plans/v0.8.1-cli-usability-patch-plan.md

@@ -0,0 +1,505 @@
+# v0.8.1 CLI Usability Patch Plan
+
+Status: frozen implementation plan for the planned v0.8.1 usability patch.
+
+This file is a planning authority only. It does not claim that the commands or
+workflow described below are implemented until repository evidence proves they
+exist and the post-implementation documentation reconciliation records that
+state.
+
+## 1. Goal
+
+Add a small human-facing project workflow above the existing canonical
+observation, comparison, contract, reference, fidelity, and viewer engines.
+
+The patch solves a concrete usability problem exposed by manual first use of
+v0.8.0: ordinary users currently have to repeat URL/viewport/target/output
+arguments, manage evidence-root paths, resolve exact artifact roots, and may
+encounter long immutable artifact identifiers as if those identifiers were the
+normal user interface.
+
+The canonical artifact identities and existing low-level commands remain valid
+and supported. v0.8.1 adds project configuration, human-readable aliases, and a
+small high-level command surface so routine human and coding-agent workflows do
+not have to operate artifact plumbing directly.
+
+## 2. Public command model
+
+The normal project workflow becomes:
+
+```text
+my-frontend-observer init
+my-frontend-observer capture <name>
+my-frontend-observer check [<baseline>]
+my-frontend-observer view
+```
+
+The existing low-level commands remain supported for automation, compatibility,
+debugging, and advanced workflows:
+
+```text
+observe
+compare
+approve-baseline
+save-change-contract
+evaluate-contract
+import-reference
+approve-reference
+evaluate-reference-fidelity
+```
+
+No existing low-level command is removed or semantically redefined by this
+patch.
+
+## 3. Project discovery
+
+Project-aware commands discover configuration by walking upward from the current
+working directory until they find:
+
+```text
+frontend-observer.json
+```
+
+Discovery stops at the filesystem root.
+
+If a project-aware command cannot find configuration, fail with an actionable
+project-not-initialized diagnostic. Do not guess a repository root, evidence
+root, URL, viewport, or target configuration.
+
+`init` creates configuration in the directory where the user explicitly runs
+it. It never walks upward and silently overwrites another project.
+
+## 4. Project configuration
+
+The first project-configuration schema is versioned independently from product
+artifacts:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "url": "http://127.0.0.1:3000",
+  "viewport": {
+    "width": 1280,
+    "height": 720
+  },
+  "targets": [
+    {
+      "name": "header",
+      "locators": [
+        {
+          "kind": "css",
+          "selector": "#header"
+        }
+      ]
+    }
+  ],
+  "defaultBaseline": "baseline"
+}
+```
+
+The implementation may support a project-relative structured targets file as an
+alternative to inline targets when that reuses the existing target-file
+contract cleanly.
+
+Project-relative file references must use portable paths. Do not persist
+machine-specific absolute paths into project configuration.
+
+Configuration supplies workflow defaults only. It does not replace canonical
+request validation or artifact identity.
+
+## 5. Managed project state
+
+Project-managed Observer state lives under:
+
+```text
+.frontend-observer/
+```
+
+The first managed layout is:
+
+```text
+.frontend-observer/
+  catalog.json
+  evidence/
+```
+
+`init` may add `.frontend-observer/` to `.gitignore` when needed. It must not
+modify application source or unrelated ignore rules.
+
+Canonical artifacts remain immutable evidence underneath the managed evidence
+root. The managed project layer must not rewrite their identities or schemas.
+
+## 6. Human-readable aliases
+
+Add a versioned alias catalog that maps human-readable workflow names to
+canonical artifacts.
+
+Conceptually:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "observations": {
+    "baseline": {
+      "observationId": "<canonical-id>",
+      "requestId": "<canonical-id>",
+      "artifactPath": "evidence/observations/<canonical-path>"
+    }
+  }
+}
+```
+
+Rules:
+
+- the catalog is workflow metadata, not a replacement evidence schema;
+- canonical artifact identity remains authoritative;
+- aliases use a bounded portable grammar and cannot contain path traversal;
+- catalog paths are project-relative and portable;
+- catalog writes are atomic;
+- malformed or unsupported catalog versions fail closed;
+- replacing an alias never deletes its previous canonical artifact;
+- alias replacement never approves, supersedes, or mutates a baseline
+  contract, reference, or other governance state.
+
+Normal CLI and viewer presentation uses aliases first. Canonical IDs remain
+available as provenance/details.
+
+## 7. `init`
+
+`init` configures one frontend project.
+
+Required initial inputs must be sufficient to create a valid observation using
+the existing canonical observation request model. At minimum this means URL,
+viewport, and target configuration according to the selected input form.
+
+Example:
+
+```text
+my-frontend-observer init \
+  --url http://127.0.0.1:3000 \
+  --viewport 1280x720 \
+  --target "header=#header" \
+  --target "workspace=#workspace"
+```
+
+Responsibilities:
+
+1. validate configuration through existing request contracts where applicable;
+2. write `frontend-observer.json` atomically;
+3. create `.frontend-observer/` managed state;
+4. create an empty versioned catalog;
+5. add `.frontend-observer/` to `.gitignore` only when needed and only through
+   this explicit initialization action.
+
+If configuration already exists, fail unless an explicit replacement option is
+provided. Replacement must not delete existing canonical evidence.
+
+## 8. `capture <name>`
+
+`capture <name>` creates one canonical observation using project defaults.
+
+Example:
+
+```text
+my-frontend-observer capture baseline
+```
+
+Behavior:
+
+1. discover the project;
+2. read and validate project configuration;
+3. construct the existing canonical observation request;
+4. call the existing observation application service exactly once;
+5. persist the canonical artifact below the managed evidence root;
+6. atomically update the alias catalog only after observation persistence
+   succeeds.
+
+Do not create a second browser-observation implementation.
+
+The user does not provide an output path for normal capture.
+
+If the alias already exists, fail unless the user explicitly requests alias
+replacement. Replacement changes only the alias mapping. It does not delete old
+evidence and does not supersede approved governance state.
+
+## 9. Project-aware `view`
+
+Preserve the current advanced form:
+
+```text
+my-frontend-observer view --root <evidence-root> ...
+```
+
+Add the normal project form:
+
+```text
+my-frontend-observer view
+```
+
+Inside an initialized project, `view` without `--root` resolves the managed
+`.frontend-observer/evidence` root automatically.
+
+Existing options such as explicit bindings, bounded context, alternate port, and
+no-open behavior remain supported.
+
+The viewer receives alias metadata as presentation metadata. Its primary lists
+show names such as `baseline`, `current`, or another user-supplied alias.
+Canonical observation/request/artifact IDs remain available in provenance and
+raw-evidence details.
+
+Viewer alias presentation must not create a new evidence engine or persist a
+viewer-only artifact family.
+
+## 10. `check [baseline]`
+
+Prompt 2 adds the high-level acceptance command after the project/alias
+foundation is proven.
+
+Examples:
+
+```text
+my-frontend-observer check baseline
+my-frontend-observer check
+my-frontend-observer check baseline --json
+```
+
+When the baseline argument is omitted, use `defaultBaseline` only when it is
+configured and resolves unambiguously.
+
+Behavior:
+
+1. resolve the baseline alias;
+2. capture the current frontend with project configuration;
+3. persist that candidate canonically;
+4. create or replace the reserved human-facing `current` alias without deleting
+   earlier candidate evidence;
+5. call the existing canonical comparison engine;
+6. evaluate configured active frontend contracts where required inputs exist;
+7. evaluate configured approved reference/fidelity evidence where required
+   inputs exist;
+8. produce one bounded workflow summary.
+
+Do not create a second comparison, contract, reference, binding,
+compatibility, or fidelity engine.
+
+## 11. `check` status contract
+
+The high-level workflow status is:
+
+```text
+PASS
+FAIL
+REVIEW_REQUIRED
+BLOCKED
+```
+
+`PASS` means every configured executable acceptance dimension required by the
+project passed.
+
+`FAIL` means at least one configured executable acceptance dimension failed.
+
+`REVIEW_REQUIRED` means useful comparison evidence exists but configured
+executable criteria are insufficient to declare success or failure. A raw
+comparison or apparent lack of differences must never be promoted to PASS by
+itself.
+
+`BLOCKED` means required evidence could not be captured, resolved, compared, or
+evaluated reliably.
+
+Required `unavailable`, `ambiguous`, `incompatible`, `incomparable`, or
+`not-evaluated` evidence must not be silently converted to PASS.
+
+Reference-fidelity PASS must never override an active frontend-contract FAIL.
+
+## 12. Human and coding-agent output
+
+Human output must be concise and actionable, emphasizing aliases and failed
+conditions rather than filesystem paths or hashes.
+
+`check --json` provides a bounded machine-readable result for coding agents. It
+must contain the workflow status, aliases, relevant canonical artifact
+references, failed contract/reference evidence, unexpected changes, and blockers
+needed for correction. It must not embed complete raw artifacts or heavy image
+bytes.
+
+The JSON workflow result is a presentation/orchestration projection over
+canonical evidence. It is not a new canonical evaluation engine.
+
+## 13. Top-level help
+
+Reorganize top-level help into two groups.
+
+Normal workflow:
+
+```text
+init
+capture
+check
+view
+```
+
+Advanced/compatibility:
+
+```text
+observe
+compare
+approve-baseline
+save-change-contract
+evaluate-contract
+import-reference
+approve-reference
+evaluate-reference-fidelity
+```
+
+Existing command-specific help and behavior stay backward compatible.
+
+## 14. Future-version compatibility
+
+### v0.9
+
+Visual annotation remains a viewer capability. v0.9 should extend `view` rather
+than create another top-level workflow architecture.
+
+Annotations may refer to human aliases for convenience, but persisted annotation
+identity must remain tied to canonical observation/reference identities.
+
+### v0.10
+
+The coding-agent correction workflow should use:
+
+```text
+my-frontend-observer check <baseline> --json
+```
+
+after implementation attempts. The external coding agent or orchestrator edits
+source; Observer captures and evaluates runtime evidence.
+
+Do not add Observer commands such as `fix`, `repair`, or `generate-code` that
+would make Observer a source-editing system.
+
+## 15. Compatibility and schema constraints
+
+This patch must not change the semantics or schema versions of:
+
+- ObservationArtifact;
+- ComparisonArtifact;
+- frontend baseline/per-change contracts;
+- frontend contract evaluation artifacts;
+- external-reference artifacts;
+- reference/runtime binding;
+- reference/candidate compatibility;
+- reference fidelity;
+- bounded-agent-context;
+- runtime/static correlation.
+
+Existing public CLI and programmatic APIs remain first-class and continue to
+work without project initialization.
+
+## 16. Implementation sequence
+
+Implement in two prompts.
+
+### Prompt 1 — Project workflow foundation and aliases
+
+Implement:
+
+- project configuration contract and validation;
+- upward project discovery;
+- managed `.frontend-observer/` state paths;
+- alias validation and versioned catalog;
+- atomic catalog persistence;
+- `init`;
+- `capture <name>`;
+- alias replacement rules;
+- project-aware `view` without `--root`;
+- alias metadata projection into the viewer;
+- alias-first viewer labels;
+- common-versus-advanced top-level help;
+- backward compatibility and focused unit/browser/packed-package proof.
+
+Prompt 1 must not implement `check` acceptance orchestration.
+
+Prompt 1 gate: from an initialized project a user can run `capture baseline`
+and `view` without supplying an output path, evidence root, or canonical
+artifact hash, while all existing low-level commands still pass regression
+coverage.
+
+### Prompt 2 — `check` orchestration and coding-agent interface
+
+Starting only after Prompt 1 passes, implement:
+
+- baseline alias resolution;
+- current candidate capture and reserved `current` alias;
+- canonical comparison composition;
+- configured contract evaluation;
+- configured approved-reference/fidelity evaluation;
+- `PASS | FAIL | REVIEW_REQUIRED | BLOCKED` workflow status;
+- concise human output;
+- bounded `--json` output;
+- real-browser PASS/FAIL/REVIEW_REQUIRED/BLOCKED acceptance fixtures;
+- coding-agent correction proof using FAIL then PASS;
+- clean packed-consumer proof;
+- post-implementation documentation reconciliation.
+
+Prompt 2 gate: a normal user can `capture baseline`, modify the frontend, and
+run `check baseline` without artifact paths/hashes; a coding agent can consume
+`check baseline --json` and receive bounded actionable runtime failure evidence.
+
+## 17. Post-implementation documentation
+
+Only after the commands actually exist, reconcile current implementation docs,
+including as applicable:
+
+- README.md;
+- docs/COMMANDS.md;
+- docs/WORKFLOWS.md;
+- docs/ARCHITECTURE.md;
+- docs/CURRENT_STATE.md;
+- docs/PROJECT_OVERVIEW.md;
+- docs/SECURITY.md;
+- docs/DEVELOPMENT.md;
+- docs/CI_CD.md.
+
+Do not document `init`, `capture`, `check`, alias-aware `view`, or the new
+workflow as implemented before repository evidence proves they exist.
+
+CHANGELOG.md remains release history and must not describe v0.8.1 as released
+until the later release workflow actually publishes it.
+
+## 18. Explicit exclusions
+
+The v0.8.1 patch does not implement:
+
+- visual annotation authoring;
+- source editing;
+- automatic frontend correction;
+- coding-agent orchestration inside Observer;
+- automatic reference/runtime binding;
+- image-to-code generation;
+- deletion of historical canonical evidence;
+- implicit baseline/reference approval or supersession;
+- new evidence/evaluation engines;
+- cloud hosting, authentication, collaboration, or database-backed evidence.
+
+## 19. Version-wide acceptance
+
+The patch is complete only when all of the following are proven:
+
+- project initialization is deterministic and bounded;
+- configuration/project discovery works from project subdirectories;
+- managed state remains project-contained;
+- `capture <name>` reuses canonical observation behavior;
+- aliases resolve to canonical immutable evidence;
+- alias replacement preserves old evidence;
+- users do not need canonical hashes or output paths in the normal workflow;
+- `view` works without `--root` inside an initialized project;
+- alias-first viewer navigation works while canonical IDs remain inspectable;
+- existing `view --root` and every existing command remain backward compatible;
+- `check` never invents PASS from comparison evidence alone;
+- contract/reference failures remain canonical and independently visible;
+- `check --json` is bounded and coding-agent usable;
+- no artifact/evaluation schema changes are introduced;
+- real Chromium exercises the new workflow;
+- exact packed candidate works in a clean consumer;
+- applicable typecheck, lint, unit, browser, build, documentation, security, and
+  package validations pass.