@dailephd/my-frontend-observer 0.8.1

package/docs/DEVELOPMENT.md

@@ -0,0 +1,202 @@
+# Development
+
+The released v0.8.1 workflow is published as
+`@dailephd/my-frontend-observer@0.8.1` (CLI `my-frontend-observer`).
+
+The v0.8.1 workflow is exercised through unit and real-Chromium tests. Project fixtures use `init`, `capture baseline`, and `check`; coding-agent consumers use bounded `check --json`. `tests/browser/projectCheckWorkflow.test.ts` covers REVIEW_REQUIRED, contract FAIL-to-PASS, reference FAIL/PASS/BLOCKED, incomparable BLOCKED, current history, and contained acceptance paths. `scripts/ci/runPackedViewerSmoke.mjs` is the single installed-package viewer/project-workflow smoke owner: it repeats REVIEW_REQUIRED and unchanged-contract FAIL-to-PASS before alias-aware viewer proof. Run the full unit, browser, security, build, documentation, and packed-consumer validations before release readiness.
+
+Install the current scaffold with `npm install`. Node.js 24+ is required.
+
+Since Batch 2, the package depends on `playwright` for the Chromium browser
+boundary. Install the browser binary once per machine with:
+
+```powershell
+npx playwright install chromium
+```
+
+The applicable foundation validation chain is:
+
+```powershell
+npm run typecheck
+npm run lint
+npm test
+npm run test:browser
+npm run build
+npm run check:docs
+npm pack --dry-run
+```
+
+`npm test` runs the fast unit suite only (`tests/unit/`; as of v0.8 Batch 8,
+1156 passing tests across 63 files, including the v0.6 bounded-agent-context
+projection/correlation and v0.8 viewer-server coverage). `npm run
+test:browser` runs the real-Chromium integration suite (`tests/browser/`; as
+of v0.8 Batch 8, 178 passing tests across 19 files, including the v0.8
+viewer/PWA real-browser proof) against deterministic local fixtures under
+`tests/fixtures/` and requires the Chromium binary above to be installed
+first; it is kept out of `npm test` because it launches a real browser and
+is slower. Exact counts drift as the suite grows - run the commands above
+for the current numbers rather than trusting this document.
+
+ROADMAP v0.1 and Project Milestone 1 require browser-level validation once the
+observation capability is planned and implemented. Static checks must not later
+be substituted for that required browser evidence. `npm run test:browser` is
+that required browser evidence and covers the full source-checkout v0.1
+workflow end to end: page/target evidence, atomic artifact persistence, and
+the real `observe` CLI (including a built `node dist/cli.js observe ...`
+smoke run) are all implemented and covered, including a deterministic
+real-navigation-failure case (distinct from a readiness timeout or a
+pre-launch safety rejection).
+
+For maintainers validating the package boundary itself (not required for
+routine development): `npm pack --dry-run` inspects the tarball contents;
+installing the real tarball (`npm pack --json`, then `npm install
+<tarball>` in a clean temporary directory) and running the installed bin
+against a disposable local HTTP target is the way to confirm the packaged
+CLI performs a real observation independent of the source checkout. This is
+local package validation only, not a release procedure.
+
+`npm run test:security` runs only the safety-relevant subset of the suite
+(`tests/unit/policy.test.ts` plus the real-Chromium enforcement cases in
+`tests/browser/chromiumAdapter.test.ts`) - a discoverable entry point for
+security review tooling, not a replacement for `npm test`/`npm run
+test:browser`.
+
+`scripts/ci/runPackedObservationSmoke.mjs <tarball-path>` is the same
+packed-candidate smoke described above, packaged as a reusable script: it
+installs the given tarball into a fresh temporary consumer directory,
+installs Chromium via that consumer's own Playwright dependency, runs the
+installed bin against a disposable local HTTP target it creates itself, and
+validates the resulting artifact - exiting nonzero on any contract failure.
+It is what `.github/workflows/pre-release-readiness.yml` runs identically on
+Windows, Linux, and macOS against one shared candidate tarball (see
+`docs/CI_CD.md`); it can also be run locally the same way the workflow runs
+it. It is readiness/CI infrastructure only, not part of the published
+package and never imported by production code. In the same run it
+exercises the legacy CSS-shorthand `--target` packed-observation shape,
+the structured semantic `--targets-file` shape, a `window-scroll-by`
+scroll scenario, and a `target-scroll-by` scroll scenario - see
+`docs/CI_CD.md` for the current readiness coverage.
+
+`scripts/dev/builtCliTargetsFileSmoke.mjs` is a separate, narrower v0.2
+development smoke, added alongside the `--targets-file` implementation: it
+runs the built `dist/cli.js` directly (`node dist/cli.js observe
+--targets-file ...`) against an inline disposable local HTTP fixture and a
+temporary JSON target file, proving a real semantic observation persists a
+valid schema-`1.2.0` artifact with no packed-tarball step involved. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliTargetsFileSmoke.mjs
+```
+
+`scripts/dev/builtCliScrollScenarioSmoke.mjs` is the v0.3 equivalent, added
+alongside the `--scroll-scenario-file` implementation: it runs the built
+`dist/cli.js` directly against an inline disposable local HTTP fixture,
+once with a temporary `window-scroll-by` scenario file and once with a
+temporary structured `--targets-file` plus a `target-scroll-by` scenario
+file, proving both real runtime scroll actions persist a valid
+schema-`1.2.0` artifact with populated `scrollScenarioEvidence`,
+scenario-file path privacy, and target-application immutability. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliScrollScenarioSmoke.mjs
+```
+
+`scripts/dev/builtCliCompareSmoke.mjs` is the v0.4 equivalent, added
+alongside the `compare` command implementation (shipped as part of the
+published `0.4.0` package - see `docs/CURRENT_STATE.md`): it runs the built
+`dist/cli.js` twice as
+`observe` against an inline disposable local HTTP fixture whose served
+content changes deterministically between the two runs (a real moved/
+resized target, and a page-width transition from fitting to exceeding the
+viewport), then runs the built `dist/cli.js compare` against the two
+resulting persisted observation artifacts. It validates artifact kind/
+schema `1.0.0`, `comparability: "comparable"`, source observation
+references, at least one real `moved` difference and one real page-width
+relationship change, that the comparison directory contains `manifest.json`
+only, that no operational filesystem path leaked into the persisted
+manifest, and that both source observation manifests are byte-identical
+before and after the comparison ran. Run it locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliCompareSmoke.mjs
+```
+
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` is the v0.5 equivalent,
+added alongside the `approve-baseline`/`save-change-contract`/
+`evaluate-contract` command implementations (shipped as part of the
+published `0.5.0` package - see `docs/CURRENT_STATE.md`). Unlike the other dev smokes, it needs no Chromium
+at all: it hand-writes deterministic, schema-`1.2.0`-valid observation
+manifests directly to a temporary directory (preserving the public
+observation artifact contract without a real browser capture), then runs
+the built `dist/cli.js` for `compare`, `approve-baseline`,
+`save-change-contract`, and `evaluate-contract` - twice for the final
+step, once without `--enforce` and once with it, against the same
+milestone-signature contract (requested navigation shrink = pass, expected
+workspace expansion = pass, protected right-rail width = fail, preserved
+unclipped navigation = fail, overall = `FAIL`). It validates both exit
+codes (`0` without `--enforce`, nonzero with it), that both invocations
+persist byte-for-byte semantically identical evaluation evidence
+(`evaluationRequestId` and `clauseResults` equal), that the evaluation
+directory contains `manifest.json` only, that no operational filesystem
+path leaked into either persisted evaluation manifest, and that every
+source observation/comparison/contract artifact remains unmodified. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliFrontendContractsSmoke.mjs
+```
+
+`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` is the v0.5 Batch 5
+real-browser equivalent, added alongside
+`tests/browser/cliFrontendContracts.test.ts`. Unlike the Chromium-free
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` above, this one launches a
+real disposable local HTTP fixture and real Playwright Chromium, then drives
+the built `dist/cli.js` through the complete `observe` → `approve-baseline`
+→ `save-change-contract` → `observe` → `compare` → `evaluate-contract`
+sequence twice: once against a candidate whose served content produces a
+fully successful contract change (all clauses `pass`, overall `PASS`), and
+once against a candidate that reproduces the milestone-signature failure - a
+real observed navigation clipping regression and a real observed right-rail
+width regression alongside an otherwise-successful requested/expected-
+dependent change (overall `FAIL`). It validates the same `--enforce`
+exit-code/identity behavior, screenshot-free evaluation directory, source
+immutability, and path-privacy properties as the Chromium-free smoke, but
+against genuine rendered geometry instead of hand-constructed artifacts. Run
+it locally after `npm run build` (Chromium must already be installed):
+
+```powershell
+node scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs
+```
+
+Since v0.8 Batch 1, `npm run build` also builds the browser-side viewer app
+(`viewer/`) with Vite into `dist/viewer` (see `docs/ARCHITECTURE.md` "v0.8
+Batch 1"). `npm run typecheck` additionally type-checks `viewer/tsconfig.json`
+alongside the existing `tsconfig.json`. To smoke-test the built viewer
+locally after `npm run build`:
+
+```powershell
+node dist/cli.js view --root <evidence-root> --no-open
+```
+
+optionally adding `--bindings-file <json-file>` and/or `--context-file
+<json-file>` (see `docs/COMMANDS.md#view` for their exact shapes), then open
+the printed `http://127.0.0.1:4319` URL in a browser (or stop with Ctrl+C).
+This starts a real, loopback-only server serving the actual built PWA. As of
+v0.8 (all eight implementation batches), it reads `--root` only for bounded,
+read-only evidence discovery through the existing canonical
+readers/classifiers - it never writes to `--root` or modifies any artifact
+under it.
+
+Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these five dev
+smokes is wired into any CI workflow or is a release gate - they are
+source-checkout development evidence only, proving the built CLI's
+`--targets-file`/`--scroll-scenario-file`/`compare`/frontend-contract
+command behavior without installing a packed tarball or requiring
+cross-platform infrastructure. None is part of the published package.
+Cross-platform packed validation of the v0.1-v0.5 observation/compare/
+contract behavior is `scripts/ci/runPackedObservationSmoke.mjs`'s
+responsibility (see `docs/CI_CD.md`) - the same script, against the same
+single candidate tarball per platform, now including the v0.5 contract/
+evaluation CLI.

package/docs/DOCUMENTATION_PRESERVATION_POLICY.md

@@ -0,0 +1,50 @@
+# Documentation Preservation Policy
+
+Current explicit user decisions have highest authority. The complete
+repository-local Project Description then owns durable product intent, and the
+complete repository-local Project Milestones owns capability ordering, major
+requirements, acceptance expectations, and cross-milestone rules. ROADMAP
+derives version-level direction from both. Actual repository evidence is the
+authority for claims about current implementation and release state. Accepted
+greenfield artifacts may prove an approved design decision but do not alone
+prove implementation. Reconnaissance informs decisions but does not replace
+intent.
+
+Responsibilities are distinct:
+
+- `PROJECT_DESCRIPTION.md` contains complete durable product intent, the three
+  primary jobs, long-term product model, principles, and ecosystem boundaries.
+- `PROJECT_MILESTONES.md` contains the complete ordered capability design,
+  acceptance expectations, and cross-milestone rules.
+- `ROADMAP.md` owns version-level goals, constraints, dependencies, exclusions,
+  ecosystem implications, acceptance, and unresolved planning decisions.
+- `docs/plans/<version>-implementation-plan.md`, when present, owns the frozen
+  concrete implementation plan produced at version start after the roadmap and
+  current repository state have been inspected. It may contain implementation
+  architecture decisions, batch structure, sequencing, batch acceptance gates,
+  validation expectations, explicit exclusions, and the post-implementation
+  handoff into documentation reconciliation and release-readiness workflows.
+  It is a planning authority only and never proves that a batch or version was
+  actually implemented.
+- `CURRENT_STATE.md` describes only actual implementation, scaffold, validation,
+  and release state.
+- `ARCHITECTURE.md` describes implemented architecture and may include clearly
+  labeled durable or planned extension constraints.
+- `PROJECT_OVERVIEW.md` is concise navigation and orientation; it does not
+  replace the complete authorities.
+
+Once a version-specific implementation plan is explicitly frozen, coding-agent
+prompts for that version must preserve its scope and batch order unless the user
+explicitly revises the plan. Batch execution reports may document what happened
+but do not silently rewrite the plan. If implementation evidence requires a
+change, record the explicit plan revision in the version plan before subsequent
+batches are treated as governed by the new sequence.
+
+ROADMAP must not override Project Description or Project Milestones on durable
+intent, and it must never contain prewritten implementation batches, command
+transcripts, or execution bookkeeping. A version plan must not promote a
+future-version capability into the current version or contradict the roadmap's
+version-level scope. Current-state documents do not override future product
+intent merely because implementation is incomplete. Before deleting,
+relocating, or replacing a source document, verify that all unique information
+and useful historical provenance remain.