baldart 4.93.0 → 4.94.0

package/framework/.claude/skills/new/references/final-review.md

@@ -211,7 +211,8 @@ that is a **gate violation**: log it as
      Log `f.2-arch: reused N per-card baselines (no re-spawn)` in the tracker. This avoids the N+1
      architect invocations the per-card persistence was designed to prevent.
    - **Any missing** (a card was added late, or a baseline was purged) → invoke **codebase-architect**
-     ONCE over the batch scope to map existing architecture, critical patterns, and high-risk code
+     ONCE over the batch scope — pass `PROFILE=baseline OUTPUT=terse` (`agents/analysis-profiles.md`) —
+     to map existing architecture, critical patterns, and high-risk code
      paths for regression. Persist its output to `/tmp/arch-baseline-batch-<FIRST-CARD-ID>.md` and set
      `${ARCH_BASELINE_PATHS}` to that single path. Log `f.2-arch: re-spawned (missing baselines: <list>)`. Do NOT spawn
      the architect more than once for the batch — it is the single grounding context for all

package/framework/.claude/skills/new/references/implement.md

@@ -10,7 +10,7 @@
    - If `DONE` (or the user chose "proceed anyway") → continue.
 2b. **Claim** — only now set the card status to `IN_PROGRESS` (in the backlog YAML / tracker) and assign yourself. This is a state write, not a visibility emission — do not also spend a TaskUpdate / Progress-Bar turn (§ "State surface — the tracker only").
 2c. **Trivial-card classification (BLOCKING gate for steps 3–4)** — evaluate `IS_TRIVIAL(card)` per § "Trivial-card fast-lane". Note: condition 3 (non-source diff) cannot be fully evaluated until the coder has produced the diff, so at this point compute the **provisional** trivial flag from conditions 1+2 only (`review_profile == skip` AND no Step-A trigger sourced from the card YAML text + `files_likely_touched` extensions — if EVERY path in `files_likely_touched` is non-source, condition 3 is provisionally satisfied). If provisionally trivial → **SKIP steps 3, 3a, and 4** (architecture grounding); log `trivial: architecture grounding skipped (review_profile=skip + non-source files_likely_touched + 0 triggers)` and jump to Phase 2. Re-confirm `IS_TRIVIAL` on the ACTUAL committed diff at the review gates (Phase 2.55/3.5/3.7); if the coder unexpectedly touched a source file, the guard flips the card back onto the normal review path there. If NOT provisionally trivial → run steps 3, 3a, 4 as normal.
-3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. Likewise, when `features.has_code_graph: true`, the architect uses the Graphify code graph for structural/relational lookups (ambient flag) per `agents/code-graph-protocol.md`. The orchestrator does NOT propagate either flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.) **Pass `OUTPUT=terse` in the architect prompt (since v4.49.0)** — this is grounding for the coder/reviewer, not an explanation, so the architect returns its structured contract (reuse table + canonical evidence + `path:line — symbol` rows + `totals:`) without narrative prose. The verbatim baseline persisted at step 5b keeps all the substance a lean `/codexreview` needs (paths, signatures, patterns, high-risk paths) while staying small in the orchestrator's context and on disk. **Baseline content contract (MANDATORY — since v4.56.0):** the architect prompt is grounding INPUT only — pass the card scope, `files_likely_touched`, and the question to map. NEVER put line-level fix directives ("remove lines 90-91", "Fix: use X"), the words "implement/fix/apply", or acceptance-criteria framed as a task into the architect prompt. The architect produces a read-only MAP (file/symbol locations, patterns, type signatures, integration points, high-risk paths); it does NOT implement and has no `Task`/Agent tool to delegate (see `codebase-architect.md` § Role boundary). The coder is a separate spawn the orchestrator owns.
+3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. Likewise, when `features.has_code_graph: true`, the architect uses the Graphify code graph for structural/relational lookups (ambient flag) per `agents/code-graph-protocol.md`. The orchestrator does NOT propagate either flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.) **Pass `OUTPUT=terse` in the architect prompt (since v4.49.0)** — this is grounding for the coder/reviewer, not an explanation, so the architect returns its structured contract (reuse table + canonical evidence + `path:line — symbol` rows + `totals:`) without narrative prose. **Pass the analysis profile too (since v4.94.0)**: `PROFILE=ui` when the card has a non-empty `links.design` OR `links.design_src` (the same mockup bit that drives step 6a), else `PROFILE=feature` — contract and per-profile scoping in `agents/analysis-profiles.md` (its § 3 caller routing table is normative). The profile is deterministic from the card YAML; never leave the architect to infer it. The verbatim baseline persisted at step 5b keeps all the substance a lean `/codexreview` needs (paths, signatures, patterns, high-risk paths) while staying small in the orchestrator's context and on disk. **Baseline content contract (MANDATORY — since v4.56.0):** the architect prompt is grounding INPUT only — pass the card scope, `files_likely_touched`, and the question to map. NEVER put line-level fix directives ("remove lines 90-91", "Fix: use X"), the words "implement/fix/apply", or acceptance-criteria framed as a task into the architect prompt. The architect produces a read-only MAP (file/symbol locations, patterns, type signatures, integration points, high-risk paths); it does NOT implement and has no `Task`/Agent tool to delegate (see `codebase-architect.md` § Role boundary). The coder is a separate spawn the orchestrator owns.
 3a. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project) — do this AFTER the codebase-architect run (step 3) so the "Active Code Context" reflects the architect's findings (which files are actually in scope), not just the card YAML's `files_likely_touched`. Writing it before the architect run would persist pre-analysis claims that downstream agents (e.g. a parallel card) would then read as truth.
 4. **Plan-auditor grounding check** — but first, a **provenance skip (since v4.7.0 — mirror of Step 3d)**: the `/prd` Step 6.6 holistic audit already ran a per-card grounding pass when the card was authored. Re-grounding here is only worth a plan-auditor spawn if something changed since. **This skip is the NORMAL path for a card implemented right after `/prd`, not an occasional optimization** — `/prd` now guarantees the `metadata.holistic_audit` stamp lands on every audited card (deterministic backstop at `validation-phase.md` Step 7 item 5b, since the v4.88.2 provenance-reliability fix), so P1 below holds whenever the batch is freshly authored. Skip the plan-auditor when **BOTH** hold:
    - **P1 — provenance present**: the card has `metadata.holistic_audit` with non-empty `audited_at`, `audited_commit`, `audited_set`.

package/framework/.claude/skills/new2/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 B7 per-card architect spawn in `new2.js` passes `PROFILE=${hasMockup ? 'ui' : 'feature'}` (deterministic from the pre-flight cardGraph bit) mirroring `/new` implement.md step 3; the SSOT is `framework/agents/analysis-profiles.md`. Tripwire rule added to `check-new-parity.mjs`.
+
 ## 1.2.1 — 2026-07-02
 
 Review avversariale post-release (3 lenti indipendenti, finding verificati):

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.2.1
+version: 1.3.0
 description: >
   Workflow-hosted batch engine for /new. Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background

package/framework/.claude/skills/prd/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 discovery-loop targeted architect question now passes `PROFILE=discovery`, and the Step 2 ISA scan passes `PROFILE=impact` (structural tier primary) — per `framework/agents/analysis-profiles.md`. Prompt semantics otherwise unchanged.
+
 ## 1.2.0 — 2026-07-02
 
 **Gate-hygiene wave** — dai driver misurati sul forensics di una sessione /prd reale (61.6M token; 48% del costo in fasi meccaniche a piena finestra; una famiglia di card spedita con zero audit-trail; ~20 righe di progress bar × 30+ messaggi):

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

@@ -1,7 +1,7 @@
 ---
 name: prd
 effort: high
-version: 1.2.0
+version: 1.3.0
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 

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

@@ -698,7 +698,9 @@ section of the state file. Mark dimension as covered.
    If more specific detail is needed beyond what context-primer provided,
    invoke `codebase-architect` agent (foreground) with a targeted question:
    ```
-   OUTPUT=terse — machine consumer (discovery dimension resolution), not human Q&A.
+   PROFILE=discovery OUTPUT=terse — machine consumer (discovery dimension resolution),
+   not human Q&A. Resolve your analysis profile per `agents/analysis-profiles.md`
+   (Grep "### PROFILE: discovery", read only that section).
    For feature `<slug>`: regarding the dimension `<dimension>`, does the codebase
    already answer this? Specifically check: existing collections, routes, components,
    permissions, and patterns. Report what you find with file references — structured
@@ -780,8 +782,10 @@ Instead, run the ISA scan and present findings for validation.
 1. Invoke `codebase-architect` agent with this specific prompt:
 
    ```
-   OUTPUT=terse — machine consumer (ISA table builder), not human Q&A: per-touchpoint
-   rows only, no narrative overview.
+   PROFILE=impact OUTPUT=terse — machine consumer (ISA table builder), not human Q&A:
+   per-touchpoint rows only, no narrative overview. Resolve your analysis profile per
+   `agents/analysis-profiles.md` (Grep "### PROFILE: impact", read only that section —
+   the structural tier is your primary source when its flag is on).
    For feature `<slug>`: perform an Integration Surface Analysis (ISA).
    Find ALL existing code that should reference, link to, or interact with this
    new feature. Scan these categories systematically:

package/framework/.claude/skills/prd-add/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)**: PATCH-mode re-discovery passes `PROFILE=impact` to `codebase-architect` (blast-radius scoping per `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/prd-add/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: prd-add
 effort: medium
-version: 1.0.0
+version: 1.1.0
 description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
 ---
 
@@ -241,7 +241,8 @@ Execute ONLY phases with PATCH or REDO verdict, in original phase order.
 
 ### For Discovery dimensions (PATCH/REDO)
 
-- **PATCH**: Run `codebase-architect` on affected dimensions only.
+- **PATCH**: Run `codebase-architect` on affected dimensions only — pass
+  `PROFILE=impact` (blast-radius scoping per `agents/analysis-profiles.md`).
   Update state file checklist entries. No user questions unless ambiguous.
 - **REDO**: Full re-discovery for that dimension (same as /prd Step 2 loop
   but scoped to affected dimensions only). May require user questions.

package/framework/.claude/skills/ui-design/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)**: Step B adjacent-UI analysis passes `PROFILE=ui OUTPUT=terse` to `codebase-architect` (registry-cascade-first per `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/ui-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ui-design
 effort: medium
-version: 1.0.0
+version: 1.1.0
 description: "UI design workflow. Generates context-aware mockups with GAN-inspired generator/evaluator separation, visual verification via Playwright, and structured sprint contracts. Use when: (1) designing new pages or components, (2) the /prd skill reaches its UI design phase (Step 3), (3) redesigning existing pages, (4) creating design options for user review, (5) any task involving 'design UI', 'mockup', 'opzioni di design', 'progetta interfaccia', '3 opzioni', 'design page', 'UI design'. Not for: bug fixes, small tweaks, copy-only changes, or implementing an already-chosen design."
 ---
 
@@ -120,7 +120,7 @@ Read [references/generation.md](references/generation.md) § Context Capture.
    render harness over full-page Playwright — `baldart render build && /ds-render`
    gives per-primitive PNGs of the REAL registry components (Storybook-backed). Use
    full-page Playwright for page-level context. No Storybook → fall back to Playwright.
-3. Invoke `codebase-architect` to analyze adjacent UI components, layout patterns, and design tokens. Report file paths and rendered structure.
+3. Invoke `codebase-architect` with `PROFILE=ui OUTPUT=terse` (profile contract: `agents/analysis-profiles.md` — registry-cascade-first, component reuse table, token findings) to analyze adjacent UI components, layout patterns, and design tokens. Report file paths and structure.
 
 ### Step C — Generate 3 Options (GENERATOR)
 

package/framework/.claude/workflows/new-card-review.js

@@ -274,7 +274,7 @@ if (baselinePaths.length) {
   log(`Baseline: reusing ${baselinePaths.length} per-card baseline file(s).`)
 } else {
   const arch = await agent(
-    `You are grounding a post-implementation code review. Map the EXISTING architecture, critical patterns, and high-risk code paths relevant to this wave's changed files, so downstream reviewers can spot regressions.\n\n${waveBrief}\n\nReturn a concise baseline (key modules, their contracts, the regression-prone seams touched by this diff). Do not review the changes yet.`,
+    `PROFILE=baseline — resolve your analysis profile per agents/analysis-profiles.md (Grep "### PROFILE: baseline", Read only that section; v4.94.0). You are grounding a post-implementation code review. Map the EXISTING architecture, critical patterns, and high-risk code paths relevant to this wave's changed files, so downstream reviewers can spot regressions.\n\n${waveBrief}\n\nReturn a concise baseline (key modules, their contracts, the regression-prone seams touched by this diff). Do not review the changes yet.`,
     { label: 'arch-baseline', phase: 'Baseline', agentType: 'codebase-architect',
       schema: { type: 'object', required: ['baseline'], additionalProperties: false, properties: { baseline: { type: 'string' } } } }
   )

package/framework/.claude/workflows/new-final-review.js

@@ -265,7 +265,7 @@ if (baselinePaths.length) {
   log(`Baseline: reusing ${baselinePaths.length} per-card baseline file(s).`)
 } else {
   const arch = await agent(
-    `You are grounding a post-implementation code review. Map the EXISTING architecture, critical patterns, and high-risk code paths relevant to this batch's changed files, so downstream reviewers can spot regressions.\n\n${scopeBrief}\n\nReturn a concise baseline (the key modules, their contracts, and the regression-prone seams touched by this diff). Do not review the changes yet.`,
+    `PROFILE=baseline — resolve your analysis profile per agents/analysis-profiles.md (Grep "### PROFILE: baseline", Read only that section; v4.94.0). You are grounding a post-implementation code review. Map the EXISTING architecture, critical patterns, and high-risk code paths relevant to this batch's changed files, so downstream reviewers can spot regressions.\n\n${scopeBrief}\n\nReturn a concise baseline (the key modules, their contracts, and the regression-prone seams touched by this diff). Do not review the changes yet.`,
     { label: 'arch-baseline', phase: 'Baseline', agentType: 'codebase-architect',
       schema: { type: 'object', required: ['baseline'], additionalProperties: false, properties: { baseline: { type: 'string' } } } }
   )

package/framework/.claude/workflows/new2.js

@@ -552,8 +552,12 @@ async function runCard(cardId, cardPath) {
   let arch = null
   try {
     arch = await agentSafe(
-      `You are the Phase-1 context retriever for card ${cardId} (per ${REF}/implement.md Phase 1 step 3 / 5b). cd into the worktree ${sharedCtx.worktreePath}.\n\n${cardBrief}\n\n` +
-        `Explore the codebase exactly as your system prompt mandates for this card's scope (requirements + files_likely_touched: ${JSON.stringify(node.filesLikelyTouched || [])}). Write your COMPLETE untruncated findings (file paths, type signatures, patterns, high-risk paths) to ${baselinePath} — refresh it if a stale copy exists. The owner agent and the per-card reviewers will Read that file; keep your structured return MINIMAL.\n\n` +
+      `You are the Phase-1 context retriever for card ${cardId} (per ${REF}/implement.md Phase 1 step 3 / 5b). cd into the worktree ${sharedCtx.worktreePath}.\n\n` +
+        // Analysis profile (v4.94.0 — implement.md step 3 parallel): deterministic from the
+        // pre-flight hasMockup bit, mirroring the mockup-first build routing (§6a). SSOT:
+        // agents/analysis-profiles.md § 3 caller routing table.
+        `PROFILE=${node.hasMockup ? 'ui' : 'feature'} OUTPUT=terse — resolve your analysis profile per agents/analysis-profiles.md (Grep "### PROFILE: ${node.hasMockup ? 'ui' : 'feature'}", Read only that section + its cited shared blocks).\n\n${cardBrief}\n\n` +
+        `Explore the codebase exactly as your system prompt + profile mandate for this card's scope (requirements + files_likely_touched: ${JSON.stringify(node.filesLikelyTouched || [])}). Write your COMPLETE untruncated findings (file paths, type signatures, patterns, high-risk paths) to ${baselinePath} — refresh it if a stale copy exists. The owner agent and the per-card reviewers will Read that file; keep your structured return MINIMAL.\n\n` +
         `Also report missingPaths: every path in files_likely_touched that does NOT exist in the worktree (factual ls/test check — no judgement). Return: { ok, missingPaths:[...], note }`,
       { label: `architect:${cardId}`, phase: 'Implement', agentType: 'codebase-architect',
         schema: { type: 'object', required: ['ok'], additionalProperties: true, properties: { ok: { type: 'boolean' }, missingPaths: { type: 'array', items: { type: 'string' } }, note: { type: 'string' } } } }

package/framework/agents/analysis-profiles.md

@@ -0,0 +1,286 @@
+# Analysis Profiles — the codebase-architect investigation contract
+
+**Purpose**: `codebase-architect` is the single read-only analyst every surface delegates
+to, but "understand the codebase" is not one job — grounding an implementer, tracing a
+bug, measuring blast radius, loading planning context, and inventorying UI primitives
+need different retrieval plans and different output blocks. This module is the **single
+SSOT of those plans**. The agent body carries the shared engine (canonical-router-first,
+tiered code search, read-size discipline, memory); each profile here scopes WHICH parts
+of that engine run, what to read/skip, and which output blocks the caller receives.
+
+This is the retrieval-side twin of `effort-protocol.md` (how deeply to reason) and
+`return-contract-protocol.md` (how compactly to report). Same mechanism as `OUTPUT=terse`
+(v4.49.0): a prompt-level token, zero new config keys, zero runtime dependency.
+
+**Consumers**: `codebase-architect` (dispatcher — reads its matching profile section at
+spawn), every caller that spawns it (`/new` implement.md, `new2.js` B7, the review
+workflows, `/prd`, `/prd-add`, `/bug`, `/ui-design`, `/ds-handoff`, `/codexreview`,
+`plan-auditor`, `/e2e-review`), and `context-primer` (maps its task types onto profiles
+instead of restating search strategy).
+
+---
+
+## 1. Contract
+
+- **Token**: the invoking prompt contains `PROFILE=<feature|bug|impact|discovery|ui|baseline>`
+  (one token, anywhere in the prompt — same parsing style as `OUTPUT=terse` and
+  `effort=<level>`). Composable with `OUTPUT=terse` and an explicit token budget.
+- **Dispatch (agent side)**: parse the token FIRST. Then Grep this file for the heading
+  `### PROFILE: <name>` and Read ONLY that section (plus any `§ Shared block` it cites) —
+  never read this module end-to-end.
+- **No token → deterministic inference**, in this exact priority order (first match wins):
+  1. prompt names a mockup / `links.design` / `component_bindings` / design-system
+     registry / tokens → `ui`
+  2. prompt asks blast-radius / affected surface / "what depends on" / refactor scope →
+     `impact`
+  3. prompt reports an error / crash / regression / "non funziona" → `bug`
+  4. prompt grounds a post-implementation review over a diff/batch → `baseline`
+  5. prompt loads context for planning / PRD / a question about docs or product intent →
+     `discovery`
+  6. otherwise → `full` (legacy monolith behavior: run every protocol, all output blocks).
+- **Caller side**: prefer the explicit token — inference is the fallback, not the design.
+  The routing table in § 3 is normative for framework callers.
+- **Invariants that hold for EVERY profile** (they live in the agent body, not here):
+  read-only role boundary; Return Contract (COMPACT); canonical-router-first engine;
+  anti-flail gate; read-size discipline; `## Canonical Evidence` block in every analysis;
+  Hot-File Map on terse output for in-scope files > 800 lines; memory hygiene.
+- **Precedence**: an explicit instruction in the invoking prompt (e.g. a caller-supplied
+  token budget or an extra output field) overrides the profile default. A profile never
+  overrides the role boundary or the Return Contract.
+
+## 2. Profiles
+
+### PROFILE: feature
+
+- **Question**: what exists in this area, which patterns must a change follow, what can
+  be reused, where are the risks?
+- **Callers**: `/new` implement.md Phase 1 step 3 + `new2.js` B7 (cards WITHOUT a
+  mockup), ad-hoc pre-implementation grounding, `hybrid-ml-architect` /
+  `security-reviewer` / `legal-counsel-gdpr` Phase-0 grounding.
+- **Retrieval**: full engine — canonical router → git log (if thin) → structural tier
+  (graph/LSP per `code-search-protocol.md` / `code-graph-protocol.md`) → targeted reads.
+- **Run**: § Shared block: Reuse Analysis · § Shared block: Documentation Reliability
+  Scan (when docs are evidence).
+- **Skip**: nothing engine-side; skip the UI cascade unless the scope touches components
+  (then the caller should have routed `ui`).
+- **Output blocks**: `## Reuse Analysis` + `## Canonical Evidence` + affected-code rows
+  (`path:line — symbol — pattern/role`) + high-risk rows + `## Hot-File Map` + `totals:`.
+- **Budget**: ≤ 20K tokens.
+
+### PROFILE: bug
+
+- **Question**: what is the code path from entry point to failure, and what changed
+  recently on it?
+- **Callers**: `/bug` Phase 0; context-primer `task_type: bug-fix`.
+- **Retrieval**: entry-point location (structural tier first for the failing
+  symbol/handler) → trace the path → `git log --oneline -15 -- <suspect paths>` for
+  recent-change candidates → targeted range reads of suspects only.
+- **Run**: nothing extra — speed is the point.
+- **Skip**: § Reuse Analysis (no component discovery in a bug hunt) · architecture docs
+  and ADRs unless the failure is a contract violation · broad domain reads.
+- **Output blocks**: `## Canonical Evidence` + a **code-path map** (ordered
+  `path:line — step` rows from entry to failure) + a **recent-change list**
+  (`sha — path — why suspect`) + `## Hot-File Map` for any suspect file > 800 lines +
+  `totals:`.
+- **Budget**: ≤ 15K tokens.
+
+### PROFILE: impact
+
+- **Question**: if X changes, what breaks — which files, contracts, and consumers are in
+  the blast radius?
+- **Callers**: `plan-auditor` FULL-mode grounding; `/prd` Step 2 ISA (Impact Surface
+  Analysis); `/prd-add` PATCH mode (affected dimensions only); `/e2e-review` route/
+  primitive reverse lookup; refactor scoping; context-primer `task_type: refactor`.
+- **Retrieval**: **structural tier is PRIMARY** — `graphify affected`/`path` when
+  `features.has_code_graph: true`, LSP `find-references` when `has_lsp_layer: true`,
+  else exports/imports reads per the engine's anti-flail rule. Router only to resolve
+  the owning contract docs of the affected surface.
+- **Run**: § Shared block: Documentation Reliability Scan only for the contract docs you
+  cite.
+- **Skip**: § Reuse Analysis · full-file reads of dependents (list them, read only the
+  coupling site) · design rationale.
+- **Output blocks**: `## Canonical Evidence` + an **affected-surface table**
+  (`path:line — dependent symbol — direction (uses/used-by) — contract at risk`) +
+  transitive one-hop notes + `totals:`.
+- **Budget**: ≤ 15K tokens.
+
+### PROFILE: discovery
+
+- **Question**: what context does a planner (or a human asking a question) need —
+  constraints, canonical sources, current state — before any decision?
+- **Callers**: `context-primer` (`task_type: new-feature | query | doc-update`); `/prd`
+  discovery-loop targeted questions.
+- **Retrieval**: docs-first — canonical router → matched reference/ADR sections →
+  backlog cards → wiki overlay (when `features.has_wiki_overlay: true`, verify wiki
+  claims against canonicals) → agent memory. **Source code only to verify a
+  runtime-sensitive claim** (auth pattern, API contract, current schema).
+- **Task-type deltas** (passed through by context-primer): `query`/`doc-update` → docs +
+  memory only, skip source entirely; `new-feature` → also map the domain's existing
+  patterns (2-3 exemplar `path:line` anchors) and relevant ADRs.
+- **Run**: § Shared block: Documentation Reliability Scan (docs ARE the evidence here —
+  mandatory).
+- **Skip**: § Reuse Analysis · code-wide scans · reading any `${paths.prd_dir}` /
+  `${paths.references_dir}` file end-to-end (route via the registry, read sections).
+- **Output blocks**: `## Canonical Evidence` + § Reliability Scan block + constraints-
+  first summary (the caller may impose its own envelope, e.g. context-primer's XML —
+  honor it verbatim).
+- **Budget**: ≤ 15K tokens.
+
+### PROFILE: ui
+
+- **Question**: which registry primitives/tokens/patterns serve this UI scope, what is
+  reused vs variant vs genuinely new, and what does the current implementation state
+  look like — **answered from the registry and code, never from pixels**.
+- **Callers**: `/new` implement.md + `new2.js` B7 (cards WITH a mockup —
+  `links.design`/`links.design_src` non-empty); `/ui-design` Step 3 adjacent-UI
+  analysis; `/ds-handoff` entity/field probe; context-primer UI-keyword branch.
+- **Retrieval**: § Shared block: UI Resolution Path is the PRIMARY route — INDEX.md
+  (thin router) → frontmatter **HEAD** of matched `components/<Name>.md` → DTCG tokens →
+  patterns. **Never read component source to learn an API its HEAD already carries**;
+  read source only for undocumented primitives or to verify a runtime-sensitive claim.
+  When `features.has_design_system: false`, degrade to
+  `${paths.references_dir}/component-registry.md` + targeted source reads.
+- **Run**: § Shared block: Reuse Analysis (component-flavored — candidates come from the
+  registry cascade, classification uses the card's `component_bindings` vocabulary
+  `reuse / reuse-variant / new` when present).
+- **Skip**: backend/data-model deep dives (one-line integration notes only) · § UI
+  boundary below.
+- **Output blocks**: `## Reuse Analysis` (component table) + `## Canonical Evidence` +
+  binding/coverage notes (`region — bound component — status`) + token findings
+  (hardcoded-value risks as `path:line — value — owning token`) + `## Hot-File Map` +
+  `totals:`.
+- **Budget**: ≤ 15K tokens.
+- **UI boundary (binding)**: this profile is **code/registry-side only**. Rendered
+  evidence — mockup images, screenshots, live routes — belongs to the multimodal
+  specialists: analysis of mockup pixels → a read-only `ui-expert` spawn (the
+  `/prd` Step 1.6.5 precedent), fidelity verdicts → the verifier trio via `/e2e-review`.
+  If the invoking prompt asks you to judge pixels, flag it as over-scoped and return the
+  code/registry map (same rule as the Role boundary for implementation asks).
+
+### PROFILE: baseline
+
+- **Question**: what is the EXISTING architecture around this diff/batch, so reviewers
+  can spot regressions?
+- **Callers**: `new-final-review.js` / `new-card-review.js` Phase Baseline (fallback
+  when no per-card baselines exist); `/codexreview` Step 1; `/new` final-review F.2
+  inline fallback.
+- **Retrieval**: diff-scoped — start from the changed-files list, resolve each file's
+  module/contract via router + structural tier; NO topic-wide exploration beyond the
+  seams the diff touches.
+- **Run**: nothing extra.
+- **Skip**: § Reuse Analysis · § Reliability Scan (cite doc freshness only if a doc
+  contradicts the code) · product-intent docs.
+- **Output blocks**: `## Canonical Evidence` + key-module map (`path — contract — why it
+  matters to this diff`) + regression-prone seams (`path:line — risk`) +
+  `## Hot-File Map` + `totals:`. Persist to the caller-named file when one is given
+  (e.g. `/tmp/arch-baseline-<CARD-ID>.md`) — persist-then-summarize per the Return
+  Contract.
+- **Budget**: ≤ 20K tokens (batch scope); ≤ 15K per single card.
+
+### PROFILE: full (fallback — no token, no inference match)
+
+Legacy monolith behavior: run the whole engine, § Reuse Analysis when the task builds or
+changes code, § Reliability Scan when docs are evidence, UI Resolution Path when the
+query concerns UI. All output blocks that apply. Budget ≤ 20K. Callers in the framework
+payload should never rely on `full` — pass a token.
+
+## 3. Caller routing table (normative for framework surfaces)
+
+| Caller | Profile |
+|---|---|
+| `/new` implement.md Phase 1 step 3 · `new2.js` B7 | `ui` if card has non-empty `links.design` OR `links.design_src` (the `hasMockup` bit), else `feature` |
+| `new-final-review.js` / `new-card-review.js` Phase Baseline · `/codexreview` Step 1 | `baseline` |
+| `plan-auditor` FULL-mode grounding spawn | `impact` |
+| `/prd` discovery-loop targeted question | `discovery` |
+| `/prd` Step 2 ISA touchpoint mapping · `/prd-add` PATCH | `impact` |
+| `/bug` Phase 0 | `bug` |
+| `/ui-design` Step 3 · `/ds-handoff` probe | `ui` |
+| `/e2e-review` route/primitive reverse lookup | `impact` |
+| `context-primer` | by task type: `bug-fix→bug` · `refactor→impact` · `new-feature/query/doc-update→discovery` · UI keywords + `has_design_system:true` → `ui` |
+
+## 4. Shared blocks
+
+### § Shared block: Reuse Analysis
+
+Run **only when a profile lists it** (feature, ui, full-when-building).
+
+1. **Identify what the task needs**: UI components, hooks, utilities, API patterns, data
+   flows.
+2. **Search for existing matches**:
+   - `features.has_design_system: true` → the fastest reuse signal is the **spec HEADs**:
+     `${paths.design_system}/INDEX.md` (thin router), then the frontmatter HEAD of
+     candidate `components/<Name>.md` (schema: `component-manifest-schema.md`). Prefer
+     this over Grep.
+   - Else `${paths.references_dir}/component-registry.md` (relevant table section only).
+   - Grep only for 2-3 specific component names, never broad semantic sweeps.
+3. **Classify each candidate**: **Direct reuse** (works as-is) · **Refactor & reuse**
+   (≥70% fit — generalize via props/config) · **Extract & share** (logic duplicated in
+   2+ places) · **No match** (build new — document why).
+4. **Agent memory**: read `.claude/agent-memory/codebase-architect/shared-components.md`
+   only when the task involves UI components; update it with new discoveries.
+
+Output format (emit in every analysis whose profile runs this block; if nothing is
+reusable, emit the section with "No reusable components found — all new code required"
+and why):
+
+```markdown
+## Reuse Analysis
+
+### Reusable Components Found
+| Need | Existing Component | Path | Classification | Action |
+|------|-------------------|------|----------------|--------|
+
+### No Match (Must Build New)
+- [component/pattern]: [why nothing existing fits]
+
+### Refactoring Opportunities
+- [duplication worth consolidating, even if adjacent to this task]
+```
+
+### § Shared block: UI Resolution Path
+
+The design-system resolution cascade (paths are project-specific; this order is the
+convention — the protocol SSOT is `design-system-protocol.md`):
+
+1. `${paths.design_system}/INDEX.md` — thin router (name → source → purpose → spec)
+2. `${paths.design_system}/components/<Name>.md` — **frontmatter HEAD first**
+   (props/variants/composes/token_bindings/a11y — schema in
+   `component-manifest-schema.md`); prose body only for rationale. Never read source to
+   learn an API the HEAD carries.
+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` — shared-component inventory
+
+### § Shared block: Documentation Reliability Scan
+
+Run when a profile lists it AND documentation is part of the evidence set:
+
+1. **Registry coverage** — the feature exists in `${paths.references_dir}/ssot-registry.md`;
+   backlog/PRD-only → report `REGISTRY_GAP`
+2. **Freshness markers** — `Last updated`/change-log markers vs `git log -1` on the doc
+3. **Link quality** — markdown links vs raw paths; path-heavy PRDs lower retrieval quality
+4. **Retrieval risk** — doc exceeds repo thresholds (reference >400 lines, API >800,
+   PRD/spec >800) → headings + targeted sections, never a full read
+5. **Router fit** — registry maps the feature to a canonical doc → prefer that route
+
+Emit 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: ...]
+```
+
+---
+
+**Codex parity: portable.** The token is prompt-level; this module ships in the bulk-
+symlinked `agents/` payload both runtimes read; the agent body (dispatcher) transpiles to
+`.codex/agents/codebase-architect.toml` unchanged. No new config key — profiles gate on
+flags that already exist (`has_design_system`, `has_code_graph`, `has_lsp_layer`,
+`has_wiki_overlay`), so the schema-change propagation rule does not apply.

package/framework/agents/index.md

@@ -13,7 +13,7 @@ Route agents to the right module with minimal reading.
 ### Documentation Routing
 
 - **MANDATORY pre-read for any skill/agent that touches project-specific paths, identity, stack, or feature toggles** -> read `agents/project-context.md`. Skills consult `baldart.config.yml` + `.baldart/overlays/<skill>.md` instead of hard-coded paths; missing keys MUST be asked, never assumed.
-- If needing to understand codebase structure, existing patterns, or architecture before planning -> MUST invoke `codebase-architect` agent (via Task tool) first; do not proceed without architectural understanding.
+- If needing to understand codebase structure, existing patterns, or architecture before planning -> MUST invoke `codebase-architect` agent (via Task tool) first, passing the matching `PROFILE=<feature|bug|impact|discovery|ui|baseline>` token per `agents/analysis-profiles.md` (§ 3 routing table); do not proceed without architectural understanding.
 - If searching for a function/type/symbol (identifier-shaped query, not free text) and `features.has_lsp_layer: true` -> read `agents/code-search-protocol.md` and prefer LSP `find-references` / `go-to-definition` over Grep. Falls back to Grep when LSP is unavailable or the query is textual.
 - If the question is STRUCTURAL / RELATIONAL (what connects X to Y, blast-radius/impact, clusters) and `features.has_code_graph: true` -> read `agents/code-graph-protocol.md` and prefer the Graphify code graph (`graphify query`/`path`/`explain`/`affected`) over LSP/Grep. Falls back silently to LSP -> Grep -> Git when the graph is unavailable.
 - If touching API endpoints or request/response shape -> read `agents/api-contracts.md` and `${paths.references_dir}/api/index.md` (then specific API module for your domain).
@@ -71,6 +71,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/skills-mapping.md`
 - `agents/llm-wiki-methodology.md` — LLM wiki overlay methodology (manual + scheduled maintenance; since v2.0.0)
 - `agents/project-context.md` — Project context protocol: `baldart.config.yml` + overlays + missing-key handling (since v3.0.0)
+- `agents/analysis-profiles.md` — Analysis-profile contract for `codebase-architect`: the `PROFILE=<feature|bug|impact|discovery|ui|baseline>` prompt token, per-profile retrieval plans + output blocks + budgets, caller routing table, shared blocks (Reuse Analysis · UI Resolution Path · Documentation Reliability Scan). The retrieval-side twin of `effort-protocol.md` + `return-contract-protocol.md` (since v4.94.0)
 - `agents/code-search-protocol.md` — Retrieval hierarchy for code search: LSP → Grep → Git (since v3.10.0, gated on `features.has_lsp_layer`)
 - `agents/code-graph-protocol.md` — Structural/relational retrieval via the Graphify code knowledge graph (since v4.21.0, gated on `features.has_code_graph`)
 - `agents/toolchain-protocol.md` — Mechanical-gate command resolution (lint/format/typecheck/test/build/audit) from `toolchain.commands.*` with silent project-standard fallback (since v4.41.0, gated on `features.has_toolchain`)

package/framework/agents/skills-mapping.md

@@ -101,6 +101,10 @@ which enforce the contract above.
 - "/cont [keywords]"
 - Auto-invoked by `/prd` at kickoff
 
+**Note**: the skill is the interactive *channel* to `codebase-architect`, not a
+competing methodology — it detects the task type and passes the matching
+`PROFILE=<bug|impact|discovery|ui>` token per `agents/analysis-profiles.md` (§ 3).
+
 ### new
 
 **When to use**:

package/framework/templates/primitives/AGENTS.CHANGELOG.md

@@ -4,6 +4,16 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Questo è il changelog INTERNO dello skeleton spedito (`primitive_version`), separato dal
 file `AGENTS.md` generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.4.0 — 2026-07-02
+
+- **Analysis-profile vocabulary on the understand-before-implement MUST**: the
+  `codebase-architect` invocation now names the six profiles
+  (`PROFILE=feature|bug|impact|discovery|ui|baseline`) and cites
+  `agents/analysis-profiles.md` as the contract SSOT — "understand the codebase" is
+  scoped to the job at hand (grounding / failure tracing / blast radius / planning
+  context / design-system inventory / review baseline) instead of one monolithic
+  exploration. Cross-tool: the token is prompt-level, identical on Claude and Codex.
+
 ## 1.3.0 — 2026-07-01
 
 - **Plan-review gate promoted to the cross-tool SSOT**: MUST have any non-trivial plan

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.3.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.4.0
      This is the SHIPPED SKELETON. The writer (src/utils/root-primitives.js) strips
      this banner, resolves every {{ slot }} / {{> partial }} / {{#flag}} from
      baldart.config.yml (+ package.json/README), merges .baldart/overlays/AGENTS.md,
@@ -26,8 +26,13 @@ mechanics — this file remains the single source of truth for the protocol.
 - MUST treat `AGENTS.md` as authoritative for agent rules.
 - MUST understand the codebase before planning/implementing — invoke `codebase-architect`
   (Claude Code: Task tool `subagent_type: codebase-architect`; Codex: the custom agent by
-  name at `.codex/agents/codebase-architect.toml`). Only if NEITHER mechanism exists,
-  degrade explicitly to inline retrieval (code-graph → LSP → Grep) and SAY SO.
+  name at `.codex/agents/codebase-architect.toml`), passing the matching **analysis
+  profile**: `PROFILE=feature` (pre-implementation grounding) · `bug` (failure-path
+  tracing) · `impact` (blast radius / refactor scope) · `discovery` (planning / question
+  context) · `ui` (design-system / component scope) · `baseline` (review grounding over a
+  diff). Contract + per-profile scoping: `agents/analysis-profiles.md`. Only if NEITHER
+  invocation mechanism exists, degrade explicitly to inline retrieval
+  (code-graph → LSP → Grep) and SAY SO.
 - MUST have any non-trivial plan reviewed BEFORE presenting it for approval — run
   `plan-auditor` + `doc-reviewer` (in parallel), incorporate their feedback, and note in the
   plan that the review gate was honored. Present the ALREADY-reviewed plan, never a raw one.

package/framework/templates/primitives/CLAUDE.CHANGELOG.md

@@ -4,6 +4,12 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Changelog INTERNO dello stub spedito (`primitive_version`), separato dal `CLAUDE.md`
 generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.2.0 — 2026-07-02
+
+- Plan Mode: the `codebase-architect` pre-plan invocation now passes the matching
+  `PROFILE=<...>` token, citing `AGENTS.md` § Non-negotiables +
+  `agents/analysis-profiles.md` (no restatement — the stub stays thin).
+
 ## 1.1.0 — 2026-07-01
 
 - Plan Mode delegation now names **both** domain agents — **code → `coder`**, **UI →

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.1.0
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.2.0
      SHIPPED SKELETON. The writer strips this banner, resolves {{ slot }}/{{#flag}} from
      baldart.config.yml, merges .baldart/overlays/CLAUDE.md, stamps a baldart-generated
      marker, and writes the result to the repo root.
@@ -16,7 +16,10 @@ SSOT, not restated here. Below are the **Claude-native mechanics only**.
 
 - Enter plan mode (`EnterPlanMode`) for any non-trivial task before writing code.
   Trivial = single-line fix / typo / obvious bug.
-- Invoke `codebase-architect` before writing the plan — never plan blind.
+- Invoke `codebase-architect` before writing the plan — never plan blind. Pass the
+  matching `PROFILE=<feature|bug|impact|discovery|ui|baseline>` token (the profile
+  vocabulary and routing live in `AGENTS.md` § Non-negotiables and
+  `agents/analysis-profiles.md` — not restated here).
 - Launch `plan-auditor` + `doc-reviewer` in parallel to review the plan, incorporate their
   feedback, and state inside the plan that the review gate was honored, BEFORE `ExitPlanMode`.
 - Wait for explicit user approval, then delegate implementation to the domain agent via the

package/package.json

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