baldart 4.0.2 → 4.0.4

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.4] - 2026-06-02
+
+**Portability fix (visual identity): genericize the last fidelity-app visual-identity flavor in doc-RAG worked examples.** Confirms the graphic dimension is clean: `Neo-Brutalism` (plus the `Press Start 2P` font and `amber accents`) appeared as bare styling labels in the `doc-writing-for-rag` before/after examples — now generalized to "the project's design system (per `identity.design_philosophy`)". No behaviour change → **PATCH**.
+
+> **Why / scope confirmation.** After this, project-specific visual identity exists in the shipped payload ONLY where it should: as a config-driven example value (`identity.design_philosophy` e.g. "Neo-Brutalism" / "Minimalist" / "Glassmorphism"), in the config documentation (`PROJECT-CONFIGURATION.md`, template comments, the contamination scanner's own meta-docs), and in the intentional `templates/overlays/*.fidelity-example.md` starter overlays (named and shipped precisely so a consumer copies/adapts/deletes them). Zero project-specific design-philosophy, chart-wrapper, font, or brand-colour literal remains baked into portable skill/agent logic. (Hard-coded `${paths.*}` literals remain a separate, larger open cleanup — see v4.0.3 note.)
+
+## [4.0.3] - 2026-06-02
+
+**Portability fix (round 3 — final): remove fidelity-app DOMAIN example-flavor from shipped framework files.** Closes the T13 portability sweep started in v4.0.1/4.0.2 by genericizing the consumer-domain vocabulary (`merchant`/`booking`/`reservation`/`merchant-theming`, `/merchant/dashboard` routes, `customer-facing vs merchant-facing`, `FEAT-0127-merchant-points-guard`, `area:customer|merchant|admin`) that survived as illustrative example flavor. No behaviour change → **PATCH**.
+
+> **Why.** Even in prose examples, a consumer-domain noun teaches the wrong vocabulary and trips the `contamination.js` `requires-decision` rules. The fix distinguishes genuine fidelity-domain flavor (generalized) from legitimate generic English (`customer` in marketing/security "multi-tenant … customers"), the scanner's own meta-references (`framework-edit-gate.js`, `contamination.js`), and `project-context.md`'s explanation that these opinionated tokens belong in the overlay — all of which are correct and untouched.
+
+### Changed — genericized domain example flavor
+
+- **Example queries/routes** → placeholders: `wiki-curator.md` / `doc-reviewer.md` search examples (`<feature-X>` / `<entity>`); `visual-fidelity-verifier.md`, `commands/design-review.md`, `e2e-review/SKILL.md` route envelopes (`/dashboard` instead of `/merchant/dashboard`); `impact-analysis.md` worked-CR endpoint.
+- **`prd.md`** — example card filename and `area:` labels reference `identity.audience_segments` instead of literal `merchant`/`customer`/`admin`.
+- **`prd-card-writer.md`** — "split by audience segment (per `identity.audience_segments`)" instead of "customer-facing vs merchant-facing"; generic subsystem example.
+- **`doc-writing-for-rag` reference files** (`before-after-examples.md`, `compact-templates.md`, `schemas-and-errors.md`) — added an "illustrative sample domain" disclaimer (the worked before/after corpus uses a sample API; only the *technique* is normative), rather than rewriting 290+ lines of self-contained illustration.
+
+> **Note — out of scope, surfaced for a future pass.** Running `contamination.js` over the whole `framework/` payload also flags ~200 hard-coded **path literals** (`backlog/`, `docs/design-system/`, `src/components/…`) that should be `${paths.*}` config keys. A meaningful fraction are legitimate (config-template defaults, `PROJECT-CONFIGURATION.md` docs, canonical protocol examples), but the rest are a genuine, larger portability cleanup deserving its own dedicated pass — not bundled here.
+
 ## [4.0.2] - 2026-06-02
 
 **Portability fix (round 2): remove hard-coded auth/deployment project identifiers from shipped framework files.** Companion to v4.0.1 — extends the de-contamination from the database dimension to the auth and deployment dimensions, where fidelity-app-specific identifiers (`withAuth`, `withAuthNoParams`, `src/lib/auth/middleware.ts`, `src/app/api/v1/...`, `BookingTable`, `ADMIN + MERCHANT`, "Vercel Functions") leaked into self-verification examples, detection-signal lists, and template fills. No behaviour change → **PATCH**.

package/VERSION

@@ -1 +1 @@
-4.0.2
+4.0.4

package/framework/.claude/agents/doc-reviewer.md

@@ -119,7 +119,7 @@ the flags above.
   `docs/ops/graph-communities-scheduling.md`:
   - `search_synthesis(question, level="global")` — community-summary
     retrieval. Use for relational / cross-cutting questions ("how does
-    auth interact with booking?", "what touches reservations?").
+    auth interact with `<feature-X>`?", "what touches `<entity>`?").
   - `search_synthesis(question, level="local")` — entity-centric retrieval
     (specific identifier lookups; equivalent to `mode="local"`).
   - `search_docs(mode="drift")` — GraphRAG DRIFT (`global` → scoped `local`),

package/framework/.claude/agents/prd-card-writer.md

@@ -211,14 +211,14 @@ Cards MUST be as atomic as possible to enable parallel execution:
 
 **Splitting heuristics:**
 - Split by concern: data model vs API vs UI vs docs
-- Split by user persona: customer-facing vs merchant-facing
+- Split by audience segment (per `identity.audience_segments`)
 - Split by module: each independent module = its own card
 - Keep tightly coupled work together (e.g., a type + its only consumer)
 
 **Anti-patterns to avoid:**
 - Monolithic "Phase 1-7" cards embedding an entire feature
 - XL cards with 15+ files — always split these
-- Cards that mix independent subsystems (e.g., booking API + promo UI)
+- Cards that mix independent subsystems (e.g., a service API + an unrelated feature's UI)
 
 ## Card Structure (MANDATORY — zero tolerance)
 

package/framework/.claude/agents/prd.md

@@ -502,7 +502,7 @@ Before creating cards, scan `backlog/*.yml` to determine the next available numb
 
 | Prefix | When to use | Example |
 |--------|-------------|---------|
-| `FEAT-NNNN-slug.yml` | Feature work | `FEAT-0127-merchant-points-guard.yml` |
+| `FEAT-NNNN-slug.yml` | Feature work | `FEAT-0127-user-rewards-guard.yml` |
 | `BUG-NNNN-slug.yml` | Bug fixes | `BUG-0071-issue-197-dashboard-bugs.yml` |
 | `UI-NNNN-slug.yml` | UI-only changes | `UI-0090-remove-install-pwa-cta.yml` |
 | `DOC-NNNN-slug.yml` | Documentation only | `DOC-0001-privacy-policy-draft.yml` |
@@ -647,7 +647,7 @@ priority: HIGH
 owner_agent: coder
 
 github_issue: NNN  # GitHub issue number
-labels: [bug, area:customer]  # area:customer | area:merchant | area:admin
+labels: [bug, area:<segment>]  # area:<segment> — values from identity.audience_segments
 
 clarity_analysis:  # MANDATORY per AGENTS.md for all bug cards
   expected_behavior: "[What should happen]"

package/framework/.claude/agents/visual-fidelity-verifier.md

@@ -52,7 +52,7 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
 ```json
 {
   "card_id": "FEAT-XXXX",
-  "route": "/merchant/dashboard",
+  "route": "/dashboard",
   "viewport": { "width": 1440, "height": 900 },
   "implementation_screenshot_path": "/abs/path/to/impl.png",
   "mockup_source": {
@@ -183,7 +183,7 @@ Inflating or suppressing severity to match the mode is a protocol violation.
 ```json
 {
   "status": "completed" | "skipped" | "error",
-  "route": "/merchant/dashboard",
+  "route": "/dashboard",
   "mockup_source_level": "figma" | "local" | "compliance-only" | "skip",
   "viewport": { "width": 1440, "height": 900 },
   "compliance_score": 0.87,

package/framework/.claude/agents/wiki-curator.md

@@ -102,9 +102,9 @@ exposed via dedicated MCP tools alongside `search_docs`:
 - `search_synthesis(question, level="global")` — community-summary retrieval.
   Use for **relational / cross-cutting** questions where the answer involves
   multiple modules at once. Examples:
-  - "How does auth interact with booking?"
-  - "What touches the reservations collection?"
-  - "Which areas share the merchant-theming pattern?"
+  - "How does auth interact with `<feature-X>`?"
+  - "What touches the `<entity>` collection/table?"
+  - "Which areas share the `<shared-pattern>` (e.g. a theming/layout) pattern?"
 - `search_synthesis(question, level="local")` — entity-centric retrieval
   (delegates to the existing `local` mode). Use for **specific lookups** —
   "what is `<authWrapper>`?", "show me the `<DomainType>` type definition".

package/framework/.claude/commands/design-review.md

@@ -11,7 +11,7 @@ This command supports two output modes, detected from the input prompt:
 
 ### Mode A — Interactive (default)
 
-When the user invokes `/design-review` directly (input is a natural-language route reference, e.g. `/design-review /merchant/dashboard`), produce the **Markdown report** described in steps 1–5 below. Use the Blockers/High/Medium/Nitpicks template from `agents/design-review.md` § Report Template.
+When the user invokes `/design-review` directly (input is a natural-language route reference, e.g. `/design-review /dashboard`), produce the **Markdown report** described in steps 1–5 below. Use the Blockers/High/Medium/Nitpicks template from `agents/design-review.md` § Report Template.
 
 ### Mode B — Programmatic (invoked by `/e2e-review`)
 
@@ -23,7 +23,7 @@ When the input contains a JSON envelope with `"mode": "programmatic"` at any pos
 {
   "mode": "programmatic",
   "card_id": "FEAT-XXXX",
-  "route": "/merchant/dashboard",
+  "route": "/dashboard",
   "viewport": { "width": 1440, "height": 900 },
   "dev_server_port": 3000,
   "registry_paths": {
@@ -46,7 +46,7 @@ When the input contains a JSON envelope with `"mode": "programmatic"` at any pos
 {
   "status": "completed" | "skipped" | "error",
   "source": "design-review",
-  "route": "/merchant/dashboard",
+  "route": "/dashboard",
   "viewport": { "width": 1440, "height": 900 },
   "findings": [
     {
@@ -110,7 +110,7 @@ When the user invokes `/design-review`, do the following (in both modes — only
    - Read `${paths.design_system}/tokens-reference.md`.
    - Read `${paths.design_system}/components/<Name>.md` for every primitive expected on the route.
    When the flag is `false`, skip the registry reads. In Mode A flag the gap in the final report and recommend `/design-system-init`. In Mode B add the gap to the `gaps[]` array of the JSON output.
-1. Start with the route or component specified (e.g., `/merchant/dashboard`) and open it in the MCP browser. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
+1. Start with the route or component specified (e.g., `/dashboard`) and open it in the MCP browser. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
 2. Follow the Quick Visual Check in `agents/design-review.md` and run Phases 0‑7 (interaction, responsiveness, polish, accessibility, robustness, code health, content/console).
 3. Capture at least one full-page screenshot at the viewport from the input (default 1440px) and note console errors. In Mode B save the screenshot at `/tmp/design-review/<route-slug>.png` and cite it in `evidence.screenshot_path`.
 4. **Mode A**: report findings using the Markdown template in `agents/design-review.md` (Blockers/High/Medium/Nitpicks). **Mode B**: assemble the JSON output described above, normalizing severity per the table.

package/framework/.claude/skills/doc-writing-for-rag/references/before-after-examples.md

@@ -1,6 +1,12 @@
 # Before/After Examples — Wave 1+2+3 Compression
 
-Casi concreti validati sul corpus reale. Per ogni esempio: prima, dopo, tecnica applicata.
+> **Illustrative sample domain.** The endpoints, routes, and entity names below
+> (booking/rooms, menu/items, reservations planner, etc.) are a SAMPLE domain used
+> only to demonstrate the doc-compaction techniques — they are not part of any
+> consumer's API. Apply the *technique* (the before→after transformation), not the
+> example's vocabulary, to your own `${paths.references_dir}` docs.
+
+Concrete cases validated on a real corpus. For each example: before, after, technique applied.
 
 ## Example 1 — API Endpoint (booking.md)
 
@@ -104,8 +110,8 @@ sidebar navigation, top bar with store switcher, and responsive container.
 **Store switching**: Supports CT-0067 multi-store. When merchant has
 multiple stores, user can switch via top bar dropdown. Current store
 persisted in sessionStorage with Safari ITP fallback.
-**Styling**: Neo-Brutalism design system (bold borders, amber accents,
-Press Start 2P titles). Follows ui-guidelines.md §3.
+**Styling**: the project's design system (per `identity.design_philosophy` —
+see `${paths.ui_guidelines}`).
 **Disabled modules**: If merchant's license doesn't include this module,
 the page is completely hidden from navigation.
 
@@ -120,7 +126,7 @@ the page is completely hidden from navigation.
 - **Auth**: merchantUserId + MERCHANT role (ADMIN via impersonation)
 - **Layout**: MerchantResponsiveLayout
 - **Store switching**: CT-0067 multi-store, sessionStorage persist
-- **Styling**: Neo-Brutalism (see ui-guidelines.md §3)
+- **Styling**: the project's design system (per `identity.design_philosophy`; see `${paths.ui_guidelines}`)
 - **License gating**: disabled modules hidden from navigation
 
 ---

package/framework/.claude/skills/doc-writing-for-rag/references/compact-templates.md

@@ -1,6 +1,11 @@
 # Compact Templates
 
-Template validati su 45 file in 3 wave di compressione. Ogni template include: before/after, line count, note critiche.
+> **Illustrative sample domain.** Endpoint paths, routes, roles, and entity names in
+> the filled examples below are a SAMPLE domain for demonstrating the template shapes —
+> substitute your project's own (auth wrapper, roles from `identity.audience_segments`,
+> routes, entities). Only the template *structure* is normative.
+
+Templates validated on 45 files across 3 compression waves. Each template includes: before/after, line count, critical notes.
 
 ## API Endpoint Template
 
@@ -131,7 +136,7 @@ last_updated: 2026-04-05
 - **Auth**: merchantUserId + MERCHANT role
 - **Layout**: MerchantResponsiveLayout
 - **Store switching**: CT-0067 multi-store support
-- **Styling**: Neo-Brutalism design system
+- **Styling**: the project's design system (per `identity.design_philosophy`)
 - **Hidden modules**: disabled via license gating
 
 ## License Gating System (FEAT-0128)

package/framework/.claude/skills/doc-writing-for-rag/references/schemas-and-errors.md

@@ -1,6 +1,10 @@
 # Schemas & Errors — Central Reference Files
 
-Protocollo per usare e estendere `${paths.api_schemas}` e `${paths.api_errors}` (typically `docs/references/api/schemas.md` and `docs/references/errors.md`).
+> **Illustrative sample domain.** Error codes, routes, and entity names in the
+> examples below are a SAMPLE domain — substitute your own. Only the protocol
+> (central schema/error files, anchor cross-referencing) is normative.
+
+Protocol for using and extending `${paths.api_schemas}` and `${paths.api_errors}` (typically `docs/references/api/schemas.md` and `docs/references/errors.md`).
 
 > **Note**: the schema names and domain sections below come from a real project (a multi-merchant fidelity/loyalty platform) and are kept as a concrete example. Replace them with your own domain entities when applying this skill to a new project — the project-specific domain vocabulary lives in `.baldart/overlays/doc-writing-for-rag.md`.
 

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -154,7 +154,7 @@ system constraints into a machine-readable verification plan.
    {
      "card_id": "FEAT-XXXX",
      "title": "...",
-     "routes": ["/merchant/dashboard", "/merchant/dashboard/edit"],
+     "routes": ["/dashboard", "/dashboard/edit"],
      "personas": [{"name": "merchant", "auth": "password", "creds": {...}}],
      "data_prerequisites": ["seed merchant 'demo'", "create one paid booking"],
      "scenarios": [
@@ -162,11 +162,11 @@ system constraints into a machine-readable verification plan.
          "id": "AC-1",
          "name": "Merchant can update store hours",
          "gherkin": "Feature: ...",
-         "routes_touched": ["/merchant/settings/hours"]
+         "routes_touched": ["/settings/hours"]
        }
      ],
      "non_functional_checks": ["loads in < 2s on slow 3G"],
-     "mockup_refs": [{"route": "/merchant/dashboard", "level": "local", "path": "mockups/dashboard.png"}]
+     "mockup_refs": [{"route": "/dashboard", "level": "local", "path": "mockups/dashboard.png"}]
    }
    ```
 
@@ -336,7 +336,7 @@ For each `route` in `plan.routes[]`:
      Input payload:
      {
        "card_id": "FEAT-XXXX",
-       "route": "/merchant/dashboard",
+       "route": "/dashboard",
        "viewport": { "width": 1440, "height": 900 },
        "implementation_screenshot_path": ".baldart/e2e-review/FEAT-XXXX/screenshots/merchant-dashboard.png",
        "mockup_source": { ... },

package/framework/.claude/skills/prd/references/impact-analysis.md

@@ -248,7 +248,7 @@ touchpoints into the existing ISA table; assign new ISA-N IDs.
 
 ## Worked Example
 
-**CR: "Add POST /api/v1/merchant/reservations/bulk-confirm for batch confirmation"**
+**CR: "Add POST /api/v1/reservations/bulk-confirm for batch confirmation"**
 
 Change type: Addition (new endpoint)
 

package/package.json

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