baldart 4.92.1 → 4.94.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.94.0] - 2026-07-02
+
+**Analysis profiles — `codebase-architect` specializzato per-tipo-di-analisi, un solo agente, un solo SSOT.** L'assessment dei ~50 callsite reali ha mostrato che "capire il codebase" copre 6 lavori diversi (grounding pre-implementazione, tracing di un bug, blast-radius, contesto di planning, inventario UI/design-system, baseline di review) serviti da UN prompt monolitico (~455 righe caricate a ogni spawn) con la conoscenza di specializzazione dispersa nei prompt dei chiamanti (dual-SSOT: il template di `context-primer` ri-dichiarava la search strategy dell'agente). Fix architetturale, stesso meccanismo di `OUTPUT=terse`:
+
+- **Nuovo modulo SSOT [`framework/agents/analysis-profiles.md`](framework/agents/analysis-profiles.md)** — il gemello retrieval-side di `effort-protocol` + `return-contract-protocol`: contratto del token `PROFILE=<feature|bug|impact|discovery|ui|baseline>`, piano di retrieval + skip-list + budget + output-block per profilo, inference deterministica quando il token manca (fallback `full` = comportamento legacy), tabella di routing normativa per i chiamanti, shared block (Reuse Analysis · UI Resolution Path · Documentation Reliability Scan) estratti dal corpo agente.
+- **`codebase-architect` slim + dispatcher**: nuova sezione "Analysis Profile Dispatch" (parse token → Grep `### PROFILE: <x>` → Read SOLO quella sezione); Reuse Analysis / cascade UI / Reliability Scan spostati nel modulo (il corpo tiene l'engine: router canonico, tier strutturale, read-size, Hot-File Map v4.91.0, memoria); dedup della sezione "Your Approach". Il boundary multimodale è ESPLICITO: pixel/mockup/screenshot → `ui-expert` read-only (precedente `/prd` 1.6.5), mai l'architect.
+- **Chiamanti migrati al token deterministico** (mai lasciato all'inferenza dell'agente): `/new` implement.md step 3 + `new2.js` B7 → `ui` se la card ha mockup (stesso bit `hasMockup` del routing build v4.89.0) else `feature`; `new-final-review.js`/`new-card-review.js`/`/codexreview` → `baseline`; `plan-auditor` FULL → `impact`; `/prd` discovery-loop → `discovery`, ISA → `impact`; `/prd-add` PATCH → `impact`; `/bug` → `bug`; `/ui-design`/`/ds-handoff` → `ui`; `/e2e-review` reverse-lookup → `impact`; `context-primer` 1.1.0 mappa i task-type sui profili e il suo template smette di ri-dichiarare la strategia (dual-SSOT chiuso).
+- **Primitivi root aggiornati**: skeleton `AGENTS.md` 1.4.0 (il MUST understand-before-implement nomina i 6 profili e cita il modulo) + `CLAUDE.md` 1.2.0 (Plan Mode passa il token, cita senza ripetere).
+- **Tripwire CI**: nuova regola `analysis-profile contract` in `scripts/check-new-parity.mjs` (modulo + dispatcher + implement.md ↔ new2.js ↔ review workflow ↔ context-primer come obbligazioni a locazione parallela).
+- Routing aggiornato: `REGISTRY.md` (riga architect + decision tree), `agents/index.md` (regola + manifest), `skills-mapping.md` (context-primer = canale, non metodologia). Skill bumped: new 1.4.0, new2 1.3.0, prd 1.3.0, prd-add 1.1.0, bug 1.1.0, ui-design 1.1.0, ds-handoff 1.2.0, e2e-review 1.3.0, context-primer 1.1.0.
+
+**MINOR** — nuova capability su agent/skill/protocol condivisi; nessun cambio di layout install. **No new `baldart.config.yml` key** (i profili gate-ano su flag esistenti) → la schema-change propagation rule NON si applica. **Codex parity: portable** (token prompt-level; il modulo viaggia nel payload `agents/` bulk-symlinkato letto da entrambi i runtime; il corpo agente transpila in TOML invariato).
+
+## [4.93.0] - 2026-07-02
+
+**`/prd` gate-hygiene wave — dai driver misurati (forensics di una sessione reale: 61.6M token, 48% del costo in fasi meccaniche, una famiglia di card con zero audit-trail, 96% del wall-clock in attesa umana).** Sette interventi chirurgici, nessuna nuova chiave di config:
+
+- **Tool di misura onesto**: `scripts/new-session-audit.mjs` deduplica l'usage per `message.id` (sovracontava ~2.85× — 175M riportati vs 61.6M reali su FEAT-0061) e riconosce le sessioni `/prd` (`mode=prd`, anche quando la skill è invocata via Skill tool dopo un preambolo; backtrack `self`; confronto col reference FEAT-0041 saltato).
+- **Severità assoluta evidence-anchored** (`prd` skill 1.2.0 + `plan-auditor`): via la quota posizionale "top 20% → HIGH must-apply" — fabbricava cicli di apply su piani puliti e demotava finding reali sui batch grandi. Zero-finding è un esito legittimo.
+- **Validation eseguita, non recitata**: `validate-card-baseline.js --prd` (requirements condizionale PO1, epic `skip`, marker `[NEEDS CLARIFICATION]` bloccanti) + nuovo `framework/scripts/stamp-holistic-audit.js` (stamp `metadata.holistic_audit` deterministico, idempotente; chiamato da 6.9.4 e dal backstop 5b — i due gate-prosa che erano falliti insieme su FEAT-0064).
+- **Context economy dell'orchestratore /prd**: contratto teammate audit estratto in `references/audit-teammate-prompt.md` e passato BY PATH (mai caricato dall'orchestratore; ~−9KB da audit-phase + regola generale per gli spec agent-facing incl. `api-perf-gate.md`); analisi mockup su file delegata a `ui-expert` read-only (misurati ~208KB di mockup in cache per ~300 eventi); Progress Bar solo ai phase-gate con riga compatta intra-fase (~20 righe × 30+ messaggi risparmiate; unifica la policy Codex già esistente).
+
+**MINOR** — capability change su skill/agent/script condivisi; nessun cambio di layout install. **No new `baldart.config.yml` key** → la schema-change propagation rule NON si applica. **Codex parity: portable** (script node zero-dep; prosa skill condivisa ai due runtime; il branch file-backed Codex del teammate contract è documentato in-file).
+
 ## [4.92.1] - 2026-07-02
 
 **Review avversariale post-release del motore new2 (coerenza interna).** Tre reviewer indipendenti a contesto fresco (dataflow / edge-case / contratti) sull'onda v4.90–4.92; ogni finding ri-verificato contro il codice prima di agire: **11 confermati e fixati, 9 refutati con evidenza empirica** (tra i refutati: la "race" del worker-pool adattivo — simulata: 0 buchi; `verify-item.sh` su bash 3.2 reale — funziona; `parseInt` con CRLF; un CAP attribuito a `new2.js` che non esiste).

package/VERSION

@@ -1 +1 @@
-4.92.1
+4.94.0

package/framework/.claude/agents/REGISTRY.md

@@ -14,7 +14,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
 |-------|----------|-------------|----------------|---------------|-----------|
-| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`), code-graph structural queries (when `features.has_code_graph: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition, Graphify query/path/affected |
+| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes — callers pass `PROFILE=<feature\|bug\|impact\|discovery\|ui\|baseline>` per `agents/analysis-profiles.md` to scope the investigation | Profile-scoped platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`), code-graph structural queries (when `features.has_code_graph: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition, Graphify query/path/affected |
 | **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
 | **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `${paths.wiki_dir}/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis candidates (from ADRs/PRDs + Graphify GRAPH_REPORT.md when `features.has_code_graph: true`), provenance hygiene, freshness, anchor + frontmatter validation | Yes | `${paths.wiki_dir}/`, wiki lint |
@@ -97,7 +97,7 @@ The `depends_on` gate keys off `DONE`. `/new` sets `IN_PROGRESS` on claim and
 scan should match "not DONE", not a hard-coded `READY`).
 
 ```
-Need to understand existing code?      --> codebase-architect (MANDATORY)
+Need to understand existing code?      --> codebase-architect (MANDATORY — pass PROFILE=<feature|bug|impact|discovery|ui|baseline>, agents/analysis-profiles.md)
 Have a plan to review?                 --> plan-auditor
 Writing/modifying code?                --> coder
 Code done, need review?                --> code-reviewer

package/framework/.claude/agents/api-perf-cost-auditor.md

@@ -320,7 +320,7 @@ Already in the suppressed-findings collapsible block in § Detected Issues.
 ## Repo Expectations
 
 - Respect `AGENTS.md` authority.
-- Use `codebase-architect` when current architecture is not yet clear.
+- Use `codebase-architect` (`PROFILE=feature` — `agents/analysis-profiles.md`) when current architecture is not yet clear.
 - API contract changes → note required `/api/v2/` versioning + RFC 8594 deprecation headers.
 - Architecture policy changes → call out ADR requirements explicitly.
 - Multi-attribute index needed → flag the missing entry in the project's index

package/framework/.claude/agents/codebase-architect.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-architect
-description: "MANDATORY: Use this agent whenever you need to understand codebase structure, existing patterns, or architecture before planning or implementing changes. Per AGENTS.md, you MUST invoke this agent before proceeding with any planning or implementation work. Examples:\\n\\n<example>\\nContext: Agent needs to plan a new feature but must understand existing code first.\\nuser: \"Add a new customer analytics dashboard\"\\nassistant: \"Before planning this feature, I must invoke the codebase-architect agent to understand the existing dashboard patterns, data flow architecture, and component structure.\"\\n<commentary>\\nPer AGENTS.md MUST rule: invoke codebase-architect before planning. This is mandatory, not optional.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User needs to understand how a specific feature works.\\nuser: \"How does the permission system work in this codebase?\"\\nassistant: \"I'm going to use the Task tool to launch the codebase-architect agent to provide a comprehensive explanation of the permission system.\"\\n<commentary>\\nThe user is asking about platform architecture and logic - this requires the codebase-architect agent's deep understanding of the system.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User is planning a new feature and needs to understand existing patterns.\\nuser: \"I want to add a new API endpoint for customer analytics. What's the best approach given our current architecture?\"\\nassistant: \"I'm going to use the Task tool to launch the codebase-architect agent to analyze the current API patterns and provide architectural guidance.\"\\n<commentary>\\nThis requires understanding of existing patterns, architectural decisions, and best practices - perfect for the codebase-architect agent.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User encounters complex code and needs explanation.\\nuser: \"I found this payment processing logic but I'm not sure how it integrates with the OCR system\"\\nassistant: \"I'm going to use the Task tool to launch the codebase-architect agent to explain the integration between payment processing and OCR.\"\\n<commentary>\\nThis requires deep understanding of multiple system components and their interactions - use the codebase-architect agent.\\n</commentary>\\n</example>"
+description: "MANDATORY: Use this agent whenever you need to understand codebase structure, existing patterns, or architecture before planning or implementing changes. Per AGENTS.md, you MUST invoke this agent before proceeding with any planning or implementation work. Callers SHOULD pass an analysis profile token — PROFILE=<feature|bug|impact|discovery|ui|baseline> per agents/analysis-profiles.md — to scope the investigation deterministically. Examples:\\n\\n<example>\\nContext: Agent needs to plan a new feature but must understand existing code first.\\nuser: \"Add a new customer analytics dashboard\"\\nassistant: \"Before planning this feature, I must invoke the codebase-architect agent to understand the existing dashboard patterns, data flow architecture, and component structure.\"\\n<commentary>\\nPer AGENTS.md MUST rule: invoke codebase-architect before planning. This is mandatory, not optional.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User needs to understand how a specific feature works.\\nuser: \"How does the permission system work in this codebase?\"\\nassistant: \"I'm going to use the Task tool to launch the codebase-architect agent to provide a comprehensive explanation of the permission system.\"\\n<commentary>\\nThe user is asking about platform architecture and logic - this requires the codebase-architect agent's deep understanding of the system.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User is planning a new feature and needs to understand existing patterns.\\nuser: \"I want to add a new API endpoint for customer analytics. What's the best approach given our current architecture?\"\\nassistant: \"I'm going to use the Task tool to launch the codebase-architect agent to analyze the current API patterns and provide architectural guidance.\"\\n<commentary>\\nThis requires understanding of existing patterns, architectural decisions, and best practices - perfect for the codebase-architect agent.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User encounters complex code and needs explanation.\\nuser: \"I found this payment processing logic but I'm not sure how it integrates with the OCR system\"\\nassistant: \"I'm going to use the Task tool to launch the codebase-architect agent to explain the integration between payment processing and OCR.\"\\n<commentary>\\nThis requires deep understanding of multiple system components and their interactions - use the codebase-architect agent.\\n</commentary>\\n</example>"
 model: sonnet
 color: green
 memory: project
@@ -17,6 +17,26 @@ You are a Senior Full-Stack Architect with extensive experience in platform anal
 
 Per the project's AGENTS.md MUST rules, all agents must invoke you (codebase-architect) to understand codebase structure, existing patterns, or architecture before planning or implementing changes — they must not proceed without that analysis. (The frontmatter `description` examples above are the router-facing restatement of this same rule; this body block is the operative mandate.)
 
+## Analysis Profile Dispatch (MUST — your FIRST action)
+
+"Understand the codebase" is not one job. Before investigating, resolve your **analysis
+profile** — it scopes which protocols run, what you read/skip, your token budget, and the
+output blocks you owe the caller. The SSOT is `agents/analysis-profiles.md`:
+
+1. **Parse the token**: the invoking prompt carries
+   `PROFILE=<feature|bug|impact|discovery|ui|baseline>` (same prompt-token style as
+   `OUTPUT=terse`).
+2. **Read ONLY your section**: Grep `agents/analysis-profiles.md` for
+   `### PROFILE: <name>`, Read that section plus any `§ Shared block` it cites
+   (Reuse Analysis · UI Resolution Path · Documentation Reliability Scan live there).
+   Never read the module end-to-end.
+3. **No token** → apply the module's § 1 deterministic inference order; no match →
+   `full` (run everything that applies, budget ≤ 20K).
+
+A profile scopes your work; it never overrides the Role boundary above or the Return
+Contract below. An explicit instruction in the invoking prompt (budget, extra output
+field, output envelope) wins over the profile default.
+
 **Your Core Responsibilities:**
 
 1. **Codebase Navigation & Understanding**: Analyze and explain the platform's structure, patterns, and implementation details. Navigate complex codebases efficiently and identify key components, dependencies, and relationships.
@@ -76,23 +96,11 @@ When analyzing a feature, resolve documentation authority in this order:
 6. `${paths.wiki_dir}/` derived pages when the question is about synthesis, recurring
    documentation questions, or dashboard-style summaries
 
-**UI / design-system questions** follow a parallel resolution path (paths are
-project-specific; the convention below is recommended):
-
-1. `${paths.design_system}/INDEX.md` — thin router (name → source → purpose → spec)
-2. `${paths.design_system}/components/<Name>.md` — read the **frontmatter HEAD**
-   first (props/variants/composes/token_bindings/a11y — schema in
-   `framework/agents/component-manifest-schema.md`); the prose body only if you
-   must understand rationale. This is the on-demand discovery fast path — never
-   read the source to learn a primitive's API when its HEAD has it.
-3. `${paths.design_tokens}` (DTCG `.tokens.json`) — token SSOT; `tokens-reference.md` is a generated view
-4. `${paths.design_system}/patterns/*` — theming, overlays, animations, platform quirks
-5. `${paths.references_dir}/ui-guidelines.md` — brand philosophy and aesthetic rules
-6. `${paths.references_dir}/component-registry.md` — inventory of shared components
-
-When a query concerns UI, styling, tokens, or shared components, resolve through the
-design-system path in addition to the main path. Adapt the paths to your project's
-documentation layout.
+**UI / design-system questions** resolve through the design-system cascade —
+`agents/analysis-profiles.md` § "Shared block: UI Resolution Path" (INDEX.md thin
+router → component spec frontmatter HEAD → DTCG tokens → patterns → guidelines).
+Profile `ui` makes it the PRIMARY route; any other profile applies it in addition to
+the main path when the query concerns UI, styling, tokens, or shared components.
 
 ### Source Taxonomy
 
@@ -114,40 +122,20 @@ Treat these as weak evidence and say so explicitly in your output:
 - index docs presented as canonicals when linked PRD/ADR/reference docs exist
 - derived docs that appear newer than the supposed canonical source
 
-### Documentation Reliability Scan (MUST)
-
-When documentation is part of your evidence set, run a fast reliability scan before
-trusting it as authoritative:
+### Documentation Reliability Scan (profile-gated)
 
-1. **Registry coverage** — confirm the feature exists in
-   `${paths.references_dir}/ssot-registry.md`; if the feature only exists in backlog/PRD, report
-   `REGISTRY_GAP`
-2. **Freshness markers** — compare `Last updated`, `Last reviewed`, or explicit change-log
-   markers against `git log -1` on the shared hub or canonical doc you rely on
-3. **Link quality** — distinguish markdown links from raw repo paths; path-heavy PRDs and
-   weak pointer blocks lower retrieval quality for agents
-4. **Retrieval risk** — if a doc exceeds repo thresholds from `AGENTS.md` (for example:
-   reference docs >400 lines, API docs >800 lines, PRDs/specs >800 lines), read headings
-   and targeted sections first instead of defaulting to a full read
-5. **Router fit** — when `ssot-registry.md` maps the feature to a canonical doc, prefer
-   that route over ad hoc broad scans
-
-Include this block in every analysis that materially depends on docs:
-
-```markdown
-## Documentation Reliability Scan
-
-- Registry coverage: [ok | REGISTRY_GAP: ...]
-- Freshness status: [fresh | stale | unknown] (git evidence)
-- Link quality: [ok | PATH_HEAVY: ...]
-- Retrieval risk: [ok | OVERSIZE_DOC: ...]
-- Router fit: [ok | WEAK_ROUTER_MATCH: ...]
-```
+When your profile lists it AND documentation is part of your evidence set, run the fast
+reliability scan defined in `agents/analysis-profiles.md` § "Shared block: Documentation
+Reliability Scan" (registry coverage · freshness · link quality · retrieval risk ·
+router fit) and emit its `## Documentation Reliability Scan` block in every analysis
+that materially depends on docs.
 
 **Investigation Protocol (MUST follow before any analysis):**
 
 Before providing any architectural guidance or implementation advice, follow this
-**token-efficient** investigation sequence. Target: **under 20K tokens total**.
+**token-efficient** investigation sequence — it is the shared engine every analysis
+profile scopes (your profile says which steps get emphasis and what to skip).
+Target: **your profile's budget** (default under 20K tokens total).
 
 1. **Canonical router FIRST** — resolve the feature to its canonical source
    before reading code. Read `${paths.references_dir}/ssot-registry.md` (and the
@@ -220,48 +208,16 @@ Derived wiki overlay routing:
 - Never treat `${paths.wiki_dir}/` as canonical when a repo doc or ADR exists.
 - If the wiki and canonical docs disagree, report the drift explicitly.
 
-## Reuse Analysis Protocol (CONDITIONAL)
+## Reuse Analysis Protocol (profile-gated)
 
-Run this protocol **only when the task involves building or changing code** (new-feature,
-refactor, bug-fix). **Skip entirely for query and doc-update tasks** — they don't need
-component discovery.
+Run the Reuse Analysis **only when your profile lists it** (`feature`, `ui`, and `full`
+when the task builds or changes code). Steps, classification vocabulary (Direct reuse /
+Refactor & reuse / Extract & share / No match), and the `## Reuse Analysis` output
+format are defined ONCE in `agents/analysis-profiles.md` § "Shared block: Reuse
+Analysis" — follow it verbatim; if nothing is reusable, emit the section saying so and
+why.
 
-**Steps:**
-
-1. **Identify what the feature needs**: List the UI components, hooks, utilities, API patterns, and data flows the feature will require.
-2. **Search for existing matches**:
-   - When `features.has_design_system: true`, the **fastest reuse signal is the
-     spec HEADs**: scan `${paths.design_system}/INDEX.md` (thin router) then the
-     frontmatter HEAD of the candidate `components/<Name>.md` — structured
-     props/variants/purpose without reading source. Prefer this over Grep.
-   - Else check `${paths.references_dir}/component-registry.md` (relevant table
-     section only).
-   - Grep only for 2-3 specific component names, not broad semantic sweeps.
-3. **Classify each candidate**:
-   - **Direct reuse**: Component works as-is, just import it
-   - **Refactor & reuse**: Component does 70%+ of what's needed; refactor to accept props/config to generalize it
-   - **Extract & share**: Logic is duplicated across 2+ places; extract into a shared component/hook/utility
-   - **No match**: Nothing exists; must build new (document why)
-4. **Check your agent memory**: Read `.claude/agent-memory/codebase-architect/shared-components.md` **only if the task involves UI components**. Skip for API-only or backend changes. Update it with any new discoveries.
-
-**Output format** (include in every architectural analysis):
-
-```markdown
-## Reuse Analysis
-
-### Reusable Components Found
-| Need | Existing Component | Path | Classification | Action |
-|------|-------------------|------|----------------|--------|
-| [what's needed] | [component name] | [file:line] | Direct reuse / Refactor & reuse / Extract & share | [what to do] |
-
-### No Match (Must Build New)
-- [component/pattern]: [why nothing existing fits]
-
-### Refactoring Opportunities
-- [description of duplication found that should be consolidated, even if not directly related to this feature]
-```
-
-Also include this evidence block in every analysis:
+Include this evidence block in **every** analysis, whatever the profile:
 
 ```markdown
 ## Canonical Evidence
@@ -274,38 +230,28 @@ Also include this evidence block in every analysis:
 - Ambiguities or drift: [none or explicit list]
 ```
 
-If no reuse candidates exist, output the section with "No reusable components found — all new code required" and explain why.
-
 **Your Approach:**
 
-**Token budget awareness**: aim for under 20K tokens per invocation. Targeted
-reads off the canonical router replace broad file scans — don't re-read what a
-canonical doc already told you.
-
-1. **Router First**: Start from `ssot-registry.md` and the matched canonical
-   doc/ADR. Trust the canonical contract for architectural summaries and only
-   read specific source files to verify claims you need to act on. Do NOT
-   re-read files a canonical doc already summarized.
-
-2. **Targeted reads**: For oversized docs (>400 lines), read headings and routing
-   sections first, then exact subsections. NEVER read agent memory files >20KB in
-   full — scan the filename and first 30 lines to decide relevance.
-   Say explicitly when you sampled instead of reading end-to-end.
+**Token budget awareness**: your profile sets the budget (default ≤ 20K tokens per
+invocation). Targeted reads off the canonical router replace broad file scans — don't
+re-read what a canonical doc already told you, and don't re-read files the Investigation
+Protocol's read-size rules told you to sample. Say explicitly when you sampled instead
+of reading end-to-end.
 
-3. **Multi-Layer Analysis**: Consider all layers of the stack:
+1. **Multi-Layer Analysis**: Consider all layers of the stack:
    - Data Model: How is data structured and persisted?
    - Backend Logic: What business rules and processing occur?
    - API Layer: How do systems communicate?
    - Frontend: How is the UI structured and how does it consume data?
    - Integration Points: How do external services fit in?
 
-3. **ADR Awareness**: When architectural decisions are involved, reference relevant ADRs. If you discover undocumented architectural patterns that should be ADRs, note this.
+2. **ADR Awareness**: When architectural decisions are involved, reference relevant ADRs. If you discover undocumented architectural patterns that should be ADRs, note this.
 
-4. **Trace Data Flows**: When explaining features, trace the complete flow: user action → frontend → API → backend logic → database → response.
+3. **Trace Data Flows**: When explaining features, trace the complete flow: user action → frontend → API → backend logic → database → response.
 
-5. **Identify Dependencies**: Highlight component dependencies, external services, and integration points that affect the functionality being discussed.
+4. **Identify Dependencies**: Highlight component dependencies, external services, and integration points that affect the functionality being discussed.
 
-6. **Security & Permissions**: Always consider the permission model when explaining features. Flag deprecated permission patterns documented in the project's MEMORY.md or AGENTS.md.
+5. **Security & Permissions**: Always consider the permission model when explaining features. Flag deprecated permission patterns documented in the project's MEMORY.md or AGENTS.md.
 
 **Common Patterns to Capture (adapt to your project):**
 
@@ -322,8 +268,10 @@ emit the structured substance ONLY, no narrative. Brain big, mouth small. Your
 return value is injected verbatim into the caller's context, so every word of
 prose costs them context budget on every subsequent turn.
 
-- **Emit, unchanged (these ARE the contract):** the `## Reuse Analysis` table and
-  the `## Canonical Evidence` block.
+- **Emit, unchanged (these ARE the contract):** the `## Canonical Evidence` block,
+  plus the `## Reuse Analysis` table and any profile-specific block
+  (code-path map / affected-surface table / component-binding notes — see
+  `agents/analysis-profiles.md`) when your profile runs them.
 - **Affected code as rows, not paragraphs:** `path:line — symbol — pattern/role`.
 - **High-risk paths / integration points, one line each:** `path:line — risk`.
 - **Hot-File Map (MANDATORY for every in-scope file > 800 lines):** a

package/framework/.claude/agents/hybrid-ml-architect.md

@@ -125,7 +125,7 @@ You MUST run as a state machine. Always label your current state at the top of e
 - Restate problem in 3–6 bullets.
 - Identify objective function / KPI.
 - Identify constraints (privacy, latency, cost, cold start).
-- Invoke `codebase-architect` agent to understand existing system structure.
+- Invoke `codebase-architect` agent (`PROFILE=feature` — `agents/analysis-profiles.md`) to understand existing system structure.
 
 ### STATE 1 — RESEARCH CHECK
 - Locate and summarize "Research Inputs Used".

package/framework/.claude/agents/legal-counsel-gdpr.md

@@ -171,7 +171,7 @@ When first invoked on a project, before doing anything else:
 ## AGENTS.md Compliance
 
 You MUST follow all rules in AGENTS.md, including:
-- Invoke `codebase-architect` agent (via Task tool) before planning or implementing changes to understand existing patterns
+- Invoke `codebase-architect` agent (via Task tool, `PROFILE=feature` — `agents/analysis-profiles.md`) before planning or implementing changes to understand existing patterns
 - Update `${paths.references_dir}/project-status.md` Active Code Context before work
 - Pick a backlog card, set IN_PROGRESS, and assign yourself before work
 - Keep docs and code in sync

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

@@ -84,7 +84,7 @@ When auditing plans for a specific project, replace the bullets above with proje
    - List the exact missing inputs as "Blocking Questions"
    - Propose safe defaults / options and explain trade-offs for each
 6. **Produce outputs that are directly actionable** by engineers. No fluff, no generic advice, no motivational language.
-7. **FULL mode only**: before starting your audit, invoke the `codebase-architect` agent (via Task tool) to understand the current codebase structure, existing patterns, and architecture relevant to the plan being reviewed. Do not audit without this context. In **QUICK** mode the caller has already supplied this grounding — do NOT re-spawn codebase-architect.
+7. **FULL mode only**: before starting your audit, invoke the `codebase-architect` agent (via Task tool) to understand the current codebase structure, existing patterns, and architecture relevant to the plan being reviewed — pass `PROFILE=impact OUTPUT=terse` (the plan's blast radius is what your audit needs; contract in `agents/analysis-profiles.md`). Do not audit without this context. In **QUICK** mode the caller has already supplied this grounding — do NOT re-spawn codebase-architect.
 
 ## PROMPT INJECTION GUARD (MUST — read first)
 
@@ -348,14 +348,15 @@ Consider:
 
 ## SEVERITY CALIBRATION (after challenge pass)
 
-After challenge pass, rank ALL surviving findings by impact:
+Severity is **ABSOLUTE, per finding, anchored to its evidenced consequence** — never a relative ranking, never a quota. (Positional bands like "top 20% → HIGH" manufacture mandatory findings on clean plans and demote real defects on large batches; both are calibration failures.)
 
-1. List all surviving findings in order of impact (most impactful first).
-2. Assign severity based on position:
-   - Top 20% → **HIGH** (must fix before implementation)
-   - Middle 40% → **MEDIUM** (should fix, mark `[MANUAL]` if ambiguous)
-   - Bottom 40% → **LOW** (note only, do not edit structured fields)
-3. **Exception**: data loss, security bypass, breaking change, claimed_path collision, ADR required missing = automatically **HIGH** regardless of position.
+For each surviving finding ask: *"what happens if the card is implemented exactly as written?"*
+
+- **HIGH** (must fix before implementation) — implementing the card as written produces a defect: data loss, security bypass, breaking change, claimed_path collision, ADR required missing, wrong behavior against a stated AC, an unimplementable AC (e.g. its seam file is outside the card's ownership), or a missing `depends_on` that creates a cross-card conflict. A HIGH MUST cite its evidence (card field/line + the code path that proves it); no evidence citation → cap at MEDIUM.
+- **MEDIUM** (should fix, mark `[MANUAL]` if ambiguous) — the card is implementable but a gap will plausibly cost a review cycle: missing doc/file in `files_likely_touched`, vague-but-inferable AC, missing validation command.
+- **LOW** (note only, do not edit structured fields) — informational, no behavioral consequence.
+
+Zero HIGH — or zero findings at all — on a well-formed card is a legitimate, reportable outcome. Do NOT stretch severities to fill bands.
 
 ## QUANTIFIED RISK SCORING (MANDATORY)
 

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

@@ -91,6 +91,14 @@ the card reaches `status: DONE`.
 
 6. **Populate `data_fields`** for every card that reads/writes the persistence layer (see Required Fields).
 
+**Never guess silently — mark the ambiguity.** The grounding rule generalizes beyond field
+names: whenever card material forces you to GUESS (an unresolved behavior, an unspecified
+control/state, a value the PRD/Discovery never pinned down), do NOT pick a plausible answer
+silently — write `[NEEDS CLARIFICATION: <the exact question>]` inline at the ambiguous spot.
+The `/prd` validation gate (`validate-card-baseline.js --prd`) BLOCKS commit while any marker
+is unresolved, so the ambiguity reaches a human instead of shipping as a hidden assumption.
+A marker is a legitimate intermediate state, never a defect — the defect is the silent guess.
+
 ## Mission
 
 You receive:

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

@@ -284,7 +284,7 @@ When you need to examine code, use Glob/Grep to find actual file paths before re
 ## Repo Workflow Expectations
 
 - Respect `AGENTS.md` as authoritative.
-- Use `codebase-architect` for architecture discovery before broad security recommendations that depend on current structure.
+- Use `codebase-architect` (`PROFILE=feature` — `agents/analysis-profiles.md`) for architecture discovery before broad security recommendations that depend on current structure.
 - Treat `${paths.references_dir}/project-status.md` as transient coordination context, not canonical feature truth.
 - When you find a security issue that implies doc or ADR drift, flag the required follow-up explicitly.
 

package/framework/.claude/commands/codexreview.md

@@ -117,7 +117,7 @@ If a card cannot be found, mark it as `UNKNOWN` and ask the user before continui
 > (plus the attached `diff_summary_path`) as the mandatory context for downstream agents, and go to
 > Step 2. In full mode (no contract file), run this step as written.
 
-Before running any review agents, invoke `codebase-architect` (via Task tool) for each card scope to map:
+Before running any review agents, invoke `codebase-architect` (via Task tool) for each card scope — pass `PROFILE=baseline OUTPUT=terse` (diff-scoped review grounding; contract in `agents/analysis-profiles.md`) — to map:
 
 - Existing architecture and critical patterns
 - High-risk code paths for regressions

package/framework/.claude/skills/bug/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.0 — 2026-07-02
+
+- **Analysis-profile contract (framework v4.94.0)**: Phase 0 code-path mapping passes `PROFILE=bug` — the profile returns the entry→failure code-path map + the recent-change suspect list and skips reuse/architecture noise. SSOT: `framework/agents/analysis-profiles.md`.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,7 +1,7 @@
 ---
 name: bug
 effort: medium
-version: 1.0.0
+version: 1.1.0
 description: >
   Structured bug investigation and resolution workflow (framework-agnostic; project-specific entry points are loaded from `.baldart/overlays/bug.md`).
   Use when: the user says /bug, 'debug', 'c e un bug', 'non funziona', 'errore', 'broken',
@@ -60,9 +60,11 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
    - **Auth** → the project's auth middleware/guard + auth error codes (per `stack.auth_provider`)
    - **Build/Deploy** → the deploy platform's logs + build output (per `stack.deployment`, e.g. Vercel)
 3. Launch `codebase-architect` agent to map the affected code paths — do NOT start debugging blind.
-   Pass `OUTPUT=terse` (since v4.49.0): you want the structured map (`path:line — symbol` rows,
-   high-risk paths, `totals:`), not a narrative essay — its return is injected verbatim into this
-   investigation context, so keep it lean.
+   Pass `PROFILE=bug OUTPUT=terse` (profile contract: `agents/analysis-profiles.md` — the
+   `bug` profile returns the code-path map entry→failure + the recent-change suspect list
+   and skips reuse/architecture noise; since v4.94.0). You want the structured map
+   (`path:line — symbol` rows, high-risk paths, `totals:`), not a narrative essay — its
+   return is injected verbatim into this investigation context, so keep it lean.
    When `features.has_lsp_layer: true` and the symptom names a concrete symbol
    (function/type/handler), `codebase-architect` will use LSP find-references /
    go-to-definition to locate the exact callsites instead of grepping. See

package/framework/.claude/skills/context-primer/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.0 — 2026-07-02
+
+- **Analysis-profile contract**: the embedded architect prompt no longer restates the
+  search strategy (canonical-router steps, task-adaptive rules, UI cascade, wiki
+  routing — a dual-SSOT with the agent body). It now passes
+  `PROFILE=<bug|impact|discovery|ui>` mapped deterministically from the detected task
+  type (new step 2b) and cites `framework/agents/analysis-profiles.md` as the single
+  SSOT of the retrieval plan. Skill-specific inputs (overlay must-include docs, git
+  recency signal) and the XML output envelope are unchanged.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/context-primer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cont
 effort: medium
-version: 1.0.0
+version: 1.1.0
 description: >
   Load codebase context silently before starting work, optimized for LLM
   comprehension using research-backed structured formatting.
@@ -56,72 +56,38 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 
    Default to `query` if ambiguous.
 
+2b. **Map the task type to an analysis profile** (the mapping SSOT is
+   `framework/agents/analysis-profiles.md` § 3 — do not restate search strategy here):
+
+   | Task type | PROFILE |
+   |-----------|---------|
+   | `bug-fix` | `bug` |
+   | `refactor` | `impact` |
+   | `new-feature`, `query`, `doc-update` | `discovery` (pass the task type through — the profile has per-task-type deltas) |
+   | any type + UI/component/token keywords when `features.has_design_system: true` | `ui` |
+
 3. Launch `codebase-architect` agent with this prompt template:
 
 ```
 Load context about: {keywords}
 Task type: {task_type}
 
+PROFILE={profile} — resolve your analysis profile per `agents/analysis-profiles.md`
+(Grep `### PROFILE: {profile}`, Read ONLY that section + the shared blocks it cites).
+It defines your retrieval plan, what to skip, and your output blocks. Your system
+prompt's Investigation Protocol is the engine; the profile scopes it.
+
 OUTPUT=terse — you are a silent loader's machine consumer, not a human Q&A. Return the
-structured contract (reuse table + canonical evidence + `path:line — symbol` rows + `totals:`)
-with no narrative prose; the loader condenses this into the XML context block.
-
-TOKEN BUDGET: stay under 15K tokens total. Prefer the canonical router + targeted reads over broad file scans.
-
-SEARCH STRATEGY — canonical-router-first, verify-only-if-needed:
-
-1. Resolve the topic to its canonical source. Read `${paths.references_dir}/ssot-registry.md`
-   to route `{keywords}` to the owning reference doc / ADR, then read only the matched
-   section(s). If the topic is documentation-heavy and `features.has_wiki_overlay: true`,
-   also consult `${paths.wiki_dir}/index.md` and any must-include docs listed in
-   `.baldart/overlays/context-primer.md` (verify wiki claims against canonical docs).
-
-2. Targeted searches:
-   a. Agent memory: grep MEMORY.md index for topic match, read ONLY
-      matching files (skip files >20KB unless filename matches keywords).
-   b. Backlog (when `features.has_backlog: true`): grep `${paths.backlog_dir}/*.yml` for card titles matching keywords.
-      Read only the matching cards, not all cards.
-   c. Git: `git log --oneline -10 --grep="{keywords}"` (10 results max).
-
-3. Broader search (when steps 1-2 are thin):
-   a. Search for 2-3 specific identifiers from steps 1-2, routing by query shape
-      per `framework/agents/code-search-protocol.md` (symbols → LSP when
-      `has_lsp_layer`) and `framework/agents/code-graph-protocol.md` (structural /
-      relational → Graphify when `has_code_graph`); grep is the fallback for textual
-      patterns. Follow those modules' tier order, budgets, and anti-flail rule —
-      don't restate them here.
-   a-bis. **UI / component keywords when `has_design_system: true`**: route via the
-      design-system layer, NOT source scans — read `${paths.design_system}/INDEX.md`
-      (thin router) then the **frontmatter HEAD** of the matched
-      `components/<Name>.md` (props/variants/token_bindings; schema
-      `framework/agents/component-manifest-schema.md`). Read a spec's prose / the
-      source only to verify a runtime-sensitive claim. This is the cheap on-demand
-      path that replaces reading a monolithic INDEX or component sources.
-   b. Read key file headers (first 50 lines) to identify structure.
-   DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
-   route via the registry and read only the specific section you need.
-
-4. Targeted verification (ALL cases):
-   - Verify ONLY runtime-sensitive claims (auth patterns, API contracts,
-     current schema) against actual code.
-   - Files <200 lines: read in full.
-   - Files 200-500 lines: read first 50 lines + specific section.
-   - Files >500 lines: grep for key exports/functions, read only those.
-   - NEVER read agent memory files >20KB in full.
-
-TASK-ADAPTIVE RULES:
-- "query": canonical docs + memory only. Skip source code unless code-specific.
-- "bug-fix": canonical docs + recent git changes + error-related code. Skip arch docs.
-- "new-feature": canonical docs + patterns in same domain + ADRs. Skip unrelated areas.
-- "refactor": canonical docs + affected files + dependency refs. Skip design rationale.
-- "doc-update": SSOT registry. Skip source code.
-
-WIKI OVERLAY ROUTING:
-- If the topic is about synthesized knowledge, dashboards, reading guides, or
-  recurring documentation questions, prefer the derived wiki overlay as a
-  compression layer.
-- Always verify wiki claims against canonical repo docs before using them as
-  working truth.
+structured contract (the profile's blocks + canonical evidence + `path:line — symbol`
+rows + `totals:`) with no narrative prose; the loader condenses this into the XML
+context block.
+
+TOKEN BUDGET: stay under 15K tokens total (this caps the profile default).
+
+SKILL-SPECIFIC INPUTS (on top of the profile plan):
+- Must-include canonical docs listed in `.baldart/overlays/context-primer.md` (if the
+  overlay is present) — read their matched sections.
+- Recency signal: `git log --oneline -10 --grep="{keywords}"` (10 results max).
 
 Return output in this EXACT XML format (30-50 lines max):
 

package/framework/.claude/skills/ds-handoff/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.2.0 — 2026-07-02
+
+- **Analysis-profile contract (framework v4.94.0)**: the standalone screen-resolution probe passes `PROFILE=ui` to `codebase-architect` per `framework/agents/analysis-profiles.md`. The Step 3 field-extraction retrieval order is unchanged.
+
 ## 1.1.0 — 2026-07-01
 
 - **Decision & preference pass (Step 5.5)** — nuovo `references/decision-pass.md`.

package/framework/.claude/skills/ds-handoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ds-handoff
 effort: medium
-version: 1.1.0
+version: 1.2.0
 description: >
   Produce a FIELD-LEVEL, 1:1, interaction-complete handoff brief for Claude Design
   — every screen's real fields (label, control type, required, validation, default,
@@ -89,7 +89,8 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
    `mockup_analysis` from the `/prd` state file `## UI Design` (reuse the caller's
    collection — do NOT re-derive). *Standalone* → derive screens from the arg;
    on ambiguity, ONE `AskUserQuestion` listing route/page candidates from a
-   `codebase-architect` probe. Never proceed on silence.
+   `codebase-architect` probe (pass `PROFILE=ui` — `agents/analysis-profiles.md`).
+   Never proceed on silence.
 
 2. **Identify backing entities per screen.** Name the entity/entities each screen
    reads or writes. A screen may legitimately have **zero** entities (pure

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

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.3.0 — 2026-07-02
+
+- **Analysis-profile contract (framework v4.94.0)**: the two `codebase-architect` reverse-dependency lookups (routes importing a changed component; primitives used by a route in compliance-only mode) pass `PROFILE=impact` per `framework/agents/analysis-profiles.md`.
+
 ## 1.2.1 — 2026-07-02
 
 - Phase 3.8: la lane visual del route non renderizzabile con mockup code-form viene