baldart 4.92.1 → 4.94.0

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/stamp-holistic-audit.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * stamp-holistic-audit.js — deterministic writer of the `metadata.holistic_audit`
+ * provenance block on backlog cards.
+ *
+ * Why this exists (/prd gate-hygiene wave): the per-card stamp write in
+ * audit-phase.md Step 6.9.4 and its backstop in validation-phase.md Step 7 item 5b
+ * were BOTH model-driven prose — and both failed together on a real run (a whole
+ * card family shipped with zero audit trail, so `/new` re-spawned the plan-auditor
+ * on every card). A prose gate degrades under context pressure; this script makes
+ * the stamp a single deterministic operation both call sites EXECUTE.
+ *
+ * Semantics are defined in audit-phase.md § "Holistic-audit provenance stamp" —
+ * this script only mechanizes the write:
+ *   - idempotent: a card already carrying `holistic_audit` with a non-empty
+ *     `audited_commit` is left untouched;
+ *   - additive: never overwrites other `metadata` keys;
+ *   - EPIC cards are skipped (they carry `planning_session` only — card-schema.md);
+ *   - `--commit ""` is written EXPLICITLY (never omitted) so `/new` treats it as
+ *     drift and runs its own plan-auditor (the fail-safe contract).
+ *
+ * Usage:
+ *   node framework/scripts/stamp-holistic-audit.js \
+ *     --at "2026-07-02T10:00:00Z" --commit "<sha-or-empty>" \
+ *     --set "FEAT-0070-01,FEAT-0070-02" <card1.yml> [<card2.yml> ...]
+ *
+ * Exit 0 = every non-epic card carries the stamp afterwards; exit 1 = a write or
+ * parse failed (per-file errors printed). Zero-dep, node-core only.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseCardYaml, detectProfile } = require(path.join(__dirname, 'validate-card-baseline.js'));
+
+function argValue(args, flag) {
+  const i = args.indexOf(flag);
+  return i > -1 && i + 1 < args.length ? args[i + 1] : null;
+}
+
+/** True when the card text already carries holistic_audit with a non-empty audited_commit. */
+function alreadyStamped(text) {
+  const m = String(text).match(/^\s+holistic_audit:\s*$[\s\S]*?^\s+audited_commit:\s*"([^"]+)"/m);
+  return !!(m && m[1].trim() !== '');
+}
+
+/** Remove a pre-existing holistic_audit block (e.g. one with an empty commit) so the rewrite is clean. */
+function stripExistingBlock(text) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((l) => /^\s+holistic_audit:\s*$/.test(l));
+  if (start === -1) return text;
+  const indent = lines[start].length - lines[start].trimStart().length;
+  let end = start + 1;
+  while (end < lines.length) {
+    const l = lines[end];
+    if (l.trim() === '') { end++; continue; }
+    const li = l.length - l.trimStart().length;
+    if (li <= indent) break;
+    end++;
+  }
+  return lines.slice(0, start).concat(lines.slice(end)).join('\n');
+}
+
+function buildBlock(at, commit, set, childIndent) {
+  const pad = ' '.repeat(childIndent);
+  const inner = ' '.repeat(childIndent + 2);
+  const ids = set.map((s) => `"${s}"`).join(', ');
+  return [
+    `${pad}holistic_audit:`,
+    `${inner}audited_at: "${at}"`,
+    `${inner}audited_commit: "${commit}"`,
+    `${inner}audited_set: [${ids}]`,
+  ].join('\n');
+}
+
+function stampFile(file, at, commit, set) {
+  let text = fs.readFileSync(file, 'utf8');
+  let card;
+  try { card = parseCardYaml(text); } catch (e) { return { file, status: 'error', detail: `YAML parse error — ${e.message}` }; }
+  if (!card || typeof card !== 'object') return { file, status: 'error', detail: 'not a YAML mapping' };
+  if (detectProfile(card, path.basename(file)) === 'EPIC') return { file, status: 'epic-skipped' };
+  if (alreadyStamped(text)) return { file, status: 'already-stamped' };
+
+  text = stripExistingBlock(text);
+  const lines = text.split('\n');
+  const metaIdx = lines.findIndex((l) => /^metadata:\s*$/.test(l));
+  if (metaIdx > -1) {
+    // child indent = indent of the first existing metadata child, else 2 spaces
+    let childIndent = 2;
+    for (let j = metaIdx + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === '') continue;
+      const li = l.length - l.trimStart().length;
+      if (li > 0) childIndent = li;
+      break;
+    }
+    lines.splice(metaIdx + 1, 0, buildBlock(at, commit, set, childIndent));
+    text = lines.join('\n');
+  } else {
+    if (!text.endsWith('\n')) text += '\n';
+    text += `\nmetadata:\n${buildBlock(at, commit, set, 2)}\n`;
+  }
+  fs.writeFileSync(file, text);
+  // verify the write landed (the 5b "re-read one card" contract, made universal)
+  if (!alreadyStamped(fs.readFileSync(file, 'utf8')) && commit !== '') {
+    return { file, status: 'error', detail: 'post-write verification failed — stamp not found' };
+  }
+  return { file, status: 'stamped' };
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const at = argValue(args, '--at');
+  const commit = argValue(args, '--commit'); // may legitimately be "" — must still be PASSED
+  const setRaw = argValue(args, '--set');
+  const files = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--at' || args[i] === '--commit' || args[i] === '--set') { i++; continue; }
+    files.push(args[i]);
+  }
+  if (!at || commit === null || setRaw === null || !files.length) {
+    process.stderr.write('Usage: stamp-holistic-audit.js --at <iso8601> --commit <sha-or-empty> --set "ID1,ID2" <card.yml> [...]\n');
+    return 2;
+  }
+  const set = setRaw.split(',').map((s) => s.trim()).filter(Boolean).sort();
+  let failed = 0, stamped = 0, already = 0, epics = 0;
+  for (const f of files) {
+    let r;
+    try { r = stampFile(f, at, commit, set); } catch (e) { r = { file: f, status: 'error', detail: e.message }; }
+    if (r.status === 'error') { failed++; process.stdout.write(`✖ ${f}: ${r.detail}\n`); }
+    else if (r.status === 'stamped') { stamped++; process.stdout.write(`✓ ${f}: stamped\n`); }
+    else if (r.status === 'already-stamped') { already++; process.stdout.write(`· ${f}: already stamped\n`); }
+    else { epics++; process.stdout.write(`· ${f}: epic — skipped\n`); }
+  }
+  process.stdout.write(`holistic_audit provenance: ${stamped + already}/${files.length - epics} non-epic cards stamped (${stamped} written here, ${already} already present, ${epics} epic skipped)\n`);
+  return failed ? 1 : 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { stampFile, alreadyStamped, stripExistingBlock };

package/framework/scripts/validate-card-baseline.js

@@ -19,8 +19,18 @@
  *
  * Usage:
  *   node framework/scripts/validate-card-baseline.js <card.yml> [<card2.yml> ...]
+ *   node framework/scripts/validate-card-baseline.js --prd <card.yml> [...]
  * Exit 0 = all valid; exit 1 = at least one card has errors (printed per-field).
  *
+ * --prd (since the /prd gate-hygiene wave): adds the deterministic subset of the
+ * /prd validation-phase Step 6 item 0 checks, so the orchestrator EXECUTES them
+ * instead of reciting them (prose gates fail silently under context pressure):
+ *   - conditional `requirements` (PO1): child/standalone with non-empty
+ *     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.
+ *
  * Module API (for CI self-tests in scripts/check-card-baseline.js):
  *   const { validateCard, detectProfile, loadSchema, loadEnums } = require(...)
  */
@@ -349,21 +359,56 @@ function validateCard(card, { matrix, enums, filename = '' } = {}) {
   return { profile, errors };
 }
 
+// --- /prd deterministic gate additions (--prd) -------------------------------
+
+/** Scan raw YAML text for unresolved planning-ambiguity markers. */
+function scanAmbiguityMarkers(text) {
+  const out = [];
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('[NEEDS CLARIFICATION')) {
+      out.push(`line ${i + 1}: ${lines[i].trim().slice(0, 120)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * 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.
+ */
+function prdGateChecks(card, text, profile) {
+  const errors = [];
+  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)");
+  }
+  if (profile === 'EPIC' && nonEmpty(card.review_profile) && String(card.review_profile) !== 'skip') {
+    errors.push(`epic 'review_profile' must be 'skip' (got '${card.review_profile}') — trackers have no code work`);
+  }
+  for (const m of scanAmbiguityMarkers(text)) {
+    errors.push(`unresolved ambiguity marker — resolve with the user before commit: ${m}`);
+  }
+  return errors;
+}
+
 // --- CLI --------------------------------------------------------------------
 
 function main(argv) {
-  const files = argv.slice(2);
+  const args = argv.slice(2);
+  const prdMode = args.includes('--prd');
+  const files = args.filter((a) => a !== '--prd');
   if (!files.length) {
-    process.stderr.write('Usage: validate-card-baseline.js <card.yml> [<card2.yml> ...]\n');
+    process.stderr.write('Usage: validate-card-baseline.js [--prd] <card.yml> [<card2.yml> ...]\n');
     return 2;
   }
   const matrix = loadSchema();
   const enums = loadEnums();
   let failed = 0;
   for (const file of files) {
-    let card;
+    let text, card;
     try {
-      card = parseCardYaml(fs.readFileSync(file, 'utf8'));
+      text = fs.readFileSync(file, 'utf8');
+      card = parseCardYaml(text);
     } catch (e) {
       process.stdout.write(`✖ ${file}: YAML parse error — ${e.message}\n`);
       failed++;
@@ -375,6 +420,7 @@ function main(argv) {
       continue;
     }
     const { profile, errors } = validateCard(card, { matrix, enums, filename: path.basename(file) });
+    if (prdMode) errors.push(...prdGateChecks(card, text, profile));
     if (errors.length) {
       failed++;
       process.stdout.write(`✖ ${file} [${profile}] — ${errors.length} issue(s):\n`);
@@ -390,4 +436,4 @@ if (require.main === module) {
   process.exit(main(process.argv));
 }
 
-module.exports = { validateCard, detectProfile, loadSchema, loadEnums, nonEmpty, parseCardYaml };
+module.exports = { validateCard, detectProfile, loadSchema, loadEnums, nonEmpty, parseCardYaml, prdGateChecks, scanAmbiguityMarkers };

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