baldart 4.93.0 → 4.95.0

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/card-schema.md

@@ -56,7 +56,8 @@ Legend: **R** = required, present **and non-empty** · **E** = required key, val
 | `scope` | R | R | R | **never omittable** — encodes intent |
 | `scope_boundaries` | R | C | C | "Omit for standalone cards with no siblings" (`prd-card-writer.md`) |
 | `requirements` | C | R | R | EPIC tracks via AC-EPIC; CHILD/STANDALONE: faithfully derivable from AC+scope when both present — see consumer contract |
-| `acceptance_criteria` | R (AC-EPIC) | R | R | |
+| `acceptance_criteria` | R (AC-EPIC) | R | R | CHILD/STANDALONE: EARS grammar — see § "Acceptance-criteria grammar (EARS)" |
+| `ac_verification` | — | C | C | OPTIONAL map `AC-N → executable oracle` (or `manual: <check>`); authored by `/prd`, executed by `/new` Phase 2.5 — see § below |
 | `definition_of_done` | R | R | R | |
 | `depends_on` / `blocks` | E (`[]`) | E | E | |
 | `estimated_complexity` | C | R | R | |
@@ -212,6 +213,64 @@ Rules:
 - Omit any sub-field whose session id is unavailable (env var unset) rather than writing a
   placeholder.
 
+## Acceptance-criteria grammar (EARS) + per-AC oracles (since the EARS+verify wave)
+
+**Why**: a prose AC passes gates without being verifiable ("handle it correctly"), and
+prose gates get gamed (measured: visible/holdout gap +28pt per 10x code; exploit rate
+0.6→13.9% post-RL). Two complementary halves: the AC is binary BY FORM (EARS), and its
+verification is EXECUTABLE, defined at planning time.
+
+### EARS grammar (CHILD/STANDALONE `acceptance_criteria` — epic AC-EPIC roll-ups exempt)
+
+Every AC entry is `"[ ] [AC-N] <EARS clause>"` where the clause matches ONE of the five
+EARS patterns:
+
+| Pattern | Form |
+|---|---|
+| Ubiquitous | `THE SYSTEM SHALL <behavior>` |
+| Event-driven | `WHEN <trigger> THE SYSTEM SHALL <behavior>` |
+| State-driven | `WHILE <state> THE SYSTEM SHALL <behavior>` |
+| Optional-feature | `WHERE <feature is present> THE SYSTEM SHALL <behavior>` |
+| Unwanted-behavior | `IF <error condition> THEN THE SYSTEM SHALL <behavior>` |
+
+Non-regression variant: `… THE SYSTEM SHALL CONTINUE TO <existing behavior>`.
+
+- The clause body stays in the project language (`identity.language`); the EARS keywords
+  stay English — they are syntactic markers, like field names.
+- **Vague verbs are BANNED** (validator ban-list: `correttamente`, `appropriato/a`,
+  `properly`, `appropriately`, `as expected`, `gracefully`, `handle correctly`, `gestire
+  corrett*`) — name the observable behavior instead.
+- Enforced by `validate-card-baseline.js --prd` (BLOCKER) — i.e. at `/prd` authoring time
+  only. Legacy cards are never retro-blocked: `/new`'s baseline conformance (1b-iii) does
+  NOT apply the EARS check.
+
+Worked example (rewritten from a real card):
+- Before: `"[ ] [AC-2] La lista fornitori si aggiorna correttamente dopo il salvataggio"`
+- After: `"[ ] [AC-2] WHEN il salvataggio di un fornitore va a buon fine THE SYSTEM SHALL mostrare il fornitore aggiornato nella lista senza reload manuale"`
+
+### `ac_verification` — per-AC executable oracle (OPTIONAL map)
+
+```yaml
+ac_verification:
+  AC-1: "npm run test -- --grep 'supplier hub layout'"
+  AC-2: "grep -q 'useSupplierList' src/app/settings/suppliers/page.tsx"
+  AC-3: "manual: verifica visiva dello stato empty su viewport 375px"
+```
+
+- **Authoring** (`prd-card-writer`): a command is written ONLY if verified to exist — an
+  npm script in `package.json`, a command in `toolchain.commands.*`, a cited test file
+  that exists. NEVER invent commands (same class as the Field Grounding Rule). Not
+  automatable → explicit `manual: <what a human checks>`.
+- **Consumption** (`/new` Phase 2.5 completeness check — the AC-verification owner): an AC
+  with a non-`manual:` oracle is verified by EXECUTING it; the exit status is the primary
+  evidence. Judgment covers only `manual:` oracles and oracle-less ACs. (`qa-sentinel` is
+  deliberately NOT the consumer — AC verification is out of its scope by contract.)
+- **Relation to `validation_commands`**: that field stays the card-level suite;
+  `ac_verification` is the per-AC mapping. The validator WARNs when a non-manual oracle
+  is absent from `validation_commands` (drift guard between the two).
+- **Enforcement is WARN-first** (the `--prd` validator warns on missing entries for cards
+  with code-testable outputs); any hard gate comes only after telemetry on real runs.
+
 ## Writer contract
 
 The canonical writer is the `prd-card-writer` agent. It emits the full baseline for the

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/scripts/validate-card-baseline.js

@@ -29,7 +29,11 @@
  *     acceptance_criteria + scope MUST have non-empty requirements;
  *   - epic `review_profile` must be `skip`;
  *   - `[NEEDS CLARIFICATION: …]` ambiguity markers in the raw YAML are BLOCKERS —
- *     a card ships only when every planning ambiguity has been resolved.
+ *     a card ships only when every planning ambiguity has been resolved;
+ *   - EARS grammar on child/standalone acceptance_criteria (5 patterns + vague-verb
+ *     ban-list) — BLOCKER; epics exempt. SSOT: card-schema.md § "Acceptance-criteria
+ *     grammar (EARS)";
+ *   - `ac_verification` per-AC oracle coverage — WARN-only (never fails the run).
  *
  * Module API (for CI self-tests in scripts/check-card-baseline.js):
  *   const { validateCard, detectProfile, loadSchema, loadEnums } = require(...)
@@ -373,12 +377,30 @@ function scanAmbiguityMarkers(text) {
   return out;
 }
 
+// EARS grammar — SSOT: card-schema.md § "Acceptance-criteria grammar (EARS)".
+// Keywords are English syntactic markers; the clause body may be any language.
+const EARS_PATTERNS = [
+  /^THE SYSTEM SHALL .+/,
+  /^WHEN .+ THE SYSTEM SHALL .+/,
+  /^WHILE .+ THE SYSTEM SHALL .+/,
+  /^WHERE .+ THE SYSTEM SHALL .+/,
+  /^IF .+ THEN THE SYSTEM SHALL .+/,
+];
+const VAGUE_VERB_RE = /(correttamente|appropriat[oa]|properly|appropriately|as expected|gracefully|handle correctly|gestire corrett)/i;
+
+/** "[ ] [AC-3] WHEN … THE SYSTEM SHALL …" → { id: 'AC-3', clause: 'WHEN … …' } (null if unparseable) */
+function parseAcEntry(entry) {
+  const m = String(entry).match(/^\s*\[[ xX]?\]\s*\[(AC-\d+)\]\s*(.+)$/);
+  return m ? { id: m[1], clause: m[2].trim() } : null;
+}
+
 /**
  * The deterministic subset of /prd validation-phase Step 6 item 0 (see file header).
- * Returns string[] errors. `text` is the raw YAML (marker scan), `card` the parsed map.
+ * Returns { errors, warnings }. `text` is the raw YAML (marker scan), `card` the parsed map.
  */
 function prdGateChecks(card, text, profile) {
   const errors = [];
+  const warnings = [];
   if (profile !== 'EPIC' && nonEmpty(card.acceptance_criteria) && nonEmpty(card.scope) && !nonEmpty(card.requirements)) {
     errors.push("has acceptance_criteria + scope but no 'requirements' — emit requirements (faithful restatement of AC + scope) before commit (PO1)");
   }
@@ -388,7 +410,37 @@ function prdGateChecks(card, text, profile) {
   for (const m of scanAmbiguityMarkers(text)) {
     errors.push(`unresolved ambiguity marker — resolve with the user before commit: ${m}`);
   }
-  return errors;
+  // EARS grammar + vague-verb ban (child/standalone only; epic AC-EPIC roll-ups exempt)
+  if (profile !== 'EPIC' && Array.isArray(card.acceptance_criteria)) {
+    for (const entry of card.acceptance_criteria) {
+      const ac = parseAcEntry(entry);
+      if (!ac) continue; // malformed entry shape is the matrix/consumer contract's concern
+      if (VAGUE_VERB_RE.test(ac.clause)) {
+        errors.push(`${ac.id} uses a banned vague verb — name the observable behavior (card-schema.md § EARS): "${ac.clause.slice(0, 90)}"`);
+      } else if (!EARS_PATTERNS.some((re) => re.test(ac.clause))) {
+        errors.push(`${ac.id} is not an EARS clause (THE SYSTEM SHALL / WHEN|WHILE|WHERE … THE SYSTEM SHALL / IF … THEN THE SYSTEM SHALL): "${ac.clause.slice(0, 90)}"`);
+      }
+    }
+    // ac_verification coverage — WARN-only (enforcement is data-driven, never a blocker here)
+    const av = card.ac_verification;
+    const hasCodeOutputs = nonEmpty(card.files_likely_touched);
+    if (!nonEmpty(av)) {
+      if (hasCodeOutputs) warnings.push("no 'ac_verification' map — consider per-AC executable oracles (or 'manual: …') per card-schema.md § ac_verification");
+    } else if (typeof av === 'object' && !Array.isArray(av)) {
+      const vcText = JSON.stringify(card.validation_commands || []);
+      for (const entry of card.acceptance_criteria) {
+        const ac = parseAcEntry(entry);
+        if (!ac) continue;
+        const oracle = av[ac.id];
+        if (oracle == null || String(oracle).trim() === '') {
+          warnings.push(`ac_verification has no entry for ${ac.id}`);
+        } else if (!/^manual:/i.test(String(oracle)) && !vcText.includes(String(oracle).slice(0, 40))) {
+          warnings.push(`${ac.id} oracle is not in validation_commands (drift guard): "${String(oracle).slice(0, 60)}"`);
+        }
+      }
+    }
+  }
+  return { errors, warnings };
 }
 
 // --- CLI --------------------------------------------------------------------
@@ -420,7 +472,12 @@ function main(argv) {
       continue;
     }
     const { profile, errors } = validateCard(card, { matrix, enums, filename: path.basename(file) });
-    if (prdMode) errors.push(...prdGateChecks(card, text, profile));
+    let warnings = [];
+    if (prdMode) {
+      const g = prdGateChecks(card, text, profile);
+      errors.push(...g.errors);
+      warnings = g.warnings;
+    }
     if (errors.length) {
       failed++;
       process.stdout.write(`✖ ${file} [${profile}] — ${errors.length} issue(s):\n`);
@@ -428,6 +485,7 @@ function main(argv) {
     } else {
       process.stdout.write(`✓ ${file} [${profile}]\n`);
     }
+    for (const w of warnings) process.stdout.write(`    ⚠ ${w}\n`);
   }
   return failed ? 1 : 0;
 }

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.95.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"