baldart 3.17.0 → 3.18.0

package/framework/.claude/skills/new/SKILL.md

@@ -811,93 +811,107 @@ After completeness is verified, clean up the implementation before it reaches re
    If any valid finding revealed a reusable pattern or common mistake, append 1-line to `## Lessons Learned`:
    `SIMPLIFY: <pattern> — <file>`
 
-### Phase 2.6 — E2E Testing (PRD-driven, card-level)
-
-This phase uses the `test_plan` field from the backlog card YAML to determine whether
-to write and run E2E tests. The test plan was defined during `/prd` discovery.
-
-**Trigger detection** — read the card's `test_plan` field:
-
-| `test_plan.e2e_required` | Action |
-|--------------------------|--------|
-| `true` | **AUTO-TRIGGER** — proceed directly, no user confirmation needed |
-| `false` | **SKIP** — log "E2E testing: SKIP (PRD evaluation: not needed)" in tracker |
-| field missing | **FALLBACK to legacy detection** (see below) |
-
-**Legacy fallback** (only when `test_plan` field is absent — old cards without PRD test plan):
-Check if ALL conditions are met:
-1. The card's `areas` field includes any of: `ui`, `frontend`, `booking`, `customer`, `merchant-dashboard`, `onboarding`, `settings`.
-2. The changed files include at least one `.tsx` page file (under `src/app/`).
-3. The card type is NOT `docs`, `chore`, or `config`.
-If all met, ask the user: `Vuoi testarlo con Playwright E2E? (si/no)`
-
-**When E2E runs** (auto-triggered or user-confirmed):
-
-1. **Update tracker**: phase = "2.6-e2e-testing".
-2. Read test scenarios and credentials from `test_plan`:
-   - `test_scenarios` — pre-planned scenarios with mapped user stories/ACs
-   - `test_credentials` — persona, auth method, credentials, store
-   - `test_data_prerequisites` — data that must exist
-3. Spawn a **coder** agent to write the Playwright E2E test:
-   ```
-   Write a Playwright E2E test for card <CARD-ID>.
-
-   Test file: tests/e2e/<card-id-slug>.spec.ts
-   Use: import { test, expect } from '@playwright/test'
-
-   ## Pre-planned Test Scenarios (from PRD)
-   [paste test_scenarios from card YAML — each has description, mapped US/AC, priority]
-
-   ## Test Credentials
-   Persona: [from test_plan.test_credentials.persona]
-   Auth method: [from test_plan.test_credentials.auth_method]
-   Credentials: [from test_plan.test_credentials.credentials]
-   Store: [from test_plan.test_credentials.store]
-   Notes: [from test_plan.test_credentials.notes]
-
-   ## Auth Handling
-   - If persona is CUSTOMER with OTP auth: navigate to login, enter phone number,
-     then use `await test.step('OTP input (manual)', async () => { await page.pause() })`
-     to pause for manual OTP entry by the user. After pause resumes, continue the flow.
-   - If persona is MERCHANT with password auth: use page.fill() for username/password
-     fields, then submit the login form. No manual intervention needed.
-
-   ## Test Data Prerequisites
-   [paste test_data_prerequisites — data that must exist in the persistence layer before the test runs]
-
-   ## Guidelines
-   - Use page.getByRole(), page.getByText(), page.getByTestId() for selectors
-   - Use expect(locator) assertions with auto-waiting
-   - Group related steps with test.describe()
-   - Implement ALL scenarios from the PRD test plan (not just happy path)
-   - Use baseURL from config (just page.goto('/relative-path'))
-   - Do NOT use chromium.launch() or manual browser management
-   - For OTP flows: use page.pause() and document it clearly in test output
+### Phase 2.6 — End-to-End Review (BLOCKING, since v3.18.0)
+
+This phase delegates to the `/e2e-review` skill — a deterministic, BLOCKING
+orchestrator that combines functional E2E (Playwright spec written by `coder`,
+executed via `playwright-skill`) with visual fidelity diff
+(`visual-fidelity-verifier` multimodal agent), aggregates findings under a
+strict severity gate, runs a bounded self-heal loop, and either passes /
+blocks / accepts an explicit user override.
+
+The skill replaces the previous advisory pair (legacy Phase 2.6 E2E testing
+and Phase 2.7 visual design review). It runs by default on every UI card,
+auto-skips on backend-only cards, and BLOCKS the commit on gating findings.
+
+#### Gate (skip the whole phase when any of the below is true)
+
+| Condition | Action |
+|-----------|--------|
+| `features.has_e2e_review: false` in `baldart.config.yml` | **SKIP** — log `"e2e-review: SKIP (feature disabled — run `npx baldart configure` to enable)"`. Preserves backwards compatibility for pre-3.18 consumers. |
+| Card has no `links.design` AND `git diff --name-only` shows no file under `${paths.app_dir}` AND no file under `${paths.components_primitives}` AND no `*.tsx` / `*.css` / `*.scss` / `*.svelte` / `*.vue` anywhere | **SKIP** — log `"e2e-review: SKIP (backend-only card)"`. |
+| Card type is `docs`, `chore`, or `config` | **SKIP** — same log. |
+
+#### Invocation contract
+
+When the gate above passes, the orchestrator invokes `/e2e-review` in
+**programmatic mode**:
+
+1. **Update tracker**: phase = "2.6-e2e-review".
+2. Spawn the skill with the payload:
+
+   ```json
+   {
+     "card_id": "<CARD-ID>",
+     "worktree_path": "<absolute worktree path>",
+     "mode": "programmatic",
+     "tolerance": "<features.e2e_review.fidelity_tolerance>",
+     "max_self_heal_iterations": "<features.e2e_review.max_self_heal_iterations>"
+   }
    ```
-4. After the test file is written, run the test in headed mode:
-   ```bash
-   npx playwright test tests/e2e/<test-file>.spec.ts --headed --reporter=list
+
+   The skill is responsible for: reading the card YAML + `test_plan`, deriving
+   routes from the diff, walking the 4-level mockup cascade (Figma MCP →
+   local image → compliance-only → skip), generating the Playwright spec via
+   `coder`, executing it headless, invoking `visual-fidelity-verifier` per
+   route, and returning a single JSON object.
+
+3. Parse the returned JSON. The contract is:
+
+   ```json
+   {
+     "status": "passed" | "blocked" | "overridden" | "skipped" | "error",
+     "iterations": 0,
+     "findings": [ ... ],
+     "ds_drift_codes": [ "DS_TOKENS_DRIFT" | "DS_COMPONENT_STALE" | "DS_INDEX_DRIFT" ],
+     "gaps": [ ... ],
+     "transcript_paths": [ ... ]
+   }
    ```
-   Note: for OTP-based tests, the test will pause at `page.pause()` for manual OTP input.
-   The user enters the OTP in the browser, then resumes (close Playwright Inspector).
-5. Report the result to the user. If tests fail, the coder agent fixes them (up to 2 retries).
-6. **Update tracker**: phase = "2.6-e2e-testing DONE", log: test file path, result (PASS/FAIL/SKIP), test count, scenarios covered (N/M from PRD plan).
-
-### Phase 2.7 — Visual Design Review (UI cards only — advisory)
-
-**Trigger**: card has `links.design` field. If absent, SKIP.
-
-Non-blocking — findings are logged but do NOT block commit.
-
-1. **Update tracker**: phase = "2.7-design-review".
-2. Extract the route from `files_likely_touched` (look for `page.tsx` under `src/app/`).
-   If no page file found, SKIP (log "no page route").
-3. Invoke the **design-review** agent (`.claude/commands/design-review.md`) on the route,
-   passing the worktree dev server port.
-4. Log findings in tracker: `design-review: [N] blockers, [M] high, [K] medium`.
-   If blockers: log in `## Issues & Flags` as `[DESIGN-ADVISORY]`.
-5. **Do NOT spawn fix agents.** Findings are informational for the user.
-6. **Update tracker**: phase = "2.7-design-review DONE".
+
+#### Gating logic (BLOCKING)
+
+| `status` from `/e2e-review` | Orchestrator action |
+|----|----|
+| `"passed"` | Log result in tracker. Proceed to Phase 3 (doc review + code review). |
+| `"skipped"` | Log skip reason. Proceed to Phase 3. |
+| `"overridden"` | Log override + reason in `## Issues & Flags` as `[E2E-OVERRIDE] <reason>`. Proceed to Phase 3. |
+| `"blocked"` | **STOP the card**. Log findings in tracker + `## Issues & Flags` as `[E2E-BLOCKED] <count> gating findings (<categories>)`. Ask the user whether to (a) override with reason, (b) escalate (open follow-up card), or (c) abandon this card and continue the batch. Do NOT proceed to Phase 3 silently. |
+| `"error"` | Log error in `## Issues & Flags`. Ask the user whether to retry, skip, or abandon. Do NOT proceed silently. |
+
+#### Re-run trigger (after Phase 3.7 `/codexreview`)
+
+If the mandatory `/codexreview` gate in Phase 3.7 modifies any file under
+`${paths.app_dir}`, `${paths.components_primitives}`, or any `*.css` /
+`*.scss`, the orchestrator MUST re-invoke `/e2e-review` BEFORE the Phase 4
+commit. This protects against code-review changes that silently reintroduce
+visual / functional drift. The re-run reuses the same
+`.baldart/e2e-review/<CARD-ID>/` state directory and starts from Phase 3
+of the skill (skipping plan extraction and mockup cascade).
+
+#### Tracker output
+
+Append to `## Current Card` and (on completion) carry into `## Completed Cards`:
+
+```
+e2e-review: <status> | iterations: <N> | findings: <X critical, Y major, Z minor> | drift: [<codes>] | tolerance: <strict|balanced|lenient>
+```
+
+#### Out of scope for this phase
+
+- Mockup re-design (the skill never modifies the mockup — only the
+  implementation).
+- Code review or doc review (those remain Phase 3 / 3.7 responsibilities).
+- Unit-test execution (that is `qa-sentinel`).
+- Visual polish beyond gating findings (advisory Minor findings under
+  balanced/lenient tolerance are logged but not actioned).
+
+#### Legacy cards
+
+Cards written before v3.18.0 (without a `test_plan` block) still work — the
+skill's Phase 1 falls back to deriving Gherkin scenarios from
+`acceptance_criteria` directly. The mockup cascade gracefully degrades when
+`links.design` is missing.
 
 ---
 

package/framework/.claude/skills/playwright-skill/SKILL.md

@@ -17,6 +17,35 @@ All browser testing uses the **Playwright Test CLI** via `playwright.config.ts`
 **Overlay:** loads `.baldart/overlays/playwright-skill.md` if present — project-specific test URLs, auth helpers, theming pairing assertions.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## MCP dependencies
+
+See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
+
+**None.** This skill uses the **Playwright Test CLI** (`@playwright/test`) directly via `npm run test:e2e` — `.spec.ts` files under `${paths.e2e_tests_dir}`. It does NOT use Playwright MCP. Consumers don't need any MCP configured to use this skill. For ad-hoc interactive browser debugging during bug investigation (not E2E test authoring) see [bug/SKILL.md](../bug/SKILL.md), which DOES require `mcp__playwright__browser_*`.
+
+## E2E Review Integration (since v3.18.0)
+
+This skill is the tooling layer consumed by `/e2e-review` Phase 3 (functional
+E2E). When the orchestrator invokes this skill, the contract is:
+
+- The `coder` agent generates the `.spec.ts` under `${paths.e2e_tests_dir}/`
+  from a Gherkin verification plan persisted at
+  `.baldart/e2e-review/<CARD-ID>/plan.json` (do not invent scenarios outside
+  the plan).
+- The spec MUST screenshot every route in scope and save the file at
+  `.baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>.png` — that path is
+  consumed verbatim by the `visual-fidelity-verifier` agent in Phase 4.
+- Execution is **headless** in programmatic mode (invocation from `/new`);
+  headed mode is reserved for OTP flows during manual `/e2e-review` runs.
+- Failed scenarios become functional findings in the aggregate report; the
+  severity is determined by the orchestrator (auth/payments/data-mutation =
+  Critical; display-only = Major; flaky-passed-on-retry = Minor).
+
+No logic of this skill changes for E2E-review consumption — the consumer
+simply requires the conventions above. See
+[`framework/.claude/skills/e2e-review/SKILL.md`](../e2e-review/SKILL.md) Phase 3
+for the full contract.
+
 ## Quick Reference
 
 | Action | Command |

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -131,6 +131,13 @@ canonical_docs:
   additional_refs:
     - "{{${paths.adrs_dir}/ADR-XXXXX.md}}"
 
+# test_plan is consumed BOTH by `/new` Phase 2.6 (legacy fallback path) AND by
+# `/e2e-review` (since v3.18.0). The /e2e-review skill maps each test_scenarios[]
+# entry into a Gherkin scenario in Phase 1 (Verification Plan Extraction).
+# When the card has `links.design`, the same scenarios additionally drive the
+# per-route visual fidelity check in Phase 4. Keep scenario.description short
+# and action-oriented (one user-facing intent per scenario) so the Gherkin
+# translation reads cleanly. See framework/.claude/skills/e2e-review/SKILL.md.
 test_plan:
   e2e_required: {{true|false}}
   e2e_rationale: "{{reason from evaluation tree}}"

package/framework/.claude/skills/webapp-testing/SKILL.md

@@ -15,6 +15,29 @@ license: Complete terms in LICENSE.txt
 
 ---
 
+## E2E Review Integration (since v3.18.0)
+
+This skill is the tooling layer consumed by `/e2e-review` in **compliance-only
+mode** (Phase 2 cascade level c) and as a fallback for runtime inspection.
+When invoked from the orchestrator:
+
+- Use the Python Playwright helpers to fetch the rendered DOM's computed
+  styles (CSS color / spacing / radius / shadow values) for the routes in
+  scope when no mockup image is available.
+- The compliance check reads `${paths.design_system}/tokens-reference.md` and
+  flags any computed value that does not match a token (the
+  `visual-fidelity-verifier` agent owns the actual cross-reference; this
+  skill only surfaces the runtime values).
+- The server lifecycle helper (`scripts/with_server.py`) MAY be used to start
+  / stop the dev server when the orchestrator runs outside a worktree that
+  already has one running.
+
+No logic of this skill changes for E2E-review consumption — see
+[`framework/.claude/skills/e2e-review/SKILL.md`](../e2e-review/SKILL.md)
+Phase 2 (compliance-only branch) for the full contract.
+
+---
+
 To test local web applications, write native Python Playwright scripts.
 
 **Helper Scripts Available**:

package/framework/AGENTS.md

@@ -16,6 +16,7 @@ This file is generic. Paths referenced as `${paths.X}` resolve from `baldart.con
 | PRD workflow, PRD sessions | `features.has_prd_workflow: true` |
 | LLM wiki overlay sync | `features.has_wiki_overlay: true` |
 | Design-system blocking reads | `features.has_design_system: true` |
+| E2E review BLOCKING gate (Phase 2.6 of `/new` invokes `/e2e-review`) | `features.has_e2e_review: true` |
 
 When a MUST rule's feature is `false` or its target file does not exist, the rule is **silent** — do not invent a workflow that isn't there. Project-specific terminology (audience segments, domain entities, brand voice) comes from `identity.audience_segments`, `agents/coding-standards.md`, and skill overlays under `.baldart/overlays/`. See `agents/project-context.md` for the full protocol.
 

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -107,7 +107,26 @@ Empty string `""` means the concept doesn't exist in your project. Skills gated
 | `prd_dir` | `docs/prd` | prd, prd-add, ui-design |
 | `references_dir` | `docs/references` | new, prd, context-primer, doc-writing-for-rag, simplify |
 | `wiki_dir` | `docs/wiki` | capture, context-primer |
-| `e2e_tests_dir` | `tests/e2e` | playwright-skill |
+| `e2e_tests_dir` | `tests/e2e` | playwright-skill, e2e-review (v3.18.0) |
+
+### 4.2.1 `e2e_review` — tuning for the BLOCKING end-to-end review gate (v3.18.0+)
+
+Only consulted when `features.has_e2e_review: true`. The block governs how the `/e2e-review` skill (auto-invoked by `/new` Phase 2.6 on UI cards) decides what blocks, how aggressively it retries, and what counts as an acceptable user override.
+
+```yaml
+e2e_review:
+  fidelity_tolerance: strict       # strict | balanced | lenient
+  max_self_heal_iterations: 2
+  pixel_diff_threshold: 0.02
+  require_override_reason: true
+```
+
+| Key | Type | Default | Effect |
+|---|---|---|---|
+| `fidelity_tolerance` | enum (`strict`/`balanced`/`lenient`) | `strict` | `strict` blocks on Critical + Major + Minor findings (Minor with `confidence: low` auto-demote to advisory to absorb font-rendering / anti-aliasing variance); `balanced` blocks on Critical + Major, Minor advisory; `lenient` blocks on Critical only. |
+| `max_self_heal_iterations` | int | `2` | After gating findings, the orchestrator re-spawns `coder` with the findings as fix instructions and re-runs functional + visual phases. Matches the existing `/new` Phase 2.5 retry policy. After exhaustion, the override path engages. |
+| `pixel_diff_threshold` | float `0.0`–`1.0` | `0.02` | When the implementation screenshot vs mockup pixel-diff is below this fraction, the orchestrator skips the Vision call for that route and treats it as a pass. Primary latency / cost saver — most routes pass pixel-diff cleanly. Set higher to skip Vision more aggressively; set to `0.0` to always invoke Vision. |
+| `require_override_reason` | bool | `true` | When self-heal exhausts iterations and the user chooses to override the gate, a written reason is mandatory. The reason is recorded both in the batch tracker's `## Issues & Flags` (as `[E2E-OVERRIDE] <reason>`) and in `.baldart/e2e-review/<CARD-ID>/report.json`. Set `false` to allow silent override (not recommended). |
 
 ### 4.3 `identity` — brand and audience facts
 

package/framework/templates/baldart.config.template.yml

@@ -145,6 +145,44 @@ features:
   # `baldart configure` installs the relevant language servers when enabled.
   has_lsp_layer: false
 
+  # End-to-end review BLOCKING gate (since v3.18.0). When true, /new Phase 2.6
+  # invokes the /e2e-review skill, which combines functional E2E (Playwright
+  # spec written by `coder`, executed via playwright-skill) with visual
+  # fidelity diff (`visual-fidelity-verifier` multimodal agent). Findings are
+  # aggregated under a severity gate (strict by default) with a bounded
+  # self-heal loop. Replaces the legacy advisory Phase 2.6 + 2.7. Requires
+  # `@playwright/test` installed and `paths.e2e_tests_dir` set. Auto-skips on
+  # backend-only cards and on cards without `links.design` when no UI files
+  # changed. See framework/.claude/skills/e2e-review/SKILL.md.
+  has_e2e_review: false
+
+# ─── E2E REVIEW ──────────────────────────────────────────────────────────
+# Tuning for the /e2e-review skill (only consulted when has_e2e_review: true).
+e2e_review:
+  # Severity floor that BLOCKS the commit.
+  #   strict   — Critical + Major + Minor block (default, recommended for
+  #              design-system-strict projects); Minor findings with
+  #              `confidence: low` auto-demote to advisory (anti font-rendering
+  #              false positive).
+  #   balanced — Critical + Major block; Minor advisory.
+  #   lenient  — Critical blocks; Major + Minor advisory.
+  fidelity_tolerance: strict
+
+  # Max self-heal iterations before falling through to the override path. The
+  # orchestrator re-spawns `coder` with the gating findings and re-runs the
+  # functional + visual phases. 2 matches the existing Phase 2.5 retry policy.
+  max_self_heal_iterations: 2
+
+  # Pre-filter pixel-diff threshold (0.0–1.0). When the implementation vs
+  # mockup pixel diff is below this value, the orchestrator skips the Vision
+  # call for that route and treats it as a pass. Primary latency / cost saver.
+  pixel_diff_threshold: 0.02
+
+  # When true, the override path (after self-heal exhaustion) requires the
+  # user to provide a written reason that is recorded in the tracker's
+  # `## Issues & Flags` and in `.baldart/e2e-review/<CARD-ID>/report.json`.
+  require_override_reason: true
+
 # ─── LSP ─────────────────────────────────────────────────────────────────
 # State of the LSP layer for this project. Populated by `baldart configure`
 # (and by `npx baldart lsp install` / the `/lsp-bootstrap` skill). Leave

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -560,6 +560,7 @@ async function interactivePrompts(merged, detected) {
     ['has_prd_workflow', 'Project uses PRD workflow (docs/prd/)?'],
     ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
     ['has_lsp_layer', 'Enable LSP symbol-search layer? (recommended for large codebases)'],
+    ['has_e2e_review', 'Enable BLOCKING end-to-end review (Phase 2.6 of /new invokes /e2e-review — functional + visual fidelity gate)?'],
   ]) {
     const [key, question] = flag;
     const currentVal = merged.features[key];
@@ -619,6 +620,62 @@ async function interactivePrompts(merged, detected) {
     merged.paths[key] = await promptForKey(`${label}`, proposed);
   }
 
+  // ---- E2E review tuning (since v3.18.0) --------------------------------
+  // Only runs when the user opted in above. Populates the e2e_review.*
+  // sub-section with the severity floor, self-heal cap, pixel pre-filter
+  // threshold, and override-reason requirement. Idempotent: re-running
+  // configure on an already-installed project re-asks each value with the
+  // current YAML value as default.
+  merged.e2e_review = merged.e2e_review || {};
+  if (merged.features.has_e2e_review === true) {
+    UI.section('E2E review tuning (/e2e-review skill — Phase 2.6 of /new)');
+    const tolDefault = merged.e2e_review.fidelity_tolerance || 'strict';
+    const tolerance = await UI.select(
+      `Severity floor that BLOCKS the commit (current: ${tolDefault})`,
+      [
+        { name: 'strict   — Critical + Major + Minor block (recommended for design-system-strict projects)', value: 'strict' },
+        { name: 'balanced — Critical + Major block; Minor advisory', value: 'balanced' },
+        { name: 'lenient  — Critical blocks; Major + Minor advisory', value: 'lenient' },
+      ]
+    );
+    merged.e2e_review.fidelity_tolerance = tolerance;
+
+    const maxIterDefault = merged.e2e_review.max_self_heal_iterations ?? 2;
+    const maxIter = await promptForKey(
+      'Max self-heal iterations before override path',
+      String(maxIterDefault)
+    );
+    merged.e2e_review.max_self_heal_iterations = Number.isFinite(Number(maxIter)) ? Number(maxIter) : 2;
+
+    const diffDefault = merged.e2e_review.pixel_diff_threshold ?? 0.02;
+    const diffThr = await promptForKey(
+      'Pixel-diff pre-filter threshold (0.0 = always invoke Vision, 1.0 = never)',
+      String(diffDefault)
+    );
+    merged.e2e_review.pixel_diff_threshold = Number.isFinite(Number(diffThr)) ? Number(diffThr) : 0.02;
+
+    const reqReasonDefault = merged.e2e_review.require_override_reason !== undefined
+      ? merged.e2e_review.require_override_reason
+      : true;
+    merged.e2e_review.require_override_reason = await promptForKey(
+      'Require a written reason when the user overrides the gate after self-heal exhaustion?',
+      reqReasonDefault,
+      'confirm'
+    );
+
+    if (!merged.paths.e2e_tests_dir) {
+      UI.info(
+        'E2E review requires `paths.e2e_tests_dir` set and `@playwright/test` installed.\n' +
+        'The path prompt above asked for the directory — confirm it exists or run `npm i -D @playwright/test` later.'
+      );
+    }
+  } else {
+    UI.info(
+      'has_e2e_review=false — /new Phase 2.6 silently skips the BLOCKING gate.\n' +
+      'Re-run `baldart configure` to enable when you want functional + visual fidelity enforced per card.'
+    );
+  }
+
   // ---- LSP layer (since v3.10.0) ----------------------------------------
   // Only runs when the user opted in above. Idempotent: re-running configure
   // on an already-installed project re-detects, asks which servers to keep,
@@ -836,6 +893,7 @@ async function configure(opts = {}) {
     `Backlog:         ${detected.features.has_backlog ? 'yes' : 'no'}`,
     `ADRs:            ${detected.features.has_adrs ? 'yes' : 'no'}`,
     `API docs:        ${detected.features.has_api_docs ? 'yes' : 'no'}`,
+    `E2E review:      ${detected.features.has_e2e_review === true ? 'yes' : detected.features.has_e2e_review === false ? 'no' : '— (will ask)'}`,
     `Charting libs:   ${detected.stack.charting.canonical.join(', ') || '—'}`,
     `Animation libs:  ${detected.stack.animation.canonical.join(', ') || '—'}`,
     `E2E framework:   ${detected.stack.testing.e2e || '—'}`,

package/src/commands/status.js

@@ -4,6 +4,19 @@ const UI = require('../utils/ui');
 const fs = require('fs');
 const path = require('path');
 
+// Lightweight semver compare. Returns positive if a > b, negative if a < b,
+// zero if equal. Treats malformed input as 0 — degrade open rather than throw.
+function cmpSemver(a, b) {
+  if (!a || !b) return 0;
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 async function status() {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
@@ -94,24 +107,43 @@ async function status() {
       }
     }
 
-    // Check for pending updates
+    // Check for pending updates (since v3.17.1 — was a no-op stub before).
     UI.newline();
     UI.section('Update Status');
 
+    let updateAvailable = false;
+    let remoteVersion = null;
     try {
       await git.fetch('antbald/BALDART');
-      UI.info('Checking for updates...');
-      // Simplified - would need more sophisticated version comparison
-      UI.success('Up to date (check with: baldart update)');
+      remoteVersion = await git.getRemoteVersion('antbald/BALDART', 'main');
+      if (!remoteVersion || remoteVersion === 'unknown') {
+        UI.warning('Could not read remote VERSION — check `baldart update` manually.');
+      } else if (cmpSemver(remoteVersion, version) > 0) {
+        updateAvailable = true;
+        UI.warning(`Update available: ${version} → ${remoteVersion}. Run: baldart update`);
+      } else if (cmpSemver(remoteVersion, version) < 0) {
+        UI.info(`Local v${version} is ahead of remote v${remoteVersion} (likely an unreleased commit).`);
+      } else {
+        UI.success(`Up to date (v${version})`);
+      }
     } catch (error) {
       UI.warning('Cannot check for updates (offline?)');
     }
 
     // Summary
     UI.newline();
+    let updateLine;
+    if (updateAvailable && remoteVersion) {
+      updateLine = `Update: ${version} → ${remoteVersion} available`;
+    } else if (remoteVersion && remoteVersion !== 'unknown') {
+      updateLine = `Update: up to date`;
+    } else {
+      updateLine = `Update: unknown (could not reach remote)`;
+    }
     UI.box('SUMMARY', [
       `Version: ${version}`,
       `Installation: ${symlinkValid ? 'Valid' : 'Issues detected'}`,
+      updateLine,
       '',
       'Commands available:',
       '  • baldart update  - Update framework',

package/src/commands/update.js

@@ -81,7 +81,10 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   if (userOwned.length > 0) {
     UI.warning(`${userOwned.length} other dirty path(s) will be left untouched (not BALDART-managed).`);
   }
-  const ok = await UI.confirm(`Commit them as \`chore(baldart): post-update reconcile to v${newVersion}\`?`, true);
+  const autoYes = options && options.yes === true;
+  const ok = autoYes
+    ? true
+    : await UI.confirm(`Commit them as \`chore(baldart): post-update reconcile to v${newVersion}\`?`, true);
   if (!ok) {
     UI.info('Auto-commit declined. Your worktree keeps the changes for manual review.');
     return;
@@ -110,6 +113,13 @@ async function update(options = {}) {
   const symlinks = new SymlinkUtils();
   const repo = 'antbald/BALDART'; // Default repo
 
+  // Non-interactive flags (since v3.17.1). `--yes` implies `--auto-stash`.
+  // When `yes` is set, every UI.confirm/UI.select downstream short-circuits
+  // to its default — the same value an unattended user would have produced.
+  const autoYes = options.yes === true;
+  const autoStash = autoYes || options.autoStash === true;
+  const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
+
   try {
     // Step 1: Verify installation
     UI.header('STEP 1/5: Verify Installation');
@@ -194,14 +204,14 @@ async function update(options = {}) {
     const diff = await git.diffWithRemote();
     if (diff) {
       UI.info('Changes detected. Review recommended.');
-      const showDiff = await UI.confirm('Show detailed diff?', false);
+      const showDiff = await confirm('Show detailed diff?', false);
 
       if (showDiff) {
         console.log(diff);
       }
     }
 
-    const proceedUpdate = await UI.confirm('Proceed with update?', true);
+    const proceedUpdate = await confirm('Proceed with update?', true);
     if (!proceedUpdate) {
       UI.info('Update cancelled');
       process.exit(0);
@@ -225,10 +235,16 @@ async function update(options = {}) {
       UI.list(unique.slice(0, 8), 'yellow');
       if (unique.length > 8) UI.info(`…and ${unique.length - 8} more.`);
 
-      const action = await UI.select('How would you like to proceed?', [
-        { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
-        { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
-      ]);
+      let action;
+      if (autoStash) {
+        UI.info('Auto-stashing dirty paths (--yes / --auto-stash).');
+        action = 'stash';
+      } else {
+        action = await UI.select('How would you like to proceed?', [
+          { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
+          { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
+        ]);
+      }
       if (action === 'abort') {
         UI.info('Aborted. Commit or `git stash -u`, then re-run `npx baldart update`.');
         process.exit(0);
@@ -361,9 +377,12 @@ async function update(options = {}) {
         'Convert legacy .claude/skills/ bulk symlink (v2.0.x) into the new per-item layout.',
         `Merge framework skills into per-tool skill dirs (${enabledTools.join(', ')}) without touching your personal skills.`
       ]);
-      const recreate = await UI.confirm('Reconcile symlinks now?', true);
+      const recreate = await confirm('Reconcile symlinks now?', true);
       if (recreate) {
-        await symlinks.createAllSymlinks({ mode: 'prompt', tools: enabledTools });
+        // In auto-yes mode pass 'force' instead of 'prompt' so per-conflict
+        // prompts inside SymlinkUtils don't reintroduce blocking I/O.
+        const mode = autoYes ? 'force' : 'prompt';
+        await symlinks.createAllSymlinks({ mode, tools: enabledTools });
       }
     } else {
       // Re-run the per-item merges for every enabled tool so newly-shipped
@@ -403,10 +422,10 @@ async function update(options = {}) {
       if (!fs.existsSync(configPath)) {
         UI.newline();
         UI.warning('No baldart.config.yml in this project — skills installed by this framework version require it.');
-        const runConfigure = await UI.confirm('Run `baldart configure` now?', true);
+        const runConfigure = await confirm('Run `baldart configure` now?', true);
         if (runConfigure) {
           const configureCmd = require('./configure');
-          await configureCmd();
+          await configureCmd(autoYes ? { nonInteractive: true } : undefined);
         }
       } else {
         // Schema migration: backfill `tools.enabled` for configs created
@@ -425,7 +444,7 @@ async function update(options = {}) {
           UI.warning('Pre-v3.7.0 config detected — `tools.enabled` is missing.');
           UI.info(`From v3.7.0, BALDART can install framework skills for multiple AI tools (Claude Code, OpenAI Codex CLI, …) from the same source.`);
           UI.info(`Autodetected on this machine: ${suggested.join(', ')}`);
-          const ok = await UI.confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
+          const ok = await confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
           if (ok) {
             cur.tools = cur.tools || {};
             cur.tools.enabled = suggested;
@@ -470,10 +489,10 @@ async function update(options = {}) {
               UI.warning(`New config keys in this version: ${allMissing.join(', ')}.`);
               // Auto-offer configure so the user actually answers, instead of
               // silently falling back to template defaults on first use.
-              const runConfigure = await UI.confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
+              const runConfigure = await confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
               if (runConfigure) {
                 const configureCmd = require('./configure');
-                await configureCmd();
+                await configureCmd(autoYes ? { nonInteractive: true } : undefined);
               } else {
                 UI.info('Skipped. Skills will prompt for the missing keys on first use.');
               }