baldart 4.93.0 → 4.95.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.95.0] - 2026-07-02
+
+**`/prd` — applier economico + EARS+verify (i due interventi strutturali dal forensics della deep analysis).**
+
+- **Apply dei finding delegato** (`prd-card-writer` `MODE: apply-findings` — un agente + token, pattern analysis-profiles v4.94.0): l'orchestratore `/prd` non edita più YAML a piena finestra (misurato: le fasi meccaniche erano il 48% del costo di un run reale, ~48 Edit a ~663k cache-read/chiamata). L'applier gira in contesto fresco (Claude: override `model: sonnet`; Codex: by-name), riceve tutto BY PATH, applica solo campi `[Target:]` con grounding obbligatorio, ESEGUE `validate-card-baseline.js --prd` + `stamp-holistic-audit.js`, ritorna compact; `audit-phase.md` 6.9 = delega thin + drift guard + fallback inline visibile. Verificato con spawn reale su fixture.
+- **AC in grammatica EARS** (child/standalone; SSOT `card-schema.md` § "Acceptance-criteria grammar"): binari per forma (5 pattern + `SHALL CONTINUE TO`), ban-list verbi vaghi, BLOCKER in `--prd`; card legacy mai retro-bloccate.
+- **`ac_verification`** — oracolo eseguibile per-AC definito a planning time (o `manual:` esplicito), authoring groundato (mai comandi inventati), eseguito da `/new` Phase 2.5 (step 4b — exit status = evidenza primaria); `qa-sentinel` intatto per contratto. Enforcement WARN-first; fixtures CI (Check D).
+
+**MINOR** — capability su skill/agent/moduli condivisi; nessun cambio di layout install. **No new `baldart.config.yml` key**; la propagazione dello schema CARD viaggia completa nella release (matrice + template + writer + validator + consumer + attack-surface — pattern v4.35.0). **Codex parity: portable.**
+
+## [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:

package/VERSION

@@ -1 +1 @@
-4.93.0
+4.95.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 |
@@ -35,7 +35,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **hyper-gamification-designer** | Design | Analyze game features and retention mechanics | Progression, reward loops | No | MDA analysis, economy balance |
 | **remotion-animator-orchestrator** | Design | Create Remotion video animations | Motion graphics, asset coordination | Yes | Remotion, visual agent coordination |
 | **prd** | Product | Create PRDs, plans, and backlog cards | Requirements, execution planning | No | PRD writing, backlog management |
-| **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
+| **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD; `MODE: apply-findings` = fresh-context applier of audit findings to card YAML (spawned by /prd Step 6.9, sonnet override) | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
 | **onboarding-architect-lead** | Product | Design/improve user onboarding experiences | Activation flows, experiments | No | Onboarding research, metrics |
 | **website-orchestrator** | Product | Coordinate multi-agent website development | Project orchestration | No | Phase management, quality gates |
 | **senior-researcher** | Research | Comprehensive research on technical topics | Evidence-based analysis | Yes | Web search, citations |
@@ -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)
 

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

@@ -476,7 +476,20 @@ Every card MUST include ALL fields from the template:
 - `context` (background + PRD reference)
 - `scope` (summary, users, value)
 - `requirements` (concrete, specific)
-- `acceptance_criteria` (testable `[ ] [AC-N]` items)
+- `acceptance_criteria` (testable `[ ] [AC-N]` items — **EARS grammar MANDATORY on child/
+  standalone cards**: the clause matches one of `THE SYSTEM SHALL …` / `WHEN … THE SYSTEM
+  SHALL …` / `WHILE …` / `WHERE …` / `IF … THEN THE SYSTEM SHALL …` (+ `SHALL CONTINUE TO`
+  for non-regression). Body in the project language, EARS keywords in English. NO vague
+  verbs ("correttamente", "properly", "as expected", … — the `--prd` validator ban-list
+  BLOCKS them): name the observable behavior. SSOT + worked example: `card-schema.md`
+  § "Acceptance-criteria grammar (EARS)". Epic AC-EPIC roll-ups are exempt.)
+- `ac_verification` (OPTIONAL map `AC-N → executable oracle`) — **grounding rule, same class
+  as the Field Grounding Rule**: write a command ONLY if you verified it exists (an npm
+  script in `package.json`, a command in `toolchain.commands.*`, a cited test file that
+  exists — Grep/Read to confirm). NEVER invent commands. Not automatable → explicit
+  `manual: <what a human checks>`. Genuinely undecidable → `[NEEDS CLARIFICATION: …]`.
+  Non-manual oracles SHOULD also appear in `validation_commands` (the validator warns on
+  drift). Consumed by `/new` Phase 2.5, which EXECUTES them.
 - `definition_of_done` (checklist including doc invariants). **When `features.has_i18n: true`** AND the
   card introduces user-facing strings, the DoD MUST carry an i18n-completeness line — NOT merely "strings
   via `t()` + registered", but: *"new keys authored in the source locale + the i18n context registry (by
@@ -724,3 +737,97 @@ Return to the caller a structured summary:
 - Cross-reference every requirement against the PRD source section
 - Verify file paths in `files_likely_touched` exist in the codebase (use Glob to check)
 - Count total files across all cards to verify no file is assigned to conflicting cards without a conflict edge
+
+## MODE: apply-findings (audit-fix applier — invoked by `/prd` audit-phase Step 6.9)
+
+**Trigger:** the invocation prompt contains `MODE: apply-findings`. In this mode you do NOT
+author new cards — you apply an audit's consolidated findings to EXISTING card YAML files.
+(Same one-agent+token mechanism as `PROFILE=` / `OUTPUT=terse`: a mode is a parameter, not a
+twin agent.)
+
+**Why this mode exists (measured):** the `/prd` orchestrator used to apply findings inline at
+full context window (~48 Edits at ~663k cache-read per call — the mechanical phases were 48%
+of a real run's cost). In a fresh subagent context the same work costs a fraction. On Claude
+the caller spawns this mode with a `model: sonnet` override (batch card AUTHORING keeps the
+frontmatter model); on Codex the by-name agent inherits the session model — the primary
+enabler is the fresh context + structured I/O, not the model tier.
+
+**Inputs (all BY PATH — never pasted content):**
+- `REPORT_FILE` — the consolidated audit report (audit-phase Step 6.7 format: findings grouped
+  per card, each tagged `(Severity: HIGH/MEDIUM/LOW)` + `[Target: <field>]`)
+- `CARD_PATHS` — the card YAML files to edit
+- `AUDITED_AT` / `AUDITED_COMMIT` / `AUDITED_SET` — the run-level provenance values
+  (audit-phase § "Holistic-audit provenance stamp")
+- `VALIDATOR` — path of `validate-card-baseline.js`; `STAMPER` — path of `stamp-holistic-audit.js`
+
+**Workflow:**
+1. Read the report; group findings per card ID.
+2. Per card, apply HIGH first, then MEDIUM, per the FIELD MAPPING table below:
+   - Edit ONLY the field named by each finding's `[Target: <field>]` tag. NEVER touch a field
+     no finding targets; NEVER "improve" untargeted content. The Field Grounding Rule above
+     binds here too (no invented field names).
+   - A finding that genuinely requires a human decision → do NOT apply; record it as `[MANUAL]`.
+   - A finding whose suggested content is UNGROUNDED (a path that doesn't exist in the repo,
+     a command not in the project's convention) or ALREADY SATISFIED by the card → do NOT
+     apply it as-is; ground it against the repo first (Glob/Grep), apply the grounded form,
+     or record it in the audit trail as `already-satisfied` / `ungrounded (<why>)`.
+   - LOW findings: audit-trail note only — no structured-field edits.
+   - Append the audit trail to `notes` (format below).
+3. **EXECUTE** `node <VALIDATOR> --prd <card>` on every edited card — exit 0 required. On
+   failure, fix your own edit and re-run (max 2 attempts, then report that card as
+   `validator: FAIL` with the error output — never ship a silently-invalid card).
+4. **EXECUTE** the stamper ONCE for the whole set:
+   `node <STAMPER> --at <AUDITED_AT> --commit <AUDITED_COMMIT> --set <AUDITED_SET> <CARD_PATHS>`
+5. Return the COMPACT summary below. Do NOT echo card bodies or the report back.
+
+### FIELD MAPPING (Target tag → card field → action)
+
+| Target tag | Card field | Action |
+|---|---|---|
+| `[Target: requirements]` | `requirements` | Append missing requirement or rewrite existing one |
+| `[Target: acceptance_criteria]` | `acceptance_criteria` | Append new `"[ ] [AC-N] ..."` item or rewrite vague AC |
+| `[Target: definition_of_done]` | `definition_of_done` | Append new `"[ ] ..."` item |
+| `[Target: files_likely_touched]` | `files_likely_touched` | Append missing path (no duplicates) |
+| `[Target: depends_on]` | `depends_on` | Append missing card ID |
+| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from ${git.trunk_branch}` |
+| `[Target: areas]` | `areas` | Add missing area key/value |
+| `[Target: unknowns]` | `unknowns` | Append new `[U-N] UNKNOWN: ...` entry |
+| `[Target: existing_patterns]` | `existing_patterns` | Append missing pattern reference or fix stale line_range/anchor_text |
+| `[Target: validation_commands]` | `validation_commands` | Append missing verification command |
+| `[Target: anti_patterns]` | `anti_patterns` | Append missing DO NOT constraint |
+| `[Target: scope_boundaries]` | `scope_boundaries` | Add missing in_scope or out_of_scope item |
+| `[Target: input_output_examples]` | `input_output_examples` | Append missing scenario or fix incorrect example |
+| `[Target: error_handling]` | `error_handling` | Append missing failure mode or fix incorrect action |
+| `[Target: reuse_analysis]` | `reuse_analysis` | Add missing reuse opportunity or correct file path |
+| `[Target: notes]` | `notes` | Audit trail only |
+
+### Severity policy
+
+- **HIGH**: MUST apply. Card cannot be safely implemented without these.
+- **MEDIUM**: SHOULD apply. Skip only if human judgment needed (mark `[MANUAL]`).
+- **LOW**: Do NOT edit structured fields. Audit trail note only.
+
+### Audit trail in `notes`
+
+After applying all edits to a card, append to its `notes`:
+
+```yaml
+## Applied by quality audit — YYYY-MM-DD
+Applied N findings to structured fields (H high, M medium).
+Manual review needed: [list [MANUAL] items, or "none"].
+```
+
+### Return contract (COMPACT — the ONLY output)
+
+```
+APPLY-FINDINGS DONE
+- <CARD-ID>: applied <H> high / <M> medium; manual: [<finding titles> | none]; validator: PASS|FAIL
+- ...
+stamp: <the stamper's one-line summary>
+```
+
+### Boundaries (mode-specific)
+
+Read-only outside the card files; no Task/Agent spawns; no git commits/staging (the
+orchestrator's Step 7 owns git); no card creation, deletion, or renaming; no edits to
+fields not targeted by a finding.

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.