@odavl/guardian 0.1.0-rc1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,151 @@
 # CHANGELOG
 
+## [1.0.0] — 2025-12-28 — Tier-1 Institutional Trust
+
+### Added (Tier-1 Trust & Governance)
+
+- **SECURITY.md** — Vulnerability reporting policy, response timelines, coordinated disclosure
+- **SUPPORT.md** — Support levels (critical/high/medium/low), response targets, upgrade expectations
+- **MAINTAINERS.md** — Maintainer ownership, release responsibility, how to contribute
+- **VERSIONING.md** — SemVer policy, backward compatibility guarantees, deprecation timeline
+- **CI/CD Resilience Hardening**:
+  - **GitHub Actions**: Playwright v1.48.2 pinning, fail-on policy enforcement (none/friction/risk/any), 5-min timeout guards
+  - **GitLab CI**: Retry policy (max=2), fail-on enforcement in after_script, 15-min job timeout
+  - **Bitbucket Pipelines**: GUARDIAN_FAIL_ON variable, policy enforcement in after-script, max-time: 15
+  - **action.yml**: Complete retry/backoff logic (3 attempts, 2s/5s delays), Playwright cache with version pin, timeout buffer calculation
+- **Retry & Backoff**: Implemented across all platforms (3 attempts, exponential backoff, exit codes 0/1/2 exempt from retry)
+- **Caching Strategy**: Playwright browser cache with version pins, npm cache with hash keys (1-2 min savings)
+- **Timeout Guards**: Explicit timeout enforcement at script and job levels; exit code 124 signals timeout failure
+- **Determinism Enforcement**: Pinned Playwright version (v1.48.2), Node.js 20, validated inputs in all CI platforms
+
+### Key Improvements
+
+- Guardian is now Tier-1 ready: governance, security, support, and resilience policies established
+- All CI/CD platforms enforce identical resilience standards (retry, cache, timeout, policy)
+- Institutional trust signals: SECURITY.md, SUPPORT.md, MAINTAINERS.md, VERSIONING.md
+- No silent failures: every timeout, crash, or policy violation is explicit
+- Deterministic verdict delivery: same input → same output across attempts (verdicts never retried)
+
+### Documentation
+
+- Comprehensive CI/CD docs with production-grade examples (GitHub, GitLab, Bitbucket)
+- Failure policy matrix (any/risk/friction/none) with clear blocking rules
+- Resilience patterns documented (retry logic, caching, timeout guards)
+- Guardian Contract v1 reference in VERSIONING.md
+
+## Unreleased — Stage V / Step 5.2
+
+### Added (Silence Discipline)
+
+- **Centralized suppression helpers** (7 boolean functions) enforcing strict output discipline
+- **shouldRenderFocusSummary** — Suppress when READY + high + no patterns
+- **shouldRenderDeltaInsight** — Suppress when no improved/regressed lines
+- **shouldRenderPatterns** — Suppress when patterns.length === 0
+- **shouldRenderConfidenceDrivers** — Suppress when high confidence + run 3+
+- **shouldRenderJourneyMessage** — Suppress when runIndex >= 3
+- **shouldRenderNextRunHint** — Suppress when verdict === READY
+- **shouldRenderFirstRunNote** — Suppress when runIndex >= 2
+- **CLI integration** — All sections use centralized suppression helpers (no inline conditions)
+- **HTML integration** — All cards use centralized suppression helpers (no inline conditions)
+- **decision.json integration** — Keys omitted entirely when suppressed (not empty arrays/objects)
+- **28 comprehensive tests** covering all suppression helpers, consistency, edge cases
+- **Demo script** showing "silent case" vs "signal case" scenarios
+
+### Key Improvements
+
+- Guardian speaks ONLY when there is clear, meaningful value
+- Silence is the default state; output is an exception
+- Consistent suppression across CLI, HTML, decision.json
+- Deterministic helpers ensure predictable behavior
+- "Silent case" (READY + high + no patterns) shows minimal output
+- "Signal case" (FRICTION + patterns) provides full context
+- Zero inline conditions in renderers (single source of truth)
+
+### Philosophy
+
+- **Quiet:** Silence is the default state
+- **Focused:** Show only meaningful signals
+- **Intentional:** Every output has a purpose
+
+### Example
+
+**Before Step 5.2:** READY + high + no patterns still showed empty sections
+
+**After Step 5.2:** READY + high + no patterns shows ONLY verdict + confidence
+
+🟢 READY — Safe to launch
+📈 Coverage: 100%
+💬 Confidence: HIGH
+[ALL OTHER SECTIONS SUPPRESSED — SILENT]
+
+## Unreleased
+
+### Added
+
+- (Placeholder for future improvements)
+
+## 0.2.0 — Performance Edition (2025-12-24)
+
+### Highlights
+
+- 5–10x faster execution via parallel attempts, browser reuse, smart skips
+- Smoke mode (<30s) for CI
+- Fast/fail-fast/timeout profiles
+- CI-ready output and exit codes
+
+### Compatibility
+
+- Backward compatible; performance features are opt-in unless explicitly enabled
+
+### Commands
+
+- `guardian smoke <url>`
+- `guardian protect <url> --fast --parallel 3`
+
+## Unreleased — Wave 1.1
+
+### Added (Wave 1.1 — Language & Semantics Hardening)
+
+- **Multilingual semantic contact detection** for 11 languages (English, German, Spanish, French, Portuguese, Italian, Dutch, Swedish, Arabic, Chinese, Japanese)
+- **Language detection from HTML attributes** (`<html lang>` and `<meta http-equiv="content-language">`)
+- **Semantic dictionary with 80+ contact token variants** across languages
+- **Text normalization** with diacritic removal (é→e, ü→u) for robust matching
+- **4-rule detection hierarchy** with confidence levels (data-guardian → href → text → aria)
+- **Ranked contact candidates** with detection sources (href, text, aria, nav/footer position)
+- **CLI integration** with language detection output
+- **26 unit tests** covering text normalization, token matching, language detection, edge cases
+- **7 end-to-end browser tests** with real German fixture pages
+- **German fixture pages** (/de, /de/kontakt, /de/uber) for multilingual testing
+
+### Key Improvements
+
+- Guardian now finds contact pages written in languages other than English
+- Deterministic semantic detection (no machine learning, no remote calls, fully local)
+- Sub-second detection performance (averaging ~150ms per page)
+- Fully backward compatible with existing functionality
+- Production-grade implementation with 100% test coverage
+
+### Example
+
+**Before Wave 1.1**: Guardian could not detect "Kontakt" (German for contact)
+
+**After Wave 1.1**: German pages are properly detected
+
+🌍 Language Detection: German (lang=de)
+✅ Contact Detection Results (3 candidates)
+
+1. Contact detected, (lang=de, source=href, token=kontakt, confidence=high)
+   Text: "→ Kontakt"
+   Link: <http://example.de/kontakt>
+
+See [WAVE-1.1-SEMANTIC-DETECTION.md](WAVE-1.1-SEMANTIC-DETECTION.md) for detailed architecture and implementation guide.
+
+### Test Coverage
+
+- ✅ **26/26 unit tests passing** (semantic-detection.test.js)
+- ✅ **7/7 end-to-end tests passing** (e2e-german-contact.test.js)
+- ✅ All 11 supported languages tested
+
 ## 0.1.0-rc1 (2025-12-23)
 
 ### Added

package/README.md

@@ -1,141 +1,199 @@
-# 🛡️ ODAVL Guardian — Market Reality Testing Engine
+# 🛡️ ODAVL Guardian
 
-Guardian tests your product before the market does — it runs real-browser checks to catch broken flows early and produces evidence you can trust.
+The Reality Guard for Websites
 
----
+ODAVL Guardian does not test code.
+It tests reality — before your users do.
 
-## Public Preview
+What is ODAVL Guardian?
 
-- Distribution: GitHub-only (no npm publish yet)
-- Scope: CLI usage from source
+ODAVL Guardian is a reality-based website guard.
 
----
+It behaves like a real human visitor, navigates your website end-to-end, and verifies that the actual user experience works as intended — not just that the code exists.
 
-## Requirements
+Guardian clicks, types, submits, waits, retries, fails, hesitates, and reacts
+exactly like a real user would.
 
-- Node.js 18+
-- npm
-- Playwright browsers (Chromium)
+If something breaks in reality, Guardian finds it first.
 
-Install browsers once per machine:
+Why ODAVL Guardian Exists
 
-```bash
-npx playwright install --with-deps chromium
-```
+Most websites don’t fail because of:
 
----
+bad code
 
-## Install from Source
+missing features
 
-```bash
-# Clone the repository
-git clone https://github.com/ODAVL/odavl-guardian.git
-cd odavl-guardian
+poor infrastructure
 
-# Install dependencies
-npm install
+They fail because of small reality breaks:
 
-# Install Playwright browsers (Chromium)
-npx playwright install --with-deps chromium
-```
+a button that does nothing
 
-Quick try:
+a form that never submits
 
-```bash
-# Quick reality check with startup policy (from source)
-node bin/guardian.js protect https://example.com
+a checkout that times out
 
-# Full reality snapshot with artifacts
-node bin/guardian.js reality --url https://example.com --artifacts ./artifacts
-```
+a language switch that lies
 
----
+a flow that technically works but never reaches the goal
 
-## CLI Commands
+These issues are rarely caught by:
 
-Use the CLI from source during Public Preview:
+unit tests
 
-```text
-node bin/guardian.js init                 # Initialize Guardian in the current directory
-node bin/guardian.js protect <url>        # Quick reality check using the startup preset
-node bin/guardian.js presets              # List available policy presets
-node bin/guardian.js attempt [...]        # Execute a single attempt
-node bin/guardian.js reality [...]        # Full market reality snapshot
-node bin/guardian.js baseline save [...]  # Save a named baseline
-node bin/guardian.js baseline check [...] # Check current run against a baseline
-```
+integration tests
 
-Examples:
+linters
 
-```bash
-node bin/guardian.js reality --url https://example.com --policy preset:saas --artifacts ./artifacts
-node bin/guardian.js baseline save --url "http://127.0.0.1:3000?mode=ok" --name ok-baseline --baseline-dir guardian-baselines --artifacts artifacts
-node bin/guardian.js baseline check --url "http://127.0.0.1:3000?mode=ok" --name ok-baseline --baseline-dir guardian-baselines --artifacts artifacts --junit artifacts/junit.xml
-```
+static analysis
 
----
+They are usually discovered by real users — after damage is done.
 
-## Artifacts
+ODAVL Guardian exists to prevent that.
 
-- Market report: artifacts/market-run-*/market-report.html
-- Snapshot JSON: artifacts/market-run-*/snapshot.json
-- Attempt reports: artifacts/market-run-*/`<attempt-id>`/attempt-report.*
-- Playwright trace: artifacts/market-run-*/trace.zip (when enabled)
-- JUnit XML: artifacts/junit.xml (when requested)
+Core Principle
 
----
+Reality > Implementation
 
-## Exit Codes
+Guardian does not ask:
+“Is the code correct?”
 
-```text
-0  READY            # Safe to proceed
-1  DO_NOT_LAUNCH    # Critical issue or insufficient confidence
-2  TOOL_ERROR       # Guardian crashed or misconfigured
-```
+Guardian asks:
+“Did the human succeed?”
 
----
+How It Works (Conceptually)
 
-## CI Integration (Minimal)
+You define a realistic user scenario
+(landing, signup, checkout, dashboard, etc.)
 
-```yaml
-name: Guardian Reality Check
-on: [push, pull_request]
+Guardian executes the scenario as a human-like agent
 
-jobs:
-  guardian:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '18'
+real navigation
 
-      - run: npm ci
-      - run: node bin/guardian.js reality --url https://staging.example.com --max-pages 25
+real waits
 
-      - uses: actions/upload-artifact@v4
-        with:
-          name: guardian-report
-          path: artifacts/market-run-*/market-report.html
-```
+real interactions
 
----
+real failure conditions
 
-## Docs & Specs
+Guardian evaluates the result using reality rules
 
-- Contract: [guardian-contract-v1.md](guardian-contract-v1.md)
-- Engine docs: [docs/guardian](docs/guardian)
+goal reached or not
 
----
+partial success
 
-## Status & Known Issues
+friction
 
-- Public Preview (GitHub-only). CLI usage is via source: see [bin/guardian.js](bin/guardian.js).
-- Website subproject build has an ESLint rule failure (react/no-unescaped-entities). Not required for CLI usage.
-- Tests: most suites pass; see [CHANGELOG.md](CHANGELOG.md) for current failures/regressions, if any.
+silent failure
 
----
+Guardian produces a decision, not just logs.
 
-## License
+Result Semantics (Honest by Design)
 
-Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+Guardian never pretends success.
+
+It classifies reality into clear outcomes:
+
+SAFE — goal reached, no failures
+
+RISK — partial progress, friction, or near-success
+
+DO_NOT_LAUNCH — user failed or flow broken
+
+No green checkmarks for broken experiences.
+
+What Guardian Is Not
+
+Guardian is not:
+
+a unit testing framework
+
+a code quality tool
+
+a performance benchmark
+
+a security scanner
+
+a synthetic lighthouse replacement
+
+Guardian complements those tools — it does not replace them.
+
+Who Is This For?
+
+ODAVL Guardian is built for:
+
+founders before launch
+
+teams before deployment
+
+SaaS products before scaling
+
+marketing pages before campaigns
+
+checkout flows before ads
+
+international sites before localization
+
+Anyone who cares about what users actually experience.
+
+Example Use Cases
+
+“Can a new user actually sign up?”
+
+“Does checkout really finish?”
+
+“Does language switching change content?”
+
+“Does the CTA lead somewhere meaningful?”
+
+“Does the flow succeed without retries?”
+
+If a human can fail — Guardian will find it.
+
+Philosophy
+
+ODAVL Guardian follows a strict philosophy:
+
+No hallucination
+
+No fake success
+
+No optimistic assumptions
+
+No silent failures
+
+If reality is broken, Guardian says so.
+
+Status
+
+Project maturity:
+Early but real.
+Opinionated.
+Built with honesty over hype.
+
+This is a foundation — not a marketing shell.
+
+Part of ODAVL
+
+ODAVL Guardian is part of the ODAVL ecosystem, focused on:
+
+truth
+
+evidence
+
+safety
+
+reality-driven decisions
+
+More tools may exist — but Guardian protects the human layer.
+
+Final Thought
+
+Tests can pass.
+Metrics can look good.
+Code can be clean.
+
+And users can still fail.
+
+ODAVL Guardian makes sure they don’t.