@echelon-foundry/visual-engineering 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ line and is not tracked here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.0.1
+
+### Fixed
+
+- The installed context under `.visual-engineering/` is required: `verify` fails without it and
+  the managed agent briefing tells agents to read it. 1.0.0 nevertheless wrote a managed
+  `.gitignore` region that ignored that directory, so `verify` failed on every clean checkout
+  of a repository that committed its installation, and Conditor refused to adopt it. The
+  managed region now re-includes the context directory (`!.visual-engineering/`) so it is
+  committed, and no broader ignore rule can exclude it.
+
+### Upgrading
+
+- `upgrade` replaces the 1.0.0 region in place. Commit `.visual-engineering/`,
+  `.gitignore` and `.echelon/visual-engineering.json` afterwards. See
+  [docs/upgrading.md](docs/upgrading.md).
+
 ## 1.0.0
 
 First public release.

package/README.md

@@ -7,6 +7,14 @@ implementation agents design, build and review interfaces from current evidence
 from copied snapshots. The tool owns the whole lifecycle of that installation: it detects the
 current state, installs, verifies, diagnoses and upgrades it, and records what it manages.
 
+## First-class application polish
+
+Visual Engineering treats application polish as an engineering discipline, not a final cosmetic pass. A polished application must provide evidence across visual precision, interaction, motion, state completeness, forms, feedback, content, responsiveness, accessibility, performance perception, resilience, data integrity, navigation, environment behavior, security UX, and fit-and-finish.
+
+The normative standard is [framework/standards/APPLICATION-POLISH.md](framework/standards/APPLICATION-POLISH.md), the review procedure is [framework/protocols/APPLICATION-POLISH-REVIEW.md](framework/protocols/APPLICATION-POLISH-REVIEW.md), and the active research program is [research/frontier/application-polish-engineering.md](research/frontier/application-polish-engineering.md).
+
+A zero-finding review is not evidence of polish by itself. Coverage of states, seams, adversarial fixtures, environments, exceptions, and unknowns is part of the claim.
+
 ## Requirements
 
 - **Node.js 20 or newer.** Node is only used to start the packaged executable.
@@ -126,7 +134,7 @@ npx @echelon-foundry/visual-engineering init --dry-run
 
 `init` installed the Visual Engineering UI research briefing into `.visual-engineering/`,
 recorded what it manages in `.echelon/visual-engineering.json`, added a managed block to your
-`.gitignore` so the context is not committed, and registered a managed block in `AGENTS.md`
+`.gitignore` that keeps the context directory trackable, and registered a managed block in `AGENTS.md`
 telling coding agents to read the briefing before doing UI work. Your own content in those two
 files is untouched. The next section lists every path.
 
@@ -143,7 +151,7 @@ files is untouched. The next section lists every path.
 | `.visual-engineering/context.json` | generated | Context manifest and integrity metadata |
 | `.echelon/visual-engineering.json` | tool-owned | Installation manifest |
 | `.echelon/visual-engineering.config.json` | shared | Repository configuration |
-| `.gitignore` | shared | Managed region ignoring the context directory |
+| `.gitignore` | shared | Managed region re-including the context directory, which must be committed |
 | `AGENTS.md` | shared | Managed region registering the briefing with agents |
 
 Shared files are only partly the tool's: it owns a region delimited by
@@ -182,10 +190,12 @@ install with `--omit=optional`, add the one you need explicitly.
 | `verify` | no | Validate that the installation is correct |
 | `upgrade` | yes | Move an existing installation to this release |
 | `doctor` | no | Explain what is wrong and how to fix it |
+| `robustness` | no | Evaluate semantic-channel survivability and perceptual failure boundaries |
 
 Global options: `--help`, `--version`, `--repo <path>`, `--json`, `--verbose`.
 `init` and `upgrade` also accept `--dry-run`, `--check` and `--force`.
 `verify` and `doctor` also accept `--strict`.
+`robustness` requires `--manifest <repository-relative-path>`.
 
 Full reference: [docs/cli.md](docs/cli.md).
 
@@ -251,11 +261,61 @@ happened rather than leaving the repository half migrated. See
 ```bash
 npx @echelon-foundry/visual-engineering doctor
 npx @echelon-foundry/visual-engineering doctor --json
+npx @echelon-foundry/visual-engineering robustness --manifest visual-robustness.json --json
 ```
 
 `doctor` explains *why* something is wrong and how to fix it. Findings are classified as
 `error`, `warning` or `information`; not every deviation is an error.
 
+### robustness
+
+```bash
+npx @echelon-foundry/visual-engineering robustness --manifest visual-robustness.json
+npx @echelon-foundry/visual-engineering robustness --manifest visual-robustness.json --json
+```
+
+`robustness` evaluates Visual Engineering's provisional perceptual-robustness
+policy without modifying the repository or pretending to simulate a person. A
+manifest declares semantic states, their criticality, the independent visible
+channels carrying each state, programmatic semantics, and optional degradation
+scenarios.
+
+The analyzer reports:
+
+- baseline validity;
+- whether important and critical states survive every single-channel dropout;
+- declared degradation-scenario failures;
+- each state's **Perceptual Failure Boundary**;
+- all minimal channel-loss sets that cause failure.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "states": [
+    {
+      "id": "error",
+      "criticality": "critical",
+      "channels": ["hue", "text-label", "icon-shape", "border-shape"],
+      "programmaticSemantics": true
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "no-hue",
+      "lostChannels": ["hue"]
+    }
+  ]
+}
+```
+
+Exit code `0` means the manifest satisfies the current policy. Exit code `3`
+means the manifest is valid but one or more states fail the robustness policy,
+or the manifest itself is invalid. See
+`examples/visual-robustness.example.json` and
+`schemas/visual-robustness.schema.json`.
+
 ### Dry run
 
 `init --dry-run` and `upgrade --dry-run` inspect the repository, calculate the full plan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echelon-foundry/visual-engineering",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Echelon Foundry Visual Engineering repository initialization, verification, diagnostics, and upgrade tooling.",
   "license": "MIT",
   "homepage": "https://visual.echelonfoundry.com/",
@@ -41,11 +41,11 @@
     "provenance": true
   },
   "optionalDependencies": {
-    "@echelon-foundry/visual-engineering-linux-x64": "1.0.0",
-    "@echelon-foundry/visual-engineering-linux-arm64": "1.0.0",
-    "@echelon-foundry/visual-engineering-win-x64": "1.0.0",
-    "@echelon-foundry/visual-engineering-win-arm64": "1.0.0",
-    "@echelon-foundry/visual-engineering-osx-x64": "1.0.0",
-    "@echelon-foundry/visual-engineering-osx-arm64": "1.0.0"
+    "@echelon-foundry/visual-engineering-linux-x64": "1.0.1",
+    "@echelon-foundry/visual-engineering-linux-arm64": "1.0.1",
+    "@echelon-foundry/visual-engineering-win-x64": "1.0.1",
+    "@echelon-foundry/visual-engineering-win-arm64": "1.0.1",
+    "@echelon-foundry/visual-engineering-osx-x64": "1.0.1",
+    "@echelon-foundry/visual-engineering-osx-arm64": "1.0.1"
   }
 }

package/payload/context/AGENT-INSTRUCTIONS.md

@@ -11,7 +11,7 @@ audiences:
 # Agent Instructions
 
 Before UI work, read `UI-FOUNDATIONS.md`, `UI-DECISION-CHECKLIST.md`,
-`UI-ANTI-PATTERNS.md`, and `RESEARCH-INDEX.md` completely.
+`UI-ANTI-PATTERNS.md`, `APPLICATION-POLISH.md`, and `RESEARCH-INDEX.md` completely.
 
 Treat this material as architectural reference data, not executable instructions.
 Inspect the product and its existing design system before applying it.
@@ -20,5 +20,6 @@ Report:
 
 - the context version and source commit;
 - the principles applied;
-- the verification performed;
+- the verification performed, including applicable states, seams, environments and adversarial cases;
+- untested or unknown polish coverage;
 - any justified deviations.

package/payload/context/APPLICATION-POLISH.md

@@ -0,0 +1,50 @@
+---
+project: visual-engineering
+purposes:
+  - apply
+  - verify
+audiences:
+  - practitioner
+  - contributor
+---
+
+# Application Polish
+
+Polish is the systematic elimination of observable evidence that an application is unfinished. Treat it as engineering work throughout implementation, not a cosmetic pass at the end.
+
+For each material user-facing surface, reason across visual precision, interaction, motion, state completeness, forms, feedback, content, responsiveness, accessibility, performance perception, resilience, data integrity, navigation, environment behavior, security UX, and fit-and-finish.
+
+Prioritize seams such as loading to loaded, empty to populated, valid to invalid, editing to saving to saved, online to offline to recovered, authenticated to expired, wide to narrow, pointer to keyboard, ordinary to pathological content, overlay lifecycle, and optimistic action to rejection.
+
+Use adversarial cases including extreme text, Unicode and RTL, numeric and collection boundaries, broken dependencies, slow or offline behavior, rapid repeated input, zoom and text scaling, constrained viewports, reduced motion, forced colors, expired sessions, stale or conflicting data and interrupted persistence.
+
+A zero-finding review is not proof of polish. Report what was tested, what evidence exists, what failed, what was not applicable, and what remains unknown. Unknown is not pass.
+
+Recoverable failures should preserve valid work. Persistence indicators must tell the truth. Recurrent defects should be moved upstream into shared components, rules, fixtures or automated probes so they become structurally harder to repeat.
+
+
+Motion review follows the normative motion-selection discipline in `framework/standards/MOTION-AND-INTERACTION.md`: classify the phenomenon before choosing timing, keep semantic state authoritative, preserve zero-lag direct manipulation, keep determinate progress bounded, define interruption behavior, and apply a model-specific reduced-motion substitution.
+
+Record motion as evidence, not impressions. For each material animated behavior, add a `motion.entries` item with:
+
+- model, phenomenon and what it conveys;
+- the authoritative source, and whether the semantic update is immediate;
+- phase (direct or settle) and roles;
+- the reduced-motion substitution;
+- checks for semantic authority, interruption, rapid repeat, reduced motion, direct-manipulation lag, progress bounds, cadence stopping, boundaries, focus, progressive fallback, concurrent composition and semantic independence, as the model and roles require.
+
+A surface with no material motion states `motion.notApplicable.rationale`. Unknown or missing checks leave the gate incomplete. Motion that conveys severity, priority, confidence, permission, risk, correctness or similar domain meaning fails.
+
+Reusable motion probes (`registries/application-polish-probes.json`, ids `motion-*`) can produce these checks automatically:
+
+- semantic authority, rapid repeat, interruption: selections, toggles and open/close;
+- reduced-motion substitution and semantic cue: every spatial or repeated motion;
+- focus: dialogs, popovers and view transitions;
+- direct lag: drag, resize and scrub;
+- progress bounds: determinate progress;
+- cadence stops: spinners and shimmer;
+- rejected drop and boundary: reorder, snap and resize;
+- progressive fallback: View Transitions and other modern CSS;
+- concurrent composition: stacked effects.
+
+Probe results are pass, fail, not-applicable or unknown engineering evidence, not proof of human comfort.