@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.8.1-check-orchestration-prompt2.md

@@ -0,0 +1,69 @@
+# v0.8.1 Check Orchestration, Prompt 2
+
+## Repository and filesystem audit
+
+Starting HEAD was `b8b2eff50dfc16dd836d3b0b37ae30c7e767da21` on `master`; package and lockfile remain `0.8.0`. The Prompt 1 report and source establish the project configuration, discovery, managed paths, alias catalog, `init`, `capture`, project-aware `view`, Chromium proof, packed proof, canonical identity preservation, and readiness for Prompt 2.
+
+All correction-run state was confined to:
+
+`C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8.1\prompt2-correction`
+
+The resolved `tmp`, `logs`, `fixtures`, `consumer`, `pack`, `npm-cache`, `browser`, `evidence`, and `quarantine` paths were verified beneath that root. Process-local `TEMP`, `TMP`, and npm cache settings pointed there for validation. One ignored, untracked root-level `observations/` directory containing prior canonical runtime output was verified untracked and moved intact to `quarantine/observations`; no user or tracked file was deleted. `.claude/` remained ignored and untouched.
+
+## Implementation
+
+Project configuration now writes schema `1.1.0` while reading both `1.0.0` and `1.1.0`. Version `1.0.0` retains its exact Prompt 1 fields and rejects `acceptance`. Version `1.1.0` optionally accepts canonical comparison configuration, a paired baseline/change contract configuration, and an approved-reference configuration with optional explicit bindings. Paths are non-empty portable project-relative strings, reject absolute/drive/backslash/colon/NUL/dot/traversal forms, and are realpath-contained before use.
+
+`current` remains rejected by human `capture`; the alias catalog accepts it only as system-managed state. `projectCheckService` resolves the explicit baseline or `defaultBaseline`, verifies catalog/artifact observation and request identity, captures one new immutable current observation, atomically updates `current`, calls the canonical comparison service once, and conditionally calls the existing contract and reference-fidelity services. It never invokes the CLI recursively, edits frontend source, infers bindings, or creates another evidence engine.
+
+Canonical comparison artifacts persist under managed comparisons. Canonical contract evaluations persist under managed evaluations. Reference fidelity remains the existing in-memory result. There is no check artifact. The workflow precedence is BLOCKED, FAIL, PASS when every configured executable dimension passes, and REVIEW_REQUIRED when comparison succeeds without executable acceptance authority.
+
+`checkResult` schema `1.0.0` projects project-relative artifact paths, canonical contract failures/unavailable/conflicts and unexpected changes, and canonical failed/unavailable reference requirements. Every problem collection is limited to 50; supporting evidence is limited to 10 per contract item; truncation is explicit. It embeds no image bytes or complete artifacts. Human output emphasizes `baseline`/`current`, concise failures/blockers, and `my-frontend-observer view`, without routine hashes or absolute paths. Exit codes are PASS 0, FAIL 1, REVIEW_REQUIRED 2, and BLOCKED 3.
+
+## Acceptance evidence
+
+`tests/browser/projectCheckWorkflow.test.ts` uses the planner-owned fixture roots and file-backed disposable frontend source:
+
+- `review-required`: real Chromium captured a changed candidate and persisted a comparison; no executable acceptance returned REVIEW_REQUIRED/2.
+- `contract-fail-pass`: a requested nav change and expected workspace change succeeded while a protected rail width regressed. `check baseline --json` returned FAIL/1 and preserved canonical clause id, source, category, primitive, status, and supporting evidence. Only `source/index.html` changed; the same command then returned PASS/0. Project config and both contract manifests were byte-identical across correction.
+- `reference-fail-pass`: a canonically imported, explicitly approved reference with an explicit rail binding returned reference FAIL, then PASS after only frontend source correction, then BLOCKED from canonical viewport incompatibility.
+- `comparison-blocked`: a viewport change produced canonical `incomparable`, workflow BLOCKED, and exit 3.
+- `current-history`: repeated checks produced distinct immutable current observations, kept the old artifact, mapped `current` only to the newest exact path in the viewer, and preserved that mapping after a later capture failure.
+- `symlink-security`: Windows successfully created a real directory junction from the project through `escaped/` to a directory outside that project. Realpath containment rejected the acceptance path.
+
+Pure/unit projection tests deterministically created 52 failed clauses with 12 evidence references apiece and 52 failed plus 51 unavailable reference requirements. They proved the 50/10 bounds and global truncation flag. CLI tests cover help/grouping, syntax rejection, all four concise human statuses, and exactly one JSON line for a project-not-initialized BLOCKED outcome. Baseline tests cover explicit/default alias selection and invalid artifacts without absolute-path leakage.
+
+## Packed clean-consumer evidence
+
+One `npm pack --pack-destination <RunRoot>\pack` candidate was installed beneath exact paths `consumer\installed-package` and `consumer\target`. `scripts/ci/runPackedCheckSmoke.mjs` used only the installed binary and its installed Playwright dependency. It proved installed `init`, `capture baseline`, `check baseline --json`, project-aware `view`, REVIEW_REQUIRED, unchanged-contract protected-clause FAIL, source-only correction to PASS, `baseline` and `current` viewer labels, and canonical current identity in details. No artifact hash/path was a check input.
+
+The same tarball also passed `runPackedObservationSmoke.mjs` and `runPackedViewerSmoke.mjs`, including the legacy low-level observation/comparison/contract/reference surfaces and real-Chromium viewer/PWA behavior.
+
+## Documentation and security
+
+README, QUICKSTART, COMMANDS, WORKFLOWS, ARCHITECTURE, CURRENT_STATE, PROJECT_OVERVIEW, ROADMAP, SECURITY, DEVELOPMENT, and CI/CD are reconciled to source-complete v0.8.1 behavior while retaining package version `0.8.0` and explicitly not claiming publication. The roadmap now makes v0.9 depend on project discovery, aliases, project-aware viewing, and canonical identity beneath aliases; mutable aliases cannot be persisted annotation identity. v0.10 must reuse `check <baseline> --json` rather than reconstruct canonical comparison, contract, fidelity, or workflow precedence.
+
+Security evidence covers portable/contained acceptance paths, a real junction escape, project-relative JSON, no image bytes, approved-reference authority, explicit-only bindings, immutable current history, read-only viewer routes, and the absence of Observer source-edit behavior.
+
+## Validation
+
+Final commands:
+
+- `npm run typecheck`
+- `npm run lint`
+- `npm test`
+- `npm run build`
+- `npm run check:docs`
+- `npm run test:browser`
+- `npm run test:security`
+- `npm pack --pack-destination <RunRoot>\pack`
+- `node scripts/ci/runPackedCheckSmoke.mjs <tarball> --consumer-root <RunRoot>\consumer`
+- `node scripts/ci/runPackedObservationSmoke.mjs <tarball>`
+- `node scripts/ci/runPackedViewerSmoke.mjs <tarball>`
+- `git diff --check`
+
+Final source-checkout counts: 68 unit files / 1,180 tests; 21 browser files / 185 tests; security subset 10 unit files / 97 tests plus 3 browser files / 76 tests (173 total). All passed. All three packed proofs passed.
+
+## Remaining risk and readiness
+
+The Windows junction proof ran successfully. Cross-platform behavior remains protected by Node path/realpath APIs and portable-path unit cases; formal multi-OS publication validation remains the later release-readiness workflow. No product blocker remains. The repository is ready for v0.8.1 pre-release readiness, not publication.

package/docs/reports/v0.8.1-implementation-completeness-documentation-reconciliation.md

@@ -0,0 +1,114 @@
+# v0.8.1 Hardened Documentation and Implementation-Completeness Audit
+
+## Verdict
+
+PASS_V081_HARDENED_DOCUMENTATION_AND_IMPLEMENTATION_COMPLETENESS_AUDIT
+
+Starting candidate: `85ff1cbaa6c9cf86aa7de59cf3abeb09cbaa6877`.
+Source-of-truth order was the task contract, current Git/package state,
+preservation policy and durable product documents, frozen v0.8.1 plan,
+current implementation/tests, then predecessor reports. The Prompt 1 and
+Prompt 2 reports were corroborating evidence only.
+
+## Capability matrix
+
+| Capability | Plan source | Implementation | Tests | Documentation | Result |
+| --- | --- | --- | --- | --- | --- |
+| Config v1.0 compatibility | Plan §§3, 6 | `projectConfig.ts` | `projectWorkflow.test.ts` | COMMANDS | PASS |
+| Config v1.1 acceptance | Plan §6 | `projectConfig.ts`, `checkAcceptance.ts` | project workflow/check tests | COMMANDS | PASS |
+| Project discovery/managed state | Plan Prompt 1 | `projectDiscovery.ts`, `projectPaths.ts` | project workflow tests | ARCHITECTURE | PASS |
+| Alias grammar/atomic catalog | Plan Prompt 1 | `projectConfig.ts`, `aliasCatalog.ts` | project workflow tests | COMMANDS | PASS |
+| Immutable evidence/alias replacement | Plan Prompt 1 | project workflow service | browser workflow tests | WORKFLOWS | PASS |
+| `init` and `capture` | Plan Prompt 1 | CLI/project workflow service | CLI/browser/packed tests | README, COMMANDS | PASS |
+| Reserved `current` | Plan Prompt 2 | project workflow service/catalog validator | unit/browser tests | COMMANDS | PASS |
+| Project-aware `view` | Plan Prompt 1 | CLI/viewer service/projection | viewer/browser/packed tests | README, COMMANDS | PASS |
+| Standalone `view --root` | Plan Prompt 1 | existing view dispatch | viewer regression tests | COMMANDS | PASS |
+| Alias-first navigation/provenance | Plan Prompt 1 | evidence projection/React list | real Chromium/packed tests | ARCHITECTURE | PASS |
+| Explicit/default baseline | Plan Prompt 2 | `projectCheckService.ts` | check-service/browser tests | COMMANDS | PASS |
+| Current capture/history | Plan Prompt 2 | capture workflow/check service | browser tests | WORKFLOWS | PASS |
+| Canonical comparison/config reuse | Plan Prompt 2 | comparison service composition | browser/unit tests | ARCHITECTURE | PASS |
+| Contract orchestration | Plan Prompt 2 | contract evaluator composition | browser/unit/packed tests | COMMANDS | PASS |
+| Approved-reference governance/bindings/fidelity | Plan Prompt 2 | reference reader/fidelity composition | browser/unit tests | SECURITY, COMMANDS | PASS |
+| PASS/FAIL/REVIEW_REQUIRED/BLOCKED precedence | Plan Prompt 2 | `checkResult.ts` | unit/CLI/browser tests | COMMANDS | PASS |
+| Human check output | Plan Prompt 2 | CLI formatter | CLI/browser tests | WORKFLOWS | PASS |
+| Bounded `check --json` | Plan Prompt 2 | `checkResult.ts` | bounded projection tests | COMMANDS | PASS |
+| Check exit codes 0/1/2/3 | Plan Prompt 2 | CLI mapping | CLI/browser tests | COMMANDS, CI_CD | PASS |
+| No check artifact/no second engine | Plan Prompt 2 | check application composition | architecture/source audit | ARCHITECTURE | PASS |
+| Coding-agent FAIL-to-PASS loop | Plan Prompt 2 | check + canonical evaluators | browser/packed tests | WORKFLOWS | PASS |
+| Acceptance paths/realpath containment | Plan Prompt 2 | config/acceptance resolver | unit/browser junction tests | SECURITY | PASS |
+| Installed-package workflow | Plan Prompt 2 | packed viewer smoke | local/CI packed smoke | CI_CD, DEVELOPMENT | PASS |
+| Advanced-command compatibility | Plan Prompt 1/2 | preserved CLI services | unit/browser/packed observation tests | COMMANDS | PASS |
+
+No `MISSING_IMPLEMENTATION`, `MISSING_TEST`, `MISSING_DOCUMENTATION`, or
+`IMPLEMENTATION_DOCUMENTATION_DRIFT` remained after the reconciliation.
+
+## ROADMAP and CLI/help audit
+
+ROADMAP now correctly says v0.8.1 is implemented in the repository, package
+metadata remains `0.8.0`, and publication has not happened. v0.9 and v0.10
+remain future work; the v0.9 alias/canonical-identity invariant and v0.10
+reuse of `check <baseline> --json` are explicit.
+
+Built CLI help was captured under the prerelease audit root for every public
+command. The common surface is `init`, `capture`, `check`, `view`; advanced
+commands remain `observe`, `compare`, `approve-baseline`,
+`save-change-contract`, `evaluate-contract`, `import-reference`,
+`approve-reference`, and `evaluate-reference-fidelity`. Documentation now
+states that `view` discovers initialized project evidence without `--root`,
+while `view --root` remains the standalone compatibility form.
+
+Documentation records check exits exactly as PASS 0, FAIL 1,
+REVIEW_REQUIRED 2, BLOCKED 3. Comparison alone is evidence and yields
+REVIEW_REQUIRED, never PASS. JSON is documented as a bounded ephemeral
+workflow projection rather than a persisted artifact.
+
+## Architecture and code-rot audit
+
+Direct source tracing found one canonical semantic owner for browser
+observation (`observationPersistence`), comparison (`comparisonEngine`),
+frontend-contract evaluation (`frontendContractEvaluation`), reference
+compatibility, explicit binding, reference fidelity, bounded context,
+runtime/static correlation, discovery, catalog persistence, project-check
+orchestration, and check-result projection. `projectCheckService` composes
+those owners; it neither spawns the CLI nor adds an evaluation engine.
+
+The packed check helper that duplicated the viewer/project workflow was
+removed. `runPackedViewerSmoke.mjs` is now the single installed-package
+project/viewer smoke owner and covers REVIEW_REQUIRED plus unchanged-criteria
+FAIL-to-PASS before alias-aware viewer checks. `runPackedObservationSmoke.mjs`
+retains its lower-level legacy responsibility. Windows npm installation in
+both smoke owners invokes npm's CLI through Node with `shell: false`; no
+project-controlled value is shell command text.
+
+Historical release reports and frozen plans retain their older descriptions as
+historical evidence. Current-state documentation no longer presents v0.8.1 as
+merely planned or `view --root` as universally required.
+
+## Security and package truth
+
+The audit reconfirmed portable acceptance paths, realpath/junction containment,
+alias/catalog containment, immutable `current` replacement, project-relative
+JSON, approved-reference-only governance, explicit bindings, loopback/read-only
+viewer routing, media traversal containment, and PWA no-stale-evidence tests.
+The dynamic-execution search found `spawn` only in controlled viewer opening
+and CI/developer smoke infrastructure; production project/config/evidence
+inputs do not become executable command text. A real-Chromium source-hash test
+proves `capture`, `check`, and `view` do not modify target frontend source.
+
+`npm pack --dry-run --json` is audited in Phase B. Package metadata remains
+`0.8.0`; v0.8.1 is implemented in source but not released, tagged, or
+published. CHANGELOG remains release history and has no released v0.8.1 entry.
+
+## Validation and next gate
+
+Phase A reruns typecheck, lint, unit tests, build, documentation checks,
+browser tests, security tests, and `git diff --check` after reconciliation.
+Results: typecheck PASS; lint PASS; build PASS; unit suite PASS (68 files,
+1,180 tests); documentation check PASS; browser suite PASS (21 files,
+186 tests); security subset PASS (97 unit plus 77 browser tests); and diff
+whitespace check PASS.
+Phase B starts only from the clean reconciliation commit and independently
+repeats local/package/security/packed validation before exact-candidate
+cross-platform CI.
+
+Next stage: formal v0.8.1 pre-release readiness.

package/docs/reports/v0.8.1-prerelease-readiness-cross-platform-security-code-rot.md

@@ -0,0 +1,170 @@
+# v0.8.1 Pre-release Readiness
+
+## 1. Purpose and scope
+
+This report records formal readiness evidence for the source-complete v0.8.1
+project workflow. It is not release preparation: package metadata remains
+`0.8.0`; no npm publication, tag, GitHub Release, or master push occurs here.
+
+## 2. Entry gate and starting state
+
+The readiness branch began from master commit
+`85ff1cbaa6c9cf86aa7de59cf3abeb09cbaa6877`, with a clean tracked worktree.
+`origin/master` was an ancestor of local master. The documentation
+reconciliation commit is `02a930d295c84fc0f47521bac226ab5fb3553542`.
+
+## 3. Filesystem policy
+
+All generated readiness state is confined to
+`.my-dev-kit-workflow/v0.8.1/prerelease-readiness`, including temp/cache,
+audit snapshots, logs, packed candidate, consumer, fixture, browser, and CI
+state. Process-local TEMP/TMP/npm cache settings point there. No sibling
+project or repository-root disposable frontend is used.
+
+## 4. Documentation/completeness and architecture audits
+
+The companion
+`v0.8.1-implementation-completeness-documentation-reconciliation.md` report
+passes the bidirectional capability matrix. It found one CI-readiness/code-rot
+defect: v0.8.1 packed `check` proof was isolated in a separate helper rather
+than the established packed viewer owner. The helper was removed and
+`runPackedViewerSmoke.mjs` now proves installed `init`, `capture baseline`,
+`check --json` REVIEW_REQUIRED, unchanged-contract FAIL-to-PASS, `baseline`
+and `current` aliases, canonical-ID detail, and the viewer. The lower-level
+packed observation smoke remains separate by responsibility.
+
+Source tracing confirms one semantic owner each for browser observation,
+relationships, comparison, contract evaluation, reference compatibility,
+explicit binding, reference fidelity, bounded context, runtime/static
+correlation, discovery, catalog persistence, project-check orchestration, and
+check projection. `check` only composes canonical owners and creates no
+persisted check artifact or second evaluation engine.
+
+## 5. Local validation
+
+From the clean reconciliation commit: typecheck PASS; lint PASS; build PASS;
+unit PASS (68 files, 1,180 tests); browser PASS (21 files, 186 tests);
+security PASS (97 unit plus 77 browser tests); documentation check PASS; and
+`git diff --check` PASS. A real-Chromium source-hash regression test confirms
+that capture, check, and view do not modify a target frontend source file.
+
+## 6. Package-content and API audit
+
+`npm pack --dry-run --json` reports 314 files and no workflow state, evidence,
+consumer, fixture, browser profile, coverage, `.claude`, or nested tarball.
+Required compiled CLI, library, project-check, check-result, and viewer files
+are present. Built exports include `CHECK_RESULT_SCHEMA_VERSION` and
+`CHECK_WORKFLOW_STATUSES`; type-only check result interfaces are present in the
+published declarations.
+
+## 7. Security and code-rot audit
+
+Project discovery stops at the nearest config. Alias/catalog validation and
+atomic catalog persistence are fail-closed. Acceptance paths are portable and
+realpath-contained; a Windows junction escape is rejected by real browser
+coverage. `current` replacement changes catalog metadata only and preserves
+canonical history. Check JSON uses project-relative paths, bounded collections,
+and no image bytes. Imported references are not approved authority; bindings
+remain explicit; contract FAIL cannot be overridden by reference PASS.
+
+Viewer security regressions cover loopback binding, read-only methods,
+traversal/media containment, symlink/junction containment, and no stale PWA
+evidence. Production source has no eval/new-Function/vm execution. The only
+process spawns are controlled viewer opening and development/CI smoke tooling;
+Windows packed npm invocation uses Node's npm CLI with `shell: false`.
+
+## 8. Local packed candidate and workflow audit
+
+LOCAL_CANDIDATE_TARBALL: `my-frontend-observer-0.8.0.tgz`
+
+LOCAL_CANDIDATE_SHA256: `5e9ded9170c59de0f7c0205144fb1d6bb375ce6c6a5b70adef57f5223db43e3a`
+
+Local installed-package observation smoke: PASS (final candidate).
+
+Local installed-package project/viewer smoke: PASS (final candidate).
+
+The GitHub workflow builds and hashes one candidate in its Linux candidate job,
+uploads that tarball, downloads it on Windows/Linux/macOS, verifies the
+candidate SHA on every matrix runner, and runs both installed-package smokes.
+
+## 9. Historical failed exact-candidate evidence
+
+The latest candidate run was `35015180719` for commit
+`b32fe9759187c024cc5828b73cf0c6a682de95b0`. Its candidate job completed all
+validation, packaging, and artifact-hash steps successfully; the exact
+downloaded candidate passed both installed-package smokes on Windows and
+Ubuntu. macOS failed only the project/viewer smoke because that test compares
+the logical temporary path returned by Node (`/var/...`) to the physical path
+reported by the viewer (`/private/var/...`) in `/api/status`.
+
+This is a smoke-harness realpath presentation mismatch, not an evidence,
+containment, or product-workflow failure. It is nevertheless a formal matrix
+failure and therefore cannot be represented as cross-platform PASS.
+
+Previous run `35012678176` identified the original raw CLI artifact-path
+assumption. Run `35013965786` validated the first correction through candidate
+and Windows/Ubuntu, then identified the macOS logical/physical temporary-root
+mismatch.
+
+## 10. Authorized macOS realpath correction
+
+Classification: **TEST/READINESS PORTABILITY DEFECT**.
+
+Product behavior affected: **NO**.
+
+The viewer is permitted to report the physical evidence root. The defect was
+only the readiness smoke's raw string comparison of the caller-visible
+`/var/...` spelling with the physical `/private/var/...` spelling. The smoke
+now compares canonical physical identity with `fs.realpath()` and reports both
+the original spellings and canonical paths if a genuine mismatch occurs. On
+Windows, a smoke-local junction regression self-check proves that an alias and
+its target compare equal while a distinct directory compares unequal.
+
+Security semantics weakened: **NO**. This helper is limited to an
+already-authorized smoke assertion; project acceptance-path containment remains
+owned by production realpath validation and is unchanged.
+
+MACOS_REALPATH_TARGETED_CORRECTION: PASS
+
+## 11. Exact-candidate and cross-platform results
+
+OLD_FAILED_RUN: `35015180719`
+
+OLD_FAILED_COMMIT: `b32fe9759187c024cc5828b73cf0c6a682de95b0`
+
+ROOT_CAUSE: logical-vs-physical temporary path comparison on macOS
+
+The next run must build a new candidate once and validate that exact SHA on
+Windows, Linux, and macOS. This historical failed candidate is never rewritten
+as passing evidence.
+
+## 12. Corrected formal exact-candidate result
+
+CORRECTION_COMMIT: `d5986b5297a2b466b3373a6c896a447cdabe2bdb`
+
+NEW_GITHUB_ACTIONS_RUN_ID: `35018400346`
+
+FINAL_VALIDATED_COMMIT: `d5986b5297a2b466b3373a6c896a447cdabe2bdb`
+
+FORMAL_CANDIDATE_TARBALL: `my-frontend-observer-0.8.0.tgz`
+
+FORMAL_CANDIDATE_SHA256:
+`1ae46575595451e56f7c851273387ee4808e546940077e08a40cebcc1c4f8d30`
+
+WINDOWS: PASS
+
+LINUX: PASS
+
+MACOS: PASS
+
+CANDIDATE_SHA_PARITY: PASS
+
+The candidate job and all three exact-candidate jobs passed. The macOS packed
+project/viewer smoke passed the corrected filesystem-identity assertion.
+
+## 13. Release-state truth and next decision
+
+The source is not released as v0.8.1. Package version is `0.8.0`; npm
+publication, tag, GitHub Release, and master push are all absent. The final
+verdict is `PASS_V081_PRERELEASE_READINESS`; the next authorized stage is
+release preparation, not publication.

package/docs/reports/v0.8.1-project-workflow-foundation-prompt1.md

@@ -0,0 +1,66 @@
+# v0.8.1 Project Workflow Foundation, Prompt 1
+
+## 1. Verdict and repository state
+
+Verdict: PASS.
+
+Repository: `C:\Users\daile\Projects\my-frontend-observer`.
+
+Branch: `master`.
+
+Starting HEAD: `00c9c1e9c6080067c5ec812c98253cce25c7280f`.
+
+Required planning commit `056db1a0881c4f40fe0a968f022c27fbde8a117f` was fetched and fast-forwarded before implementation. The frozen two-prompt plan was verified and preserved. Package and lockfile version remain `0.8.0`.
+
+## 2. Recovered instruction-file state
+
+The intentional untracked `AGENTS.md`, `CLAUDE.md`, `agents.txt`, `claude.txt`, and `.claude/` paths were moved to `.my-dev-kit-workflow/v0.8.1/preflight-preservation`, the repository was fast-forwarded, and the paths were restored. The four portable project instruction files were committed as `b8ead5aa2300f29c4a97aa2a27832962adad61eb` (`chore: add coding agent project instructions`). `.claude/settings.json` was identified as local runtime permission state, preserved locally, and ignored through `.gitignore`.
+
+## 3. Implementation
+
+New ownership modules are `src/projectWorkflow/projectConfig.ts`, `projectDiscovery.ts`, `projectPaths.ts`, `aliasCatalog.ts`, and `src/application/projectWorkflowService.ts`.
+
+The project configuration schema is `1.0.0` with exactly `schemaVersion`, `url`, `viewport`, `targets`, and `defaultBaseline`. It reuses `RawNamedTarget` and validates URL, viewport, targets, locators, and output safety through `normalizeRequest()` with `.frontend-observer/evidence/_validation`. The default baseline is `baseline`.
+
+Aliases use exactly `^[a-z0-9][a-z0-9._-]{0,63}$`; traversal-like double-dot values are rejected and `current` is reserved. Catalog schema `1.0.0` maps aliases to canonical observation ID, request ID, and POSIX evidence-relative artifact directory. Readers fail closed. Writers serialize schema first, sort aliases, use two-space indentation and a trailing newline, write a sibling temporary file, and rename only after completion.
+
+Discovery walks upward from a resolved directory to the filesystem root and stops at the nearest `frontend-observer.json`. Managed paths are centrally derived for configuration, `.frontend-observer`, catalog, evidence, and observation output.
+
+`init` shares the existing viewport, CSS target, and structured target-file parsing owners. It creates configuration, catalog, and evidence state and inserts exactly one `.frontend-observer/` ignore entry. `--replace` replaces configuration only.
+
+`capture <alias>` discovers the project, validates configuration and catalog, normalizes one canonical observation request, calls `observe()` once with `{ cwd: projectRoot }`, and updates the alias only after persistence. Replacement leaves old evidence intact; failed replacement leaves the old mapping intact.
+
+`view` without `--root` discovers and validates project state, uses the managed evidence root, and supplies an in-memory exact-relative-directory alias map. Explicit `view --root` follows the existing standalone path with an empty alias map. `/api/index` adds only optional ephemeral `alias`; canonical handles, logical IDs, artifacts, and provenance are unchanged. The React list displays alias first while detail views retain canonical identity.
+
+Top-level help now groups `init`, `capture`, and `view` under Common workflow and all existing commands under Advanced. No `check` command was added.
+
+## 4. Tests and compatibility evidence
+
+Unit coverage includes configuration validation, exact fields and versions, root/nested/nearest discovery, not-initialized behavior, alias grammar and reservation, catalog versions/IDs/path traversal/determinism/atomic replacement, failed capture replacement transaction, path derivation, init help and behavior, target input forms, ignore idempotence, capture help, and updated view project behavior. Final unit result: 66 files and 1170 tests passed.
+
+Real Chromium test `tests/browser/projectWorkflowViewer.test.ts` initializes a disposable project, captures `baseline`, replaces it, verifies both immutable artifacts, verifies the exact new catalog mapping, starts the alias-aware viewer, confirms only the new record receives `baseline`, loads its screenshot workspace, and confirms the canonical ID remains in details. The final complete browser suite passed 20 files and 179 tests. Browser file concurrency is bounded to one worker to prevent Windows Chromium screenshot protocol exhaustion observed during full-suite validation.
+
+The packed viewer smoke now checks installed `init --help`, `capture --help`, and `view --help`, initializes through the installed CLI, captures `baseline`, launches installed project-aware `view` without `--root`, verifies exact alias index projection, and verifies alias-first real-Chromium display. The existing packed observation smoke and packed viewer smoke both passed against one tarball with SHA-256 `EB2C5ED27B61C367F21D3BA6393132634BAE69EE7E85E80831916AD6DEC61825`. Packed generated state is under `.my-dev-kit-workflow/v0.8.1/packed-proof` and is ignored.
+
+Existing low-level command unit and packed smoke coverage passed unchanged in semantics. Explicit-root viewer tests remain independent of project configuration. No canonical schema or evidence engine changed.
+
+## 5. Validation
+
+The final validation set includes:
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS, 1170 tests.
+- `npm run build`: PASS.
+- `npm run check:docs`: PASS.
+- `npm run test:browser`: PASS, 179 tests.
+- `npm run test:security`: PASS, 150 tests.
+- packed observation smoke: PASS.
+- packed viewer/project-workflow smoke: PASS.
+- `git diff --check`: PASS.
+
+## 6. Remaining risks and Prompt 2 readiness
+
+No product blocker remains. Alias catalog update failure after successful canonical capture intentionally reports failure while leaving the newly persisted canonical artifact unaliased; it never rolls back or deletes evidence. This is consistent with evidence immutability and fail-closed catalog semantics.
+
+Prompt 1 does not implement `check`, acceptance orchestration, coding-agent JSON output, annotation, editing, correction, or new evidence semantics. The project/alias foundation is ready for Prompt 2.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@dailephd/my-frontend-observer",
+  "version": "0.8.1",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Local-first browser runtime evidence producer",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dailephd/my-frontend-observer.git"
+  },
+  "bin": {
+    "my-frontend-observer": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "prebuild": "node scripts/clean.mjs",
+    "build": "tsc -p tsconfig.json && vite build --config viewer/vite.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p viewer/tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:browser": "vitest run --config vitest.browser.config.ts --passWithNoTests",
+    "test:security": "vitest run tests/unit/policy.test.ts tests/unit/viewerServer.test.ts tests/unit/viewerEvidenceServer.test.ts tests/unit/referenceViewerServer.test.ts tests/unit/contextViewerServer.test.ts tests/unit/paths.test.ts tests/unit/evidenceDiscovery.test.ts tests/unit/projectWorkflow.test.ts tests/unit/projectCheckService.test.ts tests/unit/projectCheckResult.test.ts && vitest run --config vitest.browser.config.ts tests/browser/chromiumAdapter.test.ts tests/browser/pwaHardening.test.ts tests/browser/projectCheckWorkflow.test.ts",
+    "check:docs": "node scripts/check-docs.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "@vitejs/plugin-react": "6.1.1",
+    "eslint": "10.8.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.66.0",
+    "vite": "8.2.2",
+    "vite-plugin-pwa": "1.3.0",
+    "vitest": "4.1.11"
+  },
+  "dependencies": {
+    "playwright": "^1.62.1"
+  }
+}