baldart 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.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**.
+
+> **Why.** A project-specific symbol baked into a shipped detection list or CoVe example is the same frozen-spot defect as a hard-coded datastore: the consumer's auth wrapper, role names, and deploy platform are `stack.*` / overlay facts. Genuinely platform-named integrations were left untouched because they are correct: the `vercel:deploy` skill documentation (that skill *is* Vercel-specific), the multi-platform deploy tables in `/new` ("firebase: … vercel: … aws: …"), the per-platform timeout/limit tables in `api-perf-gate.md`, and the config-driven `stack_signature` example in `research-phase.md` (which already shows both a Firestore and a Supabase example).
+
+### Changed — generalized auth/deployment identifiers to placeholders / config keys
+
+- **`code-reviewer.md`** + **`plan-auditor.md`** — the chain-of-verification example findings now use `<auth-wrapper>` / `<route-file>` / `<auth-module>` placeholders (resolved from `${paths.high_risk_modules}`) instead of `withAuth` + literal `src/app/api/v1/...` / `src/lib/auth/middleware.ts` paths.
+- **`audit-phase.md`** — the auth-change detection signal cites "the project's auth-guard wrapper / permission helper (e.g. a `withAuth*`-style wrapper)" rather than the literal `withAuth` / `checkPermission` symbols.
+- **`doc-writing-for-rag`** (SKILL + `compact-templates.md`) — endpoint template fills use `<authWrapper>` / `<ROLE_A>` / `<ROLE_B>` instead of `withAuthNoParams` / `ADMIN + MERCHANT`.
+- **`api-perf-gate.md`** — the upload red-flag cites "the platform's request-body limit (e.g. 4.5MB on Vercel Functions — per `stack.deployment`)".
+- **`validation-phase.md`** — the logic-marker grep list covers datastore-access patterns per `stack.database` (not only `prisma` / `firestore.collection`).
+- **`wiki-curator.md`**, **`doc-reviewer.md`** — illustrative example queries/paths use `<authWrapper>` / `<DomainType>` / `src/lib/<module>.ts#<symbol>` placeholders.
+
 ## [4.0.1] - 2026-06-02
 
 **Portability fix: remove hard-coded `Firestore` assumptions from shipped framework files (T13 follow-up).** The v4.0.0 portability pass guarded most stack-specific checks behind `stack.database`, but a residual set of agent checklists and methodology blocks still *assumed* Firestore as the datastore — contamination that is dead-false (or misleading) on any non-Firestore consumer. No behaviour change for correctly-configured projects → **PATCH**.

package/VERSION

@@ -1 +1 @@
-4.0.1
+4.0.2

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

@@ -266,10 +266,10 @@ Emit findings of type `simulation_failure` with the file:line of the breaking br
 
 After Challenge Pass + Diff Simulation, for EACH surviving HIGH/MEDIUM finding generate 2–3 verification questions and execute them via grep/read:
 
-Example finding: "withAuth missing on POST handler at `src/app/api/v1/foo/route.ts:45`":
-1. `Does the file exist?` → `test -f src/app/api/v1/foo/route.ts`
-2. `Is there really no withAuth import or wrapper?` → `grep -n "withAuth" src/app/api/v1/foo/route.ts`
-3. `Is the route actually public per docs?` → `grep -l "api/v1/foo" docs/references/api/`
+Example finding: "auth wrapper missing on POST handler at `<route-file>:45`" (here `<auth-wrapper>` is the project's auth guard — e.g. a `withAuth*`-style wrapper; resolve from `${paths.high_risk_modules}`):
+1. `Does the file exist?` → `test -f <route-file>`
+2. `Is there really no auth import or wrapper?` → `grep -n "<auth-wrapper>" <route-file>`
+3. `Is the route actually public per docs?` → `grep -l "<route-path>" ${paths.references_dir}/api/`
 
 Drop findings whose verification fails. Record dropped findings under "Hallucinated findings dropped (CoVe)".
 

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

@@ -393,7 +393,7 @@ function whose **identity** matters to the doc's correctness — you SHOULD add
 a `code_refs:` entry to the doc's frontmatter that anchors the prose to a
 compiler-stable SCIP symbol ID.
 
-**Why**: prose paths like `src/lib/auth/middleware.ts#withAuth` rot silently
+**Why**: prose paths like `src/lib/<module>.ts#<symbol>` rot silently
 on rename. SCIP (Sourcegraph Code Intelligence Protocol) emits refactor-stable
 symbol IDs that survive moves and renames as long as the index is rebuilt.
 Research on LLM-driven doc-code traceability using SCIP-style anchors reports

package/framework/.claude/agents/plan-auditor.md

@@ -306,9 +306,9 @@ Emit findings of type `simulation_failure` with the failing step number and the
 
 After Challenge Pass and Simulation Pass, for EACH surviving HIGH/MEDIUM finding, generate 2–3 verification questions and execute them:
 
-For example, finding "Card lists `src/lib/auth/middleware.ts:45` but the function `withAuth` is at line 67":
-1. `Does the file exist?` → `test -f src/lib/auth/middleware.ts`
-2. `Is the function at line 45?` → `grep -n "function withAuth" src/lib/auth/middleware.ts`
+For example, finding "Card lists `<auth-module>:45` but the function `<auth-wrapper>` is at line 67" (where `<auth-module>` / `<auth-wrapper>` are the project's auth guard, resolved from `${paths.high_risk_modules}`):
+1. `Does the file exist?` → `test -f <auth-module>`
+2. `Is the function at line 45?` → `grep -n "function <auth-wrapper>" <auth-module>`
 3. `Does the proposed signature match?` → read 5 lines around the actual location
 
 Drop findings whose verification fails (i.e. the finding itself was wrong). Record them under "Hallucinated findings dropped (CoVe)".

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

@@ -107,7 +107,7 @@ exposed via dedicated MCP tools alongside `search_docs`:
   - "Which areas share the merchant-theming pattern?"
 - `search_synthesis(question, level="local")` — entity-centric retrieval
   (delegates to the existing `local` mode). Use for **specific lookups** —
-  "what is `withAuth`?", "show me the BookingTable type definition".
+  "what is `<authWrapper>`?", "show me the `<DomainType>` type definition".
 - `search_docs(query, mode="drift")` (or the dedicated `search_drift` tool) —
   the GraphRAG DRIFT pattern: first pick candidate communities via `global`,
   then run a scoped `local` retrieval for each. Use when a question is both

package/framework/.claude/skills/doc-writing-for-rag/SKILL.md

@@ -48,7 +48,7 @@ Do NOT load for:
    ```markdown
    ### POST /api/v1/domain/resource
 
-   **Auth**: withAuthNoParams  |  **Access**: ADMIN + MERCHANT
+   **Auth**: `<authWrapper>`  |  **Access**: `<ROLE_A>` + `<ROLE_B>`
 
    **Body**:
    | Field | Type | Required | Desc |

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

@@ -9,7 +9,7 @@ Template validati su 45 file in 3 wave di compressione. Ogni template include: b
 ```markdown
 ### POST /api/v1/domain/resource
 
-**Auth**: withAuthNoParams  |  **Access**: ADMIN + MERCHANT
+**Auth**: `<authWrapper>`  |  **Access**: `<ROLE_A>` + `<ROLE_B>`
 
 **Body**:
 | Field | Type | Required | Desc |

package/framework/.claude/skills/prd/references/api-perf-gate.md

@@ -70,7 +70,7 @@ Scan the PRD text for these keywords. Each match = a finding.
 | "global counter" / "total X" / "increment count" / "contatore" | Transaction hotspot (serializes writers) | HIGH |
 | "no limit" / "unlimited" / "senza limiti" / "illimitato" | Unbounded data growth | HIGH |
 | "save all in document" / "embed list" / "array nel documento" | Unbounded array in doc (max 1MB, degrades at 40K) | HIGH |
-| "upload file/image via API" / "carica file" | 4.5MB payload limit on Vercel Functions | HIGH |
+| "upload file/image via API" / "carica file" | the platform's request-body limit (e.g. 4.5MB on Vercel Functions — per `stack.deployment`) | HIGH |
 | "search by name" / "full-text search" / "cerca per nome" | Many DBs need a dedicated search index (Algolia/Typesense/Postgres FTS/Mongo Atlas Search) — DB-specific | HIGH |
 | "page N" / "skip" / "offset" / "pagina N" | Offset pagination is inefficient in most DBs (Firestore charges for skipped docs; SQL scans them) | MEDIUM |
 | "send email/SMS" in request path / "invia email/SMS" | Blocking I/O in request path (use waitUntil / background job) | MEDIUM |

package/framework/.claude/skills/prd/references/audit-phase.md

@@ -23,7 +23,7 @@ Scan each card for security signals to decide whether the `security-reviewer` ag
 | Signal | Where to look |
 |--------|---------------|
 | **New or modified API route** | `files_likely_touched` contains `route.ts`, `api/`, or requirements mention new endpoints |
-| **Authentication/authorization changes** | Requirements/files mention `withAuth`, `checkPermission`, `permissions`, login, session, token, JWT, OAuth |
+| **Authentication/authorization changes** | Requirements/files mention the project's auth-guard wrapper or permission helper (e.g. a `withAuth*`-style wrapper / `checkPermission`-style guard — resolve from `${paths.high_risk_modules}`), or generic markers: `permissions`, login, session, token, JWT, OAuth |
 | **Persistence-layer access rules** | `files_likely_touched` contains rule/policy files matching `stack.database` (e.g. `firestore.rules`, Supabase RLS migration, MongoDB validator) or requirements mention rule changes |
 | **External integrations** | Requirements mention webhooks, third-party APIs, payment, SMS, email providers, or external callbacks |
 | **File upload or media handling** | Requirements mention upload, image, file, media, or `files_likely_touched` contains upload/media paths |

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -18,7 +18,7 @@ Mark task 5 as `in_progress`.
 
    b. **UI-only scope heuristic (WARN — soft gate, not blocking)** — for each card with `owner_agent: ui-expert`:
       - Concatenate `scope.summary`, `requirements[]`, and `acceptance_criteria[]` into one lowercase string.
-      - Grep for logic-marker substrings: `api call`, `endpoint`, `route handler`, `state machine`, `validation logic`, `business rule`, `database`, `migration`, `prisma`, `firestore.collection`, `auth flow`, `token storage`, `webhook`, `cron`.
+      - Grep for logic-marker substrings: `api call`, `endpoint`, `route handler`, `state machine`, `validation logic`, `business rule`, `database`, `migration`, and datastore-access patterns per `stack.database` (e.g. `prisma`, `.from(` / SQL client, `firestore.collection`, `db.collection`), `auth flow`, `token storage`, `webhook`, `cron`.
       - For each marker hit, log a WARN line in the audit output:
         `"[UI-SCOPE-WARN] Card <ID> (ui-expert) mentions '<marker>' — review whether logic belongs in a sibling coder card. See backlog-phase.md § Rule B."`
       - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.

package/package.json

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