baldart 4.92.1 → 4.94.0

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

@@ -589,17 +589,34 @@ user's own folder outside the worktree — never modify or clean it; only read.
 
 Then continue to Step 1.6.5 with the selected subset.
 
-### 1.6.5 — Mockup analysis (MANDATORY before Discovery)
-
-Analyze ALL provided mockups (visual analysis for chat images, Read for copied files
-that are textual like HTML/SVG). Populate `## UI Design` in the state file using the
-**Mockup analysis schema** (see appendix at the end of this file).
-
-When `features.has_design_system: true`, BLOCKING reads of `${paths.design_system}/INDEX.md`
-and `${paths.design_system}/tokens-reference.md` apply BEFORE running the alignment
-check — same protocol as Step 3 (UI Design). Flag every hardcoded value (hex / shadow /
-radius / spacing) that conflicts with a known token as a violation in
-`mockup_analysis.design_system_alignment.violations[]`.
+### 1.6.5 — Mockup analysis (MANDATORY before Discovery — DELEGATED, mockup bytes never in the orchestrator)
+
+**HARD RULE — the orchestrator MUST NOT Read the mockup files** (images OR HTML/SVG
+bundles). A decoded mockup read in the main context rides EVERY subsequent
+full-window API call for the rest of the run (measured on a real session: ~208KB
+dragged through the cache for ~300 events). The only exception is a mockup pasted
+directly in chat as an image — that is already in context; analyze it inline.
+
+For all on-disk mockups, **spawn ONE `ui-expert` subagent in read-only analysis
+mode** with this brief:
+- the mockup file paths (`mockups.canonical_paths[]`) — the agent Reads them in ITS
+  context (it is multimodal: images render, HTML is read as text);
+- the schema to fill: instruct it to open THIS file
+  (`references/discovery-phase.md`) and read ONLY the section
+  `## Appendix — Mockup analysis schema` (Grep the heading, Read from that offset);
+- when `features.has_design_system: true`: the paths of
+  `${paths.design_system}/INDEX.md` and `${paths.design_system}/tokens-reference.md`
+  (BLOCKING reads for the agent — same protocol as Step 3), with the instruction to
+  flag every hardcoded value (hex / shadow / radius / spacing) that conflicts with a
+  known token as a violation in `mockup_analysis.design_system_alignment.violations[]`;
+- **ROLE BOUNDARY**: analysis only — no code, no file writes, no Task spawns. Its
+  final message is the filled `mockup_analysis` YAML and NOTHING else (COMPACT
+  return contract).
+
+The orchestrator persists the returned YAML into `## UI Design` in the state file
+verbatim. If the agent's YAML is malformed, re-spawn once with the error; on a
+second failure, fall back to inline analysis (and say so — the fallback is visible,
+never silent).
 
 ### 1.6.6 — Output and handoff to Discovery
 
@@ -681,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
@@ -763,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/references/validation-phase.md

@@ -6,15 +6,26 @@
 
 Mark task 5 as `in_progress`.
 
-0. **Agent Specialization Audit (runs FIRST, blocks if any failure)** — for each generated child card (epics are skipped):
+0. **Agent Specialization Audit (runs FIRST, blocks if any failure)** — two layers:
 
-   a. **`owner_agent` enum check (BLOCKING)** — read the `owner_agent` field. It MUST equal one of:
-      ```
-      coder | ui-expert | plan | visual-designer | motion-expert
-      ```
-      Empty string, missing field, `claude`, or any other value = **BLOCKER**.
-      Message to the user: `"Card <ID> has owner_agent: '<value>' — must be one of {coder, ui-expert, plan, visual-designer, motion-expert}. Fix the card YAML before commit."`
-      Halt the audit. No subsequent checks run on a card that fails this gate.
+   **0-i. Deterministic gate — EXECUTED, never recited (BLOCKING).** Run the framework validator in `/prd` mode on EVERY generated card (epics included — it is profile-aware):
+
+   ```bash
+   node .framework/framework/scripts/validate-card-baseline.js --prd \
+     "$WORKTREE_PATH/${paths.backlog_dir}"/FEAT-XXXX-*.yml
+   ```
+   (resolve the script path for your install; only if it is genuinely unreachable, fall back to reciting the checks below — and say so explicitly in the audit log).
+
+   Exit 1 = **BLOCKER**: print the per-field errors verbatim, fix the card YAML, re-run until exit 0. No subsequent checks run on a card while it fails this gate. The script covers deterministically:
+   - **`owner_agent` enum** — must be one of `{coder, ui-expert, plan, visual-designer, motion-expert}` (empty/missing/`claude` = blocker);
+   - **`review_profile` enum + epic `skip`** — `skip|light|balanced|deep`; missing/empty = blocker (the card-writer must compute it via `prd-card-writer.md § Rule C`); epics MUST be `skip`;
+   - **conditional `requirements` presence (PO1)** — a child/standalone card with non-empty `acceptance_criteria` + `scope` MUST carry `requirements` (a fresh `/prd` card without them shifts a measured ~3–4M-token back-fill into `/new`'s orchestrator — see `card-schema.md` § "Authoring completeness invariants");
+   - **unresolved `[NEEDS CLARIFICATION: …]` markers** — a card carrying a planning ambiguity is NOT implementable. Resolve each marker (with the user via `AskUserQuestion` when it needs a human answer, or from Discovery/PRD material when it does not), edit the card, re-run;
+   - the universal field-state matrix + remaining enums (`card-schema.md`).
+
+   **Why executed and not recited:** the prose version of this gate has already failed silently on a real run (a whole card family shipped with zero audit trail). A recited check degrades under context pressure; an executed one cannot.
+
+   **0-ii. Semantic checks (the model reads the cards — not scriptable):**
 
    b. **UI-only scope heuristic (WARN — soft gate, not blocking)** — for each card with `owner_agent: ui-expert`:
       - Concatenate `scope.summary`, `requirements[]`, and `acceptance_criteria[]` into one lowercase string.
@@ -24,23 +35,7 @@ Mark task 5 as `in_progress`.
       - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.
       - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected. **[SEMANTIC — not purely deterministic]** Determining whether a marker substring is (a) inside a YAML quoted string and (b) that string contains one of the escape phrases requires contextual interpretation across multiple YAML quoting styles (single-quote, double-quote, block scalar). FP posture: when in doubt, log the WARN and let the human decide — do not suppress a WARN based on uncertain quoting analysis.
 
-   c. **`review_profile` enum check (BLOCKING)** — read the `review_profile` field on each child card. It MUST equal one of:
-      ```
-      skip | light | balanced | deep
-      ```
-      - **Missing or empty** = **BLOCKER** — the card-writer must compute it via `prd-card-writer.md § Rule C` (the SSOT mapping table). Message: `"Card <ID> has no review_profile — compute it from Rule C (skip|light|balanced|deep) before commit."`
-      - **Out-of-enum value** = **BLOCKER**. Message: `"Card <ID> has review_profile: '<value>' — must be one of {skip, light, balanced, deep}."`
-      - **Consistency WARN (soft)**: a `feature`/`enhancement` card with `review_profile: light` may violate Rule C. Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — verify against Rule C in prd-card-writer.md."` **Do NOT auto-bump the field** — `review_profile` is computed by `prd-card-writer` (Rule C); see `prd-card-writer.md` for the criteria. This is a soft gate: log the warning and surface it for human review.
-      - **Epics**: `review_profile` MUST be `skip` (trackers have no code work). Any other value = WARN, normalize to `skip`.
-
-   d. **`requirements` presence (BLOCKING — PO1)** — for each CHILD/STANDALONE card whose
-      `acceptance_criteria` AND `scope` are both non-empty, `requirements` MUST be present and
-      non-empty. A freshly authored `/prd` card with derivable material but no `requirements` is an
-      authoring miss that shifts a measured ~3–4M-token back-fill into `/new`'s orchestrator context
-      (see `card-schema.md` § "Authoring completeness invariants"). `/prd` fixes it now for free.
-      Message: `"Card <ID> has acceptance_criteria + scope but no requirements — emit requirements
-      (faithful restatement of AC + scope) before commit."` (The `/new` conditional back-fill remains
-      only as the safety net for legacy / externally-authored cards.)
+   c. **Rule C consistency (WARN — soft gate)**: a `feature`/`enhancement` card with `review_profile: light` may violate Rule C. Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — verify against Rule C in prd-card-writer.md."` **Do NOT auto-bump the field** — `review_profile` is computed by `prd-card-writer` (Rule C); see `prd-card-writer.md` for the criteria. This is a soft gate: log the warning and surface it for human review. (The enum/presence/epic-`skip` checks are handled deterministically by 0-i.)
 
    e. **files_likely_touched coverage (BLOCKING — P1/P2 closure)** — two sub-checks:
       - **⊆ coverage (P2):** every file path named in a card's `requirements` /
@@ -58,9 +53,10 @@ Mark task 5 as `in_progress`.
         no card — assign it to a card's files_likely_touched."`
       Both are SEMANTIC (path extraction from prose / ISA needs interpretation) — bias toward flagging.
 
-   **Gate**: every card has `owner_agent` AND `review_profile` in their enums, `requirements` present when
-   derivable (d), and full files_likely_touched coverage (e). WARN entries from checks (b)/(c) are noted in
-   the audit log; user may accept them after review. The (d)/(e) BLOCKERs must be fixed before commit.
+   **Gate**: the 0-i validator exits 0 on every card (enums, conditional `requirements`, zero
+   `[NEEDS CLARIFICATION]` markers) AND full files_likely_touched coverage (e). WARN entries from
+   checks (b)/(c) are noted in the audit log; user may accept them after review. The 0-i and (e)
+   BLOCKERs must be fixed before commit.
 
 1. **Field Name Audit (runs after item 0 — only when item 0 passes for a given card; skipped for cards blocked in item 0)** — for each generated card:
 
@@ -132,37 +128,37 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    (`paths.metrics` default: `docs/metrics`), which must be part of the same commit.
    Non-blocking: if it fails, log "Metrics Log: SKIPPED" in the progress bar and continue.
 
-5b. **Holistic-audit provenance backstop (BLOCKING on the STAMP, never on the PRD).**
-   The per-card stamp write in `audit-phase.md` Step 6.9.4 is model-driven and is the
-   single most-omitted step under context pressure. When it is skipped, every card
-   ships WITHOUT `metadata.holistic_audit` — and `/new` (`implement.md` Phase 1 step 4,
-   P1) + `new2` then spawn the plan-auditor on **every** card even when the batch is
-   implemented immediately after this audit (nothing changed). Step 6 is complete (its
-   gate passed), so the audit genuinely ran: this is the authoritative, deterministic
-   point to guarantee the stamp lands. **Do NOT re-derive the semantics** — reuse the
-   run-level values and the YAML block DEFINED in `audit-phase.md` § "Holistic-audit
-   provenance stamp".
-   - Recompute the three run-level values ONCE (same snippet as audit-phase.md), inside
-     `$WORKTREE_PATH`:
-     ```bash
-     HOLISTIC_AUDITED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-     HOLISTIC_AUDITED_COMMIT="$(git -C "$WORKTREE_PATH" merge-base HEAD "${git.trunk_branch}" 2>/dev/null || git -C "$WORKTREE_PATH" rev-parse "${git.trunk_branch}" 2>/dev/null || echo "")"
-     # audited_set = the sorted Step-5 child card IDs (the joint cross-card scope).
-     ```
-   - For EACH **non-EPIC** card from Step 5: if it lacks `metadata.holistic_audit` with a
-     non-empty `audited_commit`, WRITE the block (additive — never overwrite other
-     `metadata` keys). A card that already carries it (from Step 6.9.4) is untouched —
-     **idempotent**. EPIC-parent cards are excluded (they carry `planning_session` only —
-     `card-schema.md`).
-   - Re-read one backfilled card to verify the block landed. Log
-     `holistic_audit provenance: N/N cards stamped (M backfilled here)`.
+5b. **Holistic-audit provenance backstop (BLOCKING on the STAMP, never on the PRD) —
+   EXECUTED via script.** The per-card stamp write in `audit-phase.md` Step 6.9.4 is
+   model-driven and is the single most-omitted step under context pressure; when it is
+   skipped, every card ships WITHOUT `metadata.holistic_audit` — and `/new`
+   (`implement.md` Phase 1 step 4, P1) + `new2` then spawn the plan-auditor on **every**
+   card even when the batch is implemented immediately after this audit. Step 6 is
+   complete (its gate passed), so the audit genuinely ran: guarantee the stamp lands by
+   RUNNING the deterministic stamper (semantics defined in `audit-phase.md`
+   § "Holistic-audit provenance stamp" — the script only mechanizes the write):
+   ```bash
+   HOLISTIC_AUDITED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+   HOLISTIC_AUDITED_COMMIT="$(git -C "$WORKTREE_PATH" merge-base HEAD "${git.trunk_branch}" 2>/dev/null || git -C "$WORKTREE_PATH" rev-parse "${git.trunk_branch}" 2>/dev/null || echo "")"
+   # --set = the sorted Step-5 child card IDs (the joint cross-card scope), comma-separated.
+   node .framework/framework/scripts/stamp-holistic-audit.js \
+     --at "$HOLISTIC_AUDITED_AT" --commit "$HOLISTIC_AUDITED_COMMIT" \
+     --set "<ID1,ID2,...>" "$WORKTREE_PATH/${paths.backlog_dir}"/FEAT-XXXX-*.yml
+   ```
+   The script is **idempotent** (a card already stamped by Step 6.9.4 is untouched),
+   **additive** (never overwrites other `metadata` keys), skips EPIC cards (they carry
+   `planning_session` only — `card-schema.md`), and verifies its own writes. Log its
+   summary line (`holistic_audit provenance: N/N non-epic cards stamped (M written
+   here, …)`) in the audit log. Only if the script is genuinely unreachable in this
+   install, fall back to the manual per-card write per `audit-phase.md` § "Holistic-audit
+   provenance stamp" — and say so explicitly.
    **Fail-safe (unchanged contract):** the stamp is an OPTIMIZATION hint, never a
    *correctness* gate — if `HOLISTIC_AUDITED_COMMIT` resolves to `""` (git genuinely
-   unavailable), write it explicitly as `""` so `/new` treats it as drift and RUNS the
-   plan-auditor. **NEVER block or abort the PRD over the stamp**; the only thing this gate
-   blocks is shipping cards with the stamp SILENTLY absent. Runtime-neutral (bash + YAML
-   edits) → identical on Claude and Codex. The backfilled YAMLs are staged by item 6's
-   existing `FEAT-XXXX-*.yml` glob.
+   unavailable), the script writes it explicitly as `""` so `/new` treats it as drift and
+   RUNS the plan-auditor. **NEVER block or abort the PRD over the stamp**; the only thing
+   this gate blocks is shipping cards with the stamp SILENTLY absent. Runtime-neutral
+   (node + YAML edits) → identical on Claude and Codex. The backfilled YAMLs are staged
+   by item 6's existing `FEAT-XXXX-*.yml` glob.
 
 6. Stage ONLY PRD session artefacts by explicit file name (NEVER `git add .`
    or `git add -A`):

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.