baldart 3.40.0 → 4.0.0

package/framework/agents/coding-standards.md

@@ -86,6 +86,91 @@ if (error) {
 }
 ```
 
+## Reference-Aliasing Mutation Patterns
+
+> **SSOT.** This section is the canonical policy for reference-aliasing mutation
+> hazards. It is cited as the source of truth by `coder.md`
+> (§ Reference-Aliasing Mutation Hazards), `code-reviewer.md` (review checklist),
+> and `.claude/skills/new/SKILL.md` (Phase 2.5 step 5c deterministic detector +
+> Phase 3.7 trigger #6). When those files cite "§ Reference-Aliasing Mutation
+> Patterns", they mean this section.
+
+### The hazard
+
+A call site pairs a helper invocation with in-place mutation of an input
+array/object, where the helper *may return the input reference unchanged*
+(early-return, fallback, or no-op guard path). When the returned value and the
+input are the same reference, an in-place reset of the input also empties the
+"result", and the subsequent re-populate pushes nothing:
+
+```ts
+const result = filterHelper(input, ...);
+input.length = 0;        // ← wipes BOTH input AND result when result === input
+input.push(...result);   // ← pushes zero elements (result was just emptied)
+```
+
+The TypeScript signature does **not** encode reference identity — a function
+typed `(xs: T[]) => T[]` may still return its argument unchanged. Unit tests on
+the helper in isolation pass; the defect only manifests end-to-end at the call
+site. This is the class of bug that motivated this policy (a filter helper that
+returned its input reference on most paths, paired with an unguarded
+`length = 0; push(...result)` reset, collapsing a list to empty in production).
+
+### The 3-question detector
+
+Before writing — or while reviewing — any call site that mutates an input array
+in place after a helper call, answer:
+
+1. **Does the helper return an array or object?** If yes, continue.
+2. **Could the helper return the input reference unchanged** on any path?
+   Read every `return` statement in the helper body. If yes, continue.
+3. **Does the call site mutate the input in place** via `arr.length = 0`,
+   `arr.splice(0)`, `Object.assign(input, result)`, or similar? If yes — and
+   (1)+(2) were also yes — you have an alias-mutation hazard.
+
+### Required remediation (apply exactly one)
+
+- **Identity guard** at the call site:
+  ```ts
+  const result = filterHelper(input, ...);
+  if (result !== input) {
+    input.length = 0;
+    input.push(...result);
+  }
+  ```
+- **Defensive clone** before the call: `filterHelper([...input], ...)` (or
+  `input.slice()`).
+- **Refactor the helper** to always return a new array on every path
+  (preferred when the helper is exported and consumed by 2+ callers). Document
+  the immutability contract in the helper's JSDoc, e.g.
+  `@returns a NEW array — never the input reference`, so reviewers can trust it
+  without re-reading every branch.
+
+### Test contract
+
+When a guard or clone is applied, ALSO write a regression test on the **caller
+pattern** — not only on the helper in isolation. The test MUST include:
+
+- An assertion on the post-call state of the input (e.g. its length/contents
+  after the helper invocation), and
+- A **negative-control case** that documents the failure mode that would recur
+  if the guard/clone were removed.
+
+Place caller-pattern reference tests under your project's test root (the same
+path the card's `paths.*` test convention uses); cite that reference test from
+the helper's JSDoc so future editors find the contract.
+
+### Enforcement layers
+
+- **This section** — full policy + JSDoc contract + remediation menu.
+- `coder.md § Reference-Aliasing Mutation Hazards` — pre-implementation check.
+- `code-reviewer.md` review checklist — flags un-guarded patterns at review time.
+- `.claude/skills/new/SKILL.md § Phase 2.5 step 5c` — deterministic detector
+  that flags un-guarded patterns as `[ALIAS-MUTATION] BLOCKER` in
+  `## Issues & Flags`.
+- `.claude/skills/new/SKILL.md § Phase 3.7 trigger #6` — a mutation-after-helper
+  call invokes a per-card adversarial cross-model review before commit.
+
 ## Commit Message Format
 
 - **Format**: `[TYPE-XXX] Brief description` or adapt to your project convention

package/framework/agents/index.md

@@ -22,7 +22,8 @@ Route agents to the right module with minimal reading.
 - If touching design-review workflows or UI guidelines -> read `agents/design-review.md` and project-specific UI guidelines.
 - If touching architecture, auth, or tech stack -> read `agents/architecture.md`.
 - If touching workflow/process/commits/backlog -> read `agents/workflows.md`.
-- If touching testing or QA issues -> read `agents/testing.md`.
+- If touching testing or QA issues -> read `agents/testing.md` (also documents the scope-aware,
+  profile-driven test-selection strategy consumed by `qa-sentinel`).
 - If touching GitHub issues or issue workflow -> read `agents/github-issue-subagent.md`.
 - If touching terminology or naming -> read `agents/coding-standards.md`.
 - If touching env vars or scripts -> read `agents/runbook.md` and `agents/env-reference.md`.

package/framework/agents/skills-mapping.md

@@ -21,95 +21,85 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - Use wrong skill for the task
 - Rationalize not using applicable skills
 
+> This map references **only skills shipped under `framework/.claude/skills/`**.
+> Confirm a skill exists (its directory is present) before routing to it; never
+> route to a skill name that has no directory.
+
 ## Core Development Skills
 
-### brainstorming
+### prd
 
 **When to use**:
 
-- Starting new features
-- Unclear requirements
-- Multiple possible approaches
-- Design decisions needed
+- Starting a new feature (scoping + planning)
+- Unclear or multi-part requirements
+- Multiple possible approaches / design decisions needed
+- Need a PRD + UI design + atomic backlog cards before implementation
 
 **Triggers**:
 
-- "Add [feature]"
-- "Build [component]"
-- "Implement [functionality]"
-- "How should I..."
+- "Plan [feature]"
+- "Crea un PRD"
+- "Nuova funzionalità"
+- "How should I scope..."
 
-### writing-plans
+### context-primer
 
 **When to use**:
 
-- After brainstorming
-- Multi-step implementation needed
-- Complex feature development
+- Before starting work on an unfamiliar area of the codebase
+- Need existing patterns/architecture loaded silently into context
 
 **Triggers**:
 
-- After design approval
-- Before starting implementation
-- For documented requirements
+- "/cont [keywords]"
+- Auto-invoked by `/prd` at kickoff
 
-### test-driven-development
+### new
 
 **When to use**:
 
-- Implementing new features
-- Fixing bugs
-- Adding testable functionality
+- Implementing one or more approved backlog cards end-to-end
+- Multi-step implementation across a worktree with review/QA/commit per card
 
 **Triggers**:
 
-- New feature implementation
-- Bug fix with test case
-- Refactoring with tests
+- "/new CARD-IDS"
+- "Implementa le card"
+- "Esegui le card"
 
-### systematic-debugging
+### bug
 
 **When to use**:
 
 - Bug investigation
-- Test failures
-- Unexpected behavior
+- Test failures / unexpected behavior
+- Regression hunting
 
 **Triggers**:
 
+- "/bug"
 - "Fix [bug]"
-- "Why is [X] not working?"
-- Test failure analysis
+- "Non funziona" / "Why is [X] not working?"
 
 ## Code Quality Skills
 
-### code-review
+### simplify
 
 **When to use**:
 
-- Before merging
-- After major implementation
-- PR review process
+- Reducing complexity in a changed area (reuse, dedup, altitude cleanups)
+- After major implementation, before commit
 
 **Triggers**:
 
-- Feature completion
-- Before deployment
-- Pull request review
-
-### verification-before-completion
-
-**When to use**:
-
-- Claiming work is complete
-- Before marking card done
-- Before creating PR
-
-**Triggers**:
+- "/simplify"
+- "Semplifica"
+- "Reduce duplication"
 
-- "Done"
-- "Fixed"
-- "Tests passing"
+> Code review and pre-merge gates are run by the `/new` orchestration
+> (`code-reviewer` agent + `qa-sentinel` gate run) and the `/codexreview`
+> command — not by a standalone "code-review" skill. Route review tasks there.
 
 ## UI/UX Skills
 
@@ -127,19 +117,24 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Build [component]"
 - "Design [interface]"
 
-### ui-ux-pro-max
+### ui-design
 
 **When to use**:
 
-- Professional UI/UX design
-- Design system work
-- Polished interfaces
+- Designing new pages or components (context-aware mockups)
+- The `/prd` skill reaches its UI design phase
+- Redesigning existing pages / creating design options for review
 
 **Triggers**:
 
-- Design-heavy features
-- Visual refinement needed
-- Design system development
+- "/ui-design"
+- "Design UI" / "mockup" / "opzioni di design"
+- Design-heavy features, visual refinement, design-system work
+
+> `ui-ux-pro-max` is a **tool used inside** the `ui-expert` agent / `ui-design`
+> skill (see REGISTRY.md — listed as a Key Tool of `ui-expert`), not a
+> standalone invocable BALDART skill. Route UI work through `ui-design` /
+> `ui-expert`, not to `ui-ux-pro-max` directly.
 
 ## Testing Skills
 
@@ -173,19 +168,30 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 
 ## Documentation Skills
 
-### writing-clearly-and-concisely
+### doc-writing-for-rag
+
+**When to use**:
+
+- Writing/rewriting dense reference documentation optimized for RAG indexing
+- Creating endpoint/reference docs in `${paths.references_dir}`
+
+**Triggers**:
+
+- "doc per RAG" / "dense documentation"
+- "template endpoint" / "compattare docs"
+
+### copywriting
 
 **When to use**:
 
-- Writing documentation
-- Creating specs
-- User-facing content
+- User-facing content, marketing copy, microcopy
+- Tone/voice refinement
 
 **Triggers**:
 
-- Documentation updates
-- README writing
-- Technical writing
+- "Scrivi la copy"
+- "Migliora il testo"
+- Landing/marketing content
 
 ## Project-Specific Skills
 
@@ -207,29 +213,25 @@ Add your project-specific skills here:
 START: User gives a task
   |
   v
-Is it a new feature/design task?
-  |-- YES --> Use brainstorming skill first
-  |           Then writing-plans
-  |           Then implementation skills
+Is it a new feature needing scope/plan?
+  |-- YES --> /prd (scopes + plans + writes cards)
+  |           Then /new (implements the cards end-to-end)
   |
   v
 Is it a bug fix?
-  |-- YES --> Use systematic-debugging
-  |           Then test-driven-development
-  |           Then verification-before-completion
+  |-- YES --> /bug (5-phase investigation + fix)
   |
   v
 Is it UI/visual work?
-  |-- YES --> Use frontend-design or ui-ux-pro-max
+  |-- YES --> /ui-design (mockups/options) or frontend-design
   |
   v
 Is it browser testing?
-  |-- YES --> Use playwright-skill or webapp-testing
+  |-- YES --> playwright-skill or webapp-testing (E2E via /e2e-review)
   |
   v
-Is work complete?
-  |-- YES --> Use verification-before-completion
-  |           Then code-review
+Is it cleanup/complexity reduction?
+  |-- YES --> /simplify
   |
   v
 Proceed with appropriate skill
@@ -237,29 +239,30 @@ Proceed with appropriate skill
 
 ## Skill Chaining
 
-Common skill chains:
+Common skill chains (all skills below are shipped under `.claude/skills/`):
 
 1. **New Feature**:
-   - brainstorming → writing-plans → test-driven-development → verification-before-completion → code-review
+   - /prd → /new (the orchestrator runs `code-reviewer` + `qa-sentinel` gates per card)
 
 2. **Bug Fix**:
-   - systematic-debugging → test-driven-development → verification-before-completion
+   - /bug → (fix lands through the bug skill's verify phase)
 
 3. **UI Feature**:
-   - brainstorming → frontend-design → test-driven-development → playwright-skill → code-review
+   - /prd → /ui-design → /new → playwright-skill (or /e2e-review for blocking E2E)
 
 4. **Refactoring**:
-   - code-review (identify issues) → test-driven-development → verification-before-completion
+   - /simplify (identify + apply cleanups) → /new gates re-run lint/tsc/tests
 
 ## Anti-Patterns
 
 **Don't**:
 
-- Skip brainstorming for "simple" features
+- Skip `/prd` scoping for "simple" multi-part features
 - Start coding before planning
-- Skip TDD because "I know how to fix it"
-- Skip verification before claiming completion
+- Skip the per-card `qa-sentinel` gate run because "I know how to fix it"
+- Claim completion before the `/new` review + gate cycle passes
 - Use wrong skill for the task
+- Route to a skill name that has no directory under `.claude/skills/`
 
 **Do**:
 

package/framework/agents/testing.md

@@ -9,6 +9,34 @@ Define required manual testing and QA issue workflow, including browser automati
 **In**: Manual testing steps, QA issue creation and handling, browser automation.
 **Out**: Performance testing strategy (see agents/performance.md).
 
+## Scope-aware Test Selection (Automated QA)
+
+The automated QA gate (`qa-sentinel`) does **not** run the full test suite on every change. It runs
+the depth dictated by the card's `review_profile`. The decision criteria for which profile a card
+gets are **computed by `prd-card-writer` (Rule C)** — see `prd-card-writer.md` for the criteria;
+this module only describes the profile→tier mapping qa-sentinel applies:
+
+- **balanced → SCOPED**: run only the tests *related to the changed files* (test-impact selection),
+  not the whole suite. This is the default for ordinary features and refactors.
+- **deep → FULL**: run the whole suite + security audit. Reserved for high-risk
+  changes (data model, security, broad blast radius). Blocking E2E for these changes is owned by the
+  separate `/e2e-review` skill (qa-sentinel does NOT run Playwright/E2E).
+- **skip / light**: the gate is not invoked — these are handled upstream (docs/chore, or gates
+  already run during implementation).
+- **Risk-drift escalation**: a `balanced` change is promoted to FULL only when the diff itself
+  reveals undeclared risk — paths touching auth, permissions, payment/billing, DB schema/migration,
+  or an API contract. Change *count* never escalates (it is advisory only).
+
+Test selection is **heuristic**, not instrumented: it relies on file paths, naming, and the test
+runner's native related-tests capability — no coverage maps, AST analysis, or ML. When no related
+tests can be resolved for a logic change, the gate records a coverage-gap and lowers its confidence
+rather than silently passing or falling back to the full suite. The concrete per-runner commands
+live in the `qa-sentinel` agent (which is stack-aware); this module states the principle only.
+
+> The executable tier table + runner cascade is owned by `qa-sentinel` (`.claude/agents/qa-sentinel.md`),
+> kept stack-specific there. Optional smoke convention: a `test:smoke` script or `tests/smoke/`
+> directory, if present, is used as a minimal sanity set — its absence is fine, not a misconfiguration.
+
 ## Do
 
 - Run project build command before marking a card done.

package/framework/templates/baldart.config.template.yml

@@ -45,6 +45,22 @@ paths:
   # Test infrastructure.
   e2e_tests_dir: ""           # e.g. tests/e2e
 
+  # Metrics output directory (used by /new Phase 8 + /prd metrics log).
+  # Default convention is "docs/metrics" — set explicitly to override.
+  metrics: ""                 # e.g. docs/metrics
+
+  # Optional telemetry tap for the wiki auto-learning loop. When set, skills
+  # append retrieval signal here; when empty, the tap is skipped with a
+  # WARNING (never a silent no-op). Only meaningful with has_wiki_overlay.
+  wiki_log: ""                # e.g. tools/doc-rag/wiki_log.py
+
+  # High-risk module paths used by RISK DETECTORS (review-profile escalation,
+  # security/perf signal detection). A portable list of repo-relative globs
+  # the project considers sensitive (auth, payments, billing, core engines).
+  # When EMPTY, risk detectors that depend on it emit a one-line diagnostic
+  # and skip — they never fall back to hard-coded project paths.
+  high_risk_modules: []       # e.g. ["src/lib/auth/**", "src/app/api/**/billing/**"]
+
 # ─── IDENTITY ────────────────────────────────────────────────────────────
 # Brand and audience facts skills use when generating UI, copy, or motion.
 identity:
@@ -199,18 +215,24 @@ lsp:
 
 # ─── GIT ─────────────────────────────────────────────────────────────────
 # Controls how worktree-manager (`/mw`) integrates a worktree's feature
-# branch back into `develop`.
+# branch back into the integration trunk.
 git:
-  # How `/mw` lands the feature branch onto develop:
+  # Integration trunk branch — the branch worktrees are created from and merged
+  # back into. NEVER hard-code "develop"/"main" in skills; they resolve this key.
+  # `baldart configure` autodetects it from `git symbolic-ref refs/remotes/origin/HEAD`
+  # (falling back to asking the user). Default kept as "develop" for back-compat.
+  trunk_branch: develop
+
+  # How `/mw` lands the feature branch onto the trunk:
   #
   #   pr          (default) — push feature branch, open a PR via `gh pr create`,
-  #                 merge via `gh pr merge`. Required if `develop` is protected
+  #                 merge via `gh pr merge`. Required if the trunk is protected
   #                 on origin (status checks, required reviews, merge queue).
   #
-  #   local-push  — after rebasing the feature branch onto `origin/develop`,
-  #                 fast-forward push the feature branch directly to
-  #                 `origin/develop` (`git push origin <feat>:develop`).
-  #                 No PR, no `gh` dependency. FAILS hard if `develop` is
+  #   local-push  — after rebasing the feature branch onto `origin/<trunk>`,
+  #                 fast-forward push the feature branch directly to the trunk
+  #                 (`git push origin <feat>:<trunk_branch>`).
+  #                 No PR, no `gh` dependency. FAILS hard if the trunk is
   #                 protected on origin — switch back to `pr` in that case.
   #
   # Neither strategy ever touches the main repo's HEAD — both flows are

package/package.json

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

package/src/commands/configure.js

@@ -38,7 +38,7 @@ const IGNORED_DIRS = new Set([
  * Non-fatal: any failure returns `{ value: 'pr', protected: null }` so configure
  * keeps moving. The user can override in the interactive prompt.
  */
-function detectMergeStrategy(cwd = process.cwd()) {
+function detectMergeStrategy(cwd = process.cwd(), trunk = 'develop') {
   try {
     const { execSync } = require('child_process');
     const opts = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf8' };
@@ -52,17 +52,17 @@ function detectMergeStrategy(cwd = process.cwd()) {
     } catch (_) {
       return { value: 'pr', protected: null, reason: 'no GitHub remote detected — defaulting to pr.' };
     }
-    // Probe branch protection. 404 means "not protected" → local-push viable.
+    // Probe branch protection on the resolved trunk. 404 means "not protected" → local-push viable.
     try {
-      execSync(`gh api repos/${nameWithOwner}/branches/develop/protection`, opts);
-      return { value: 'pr', protected: true, reason: 'develop is protected on origin — PR strategy required.' };
+      execSync(`gh api repos/${nameWithOwner}/branches/${trunk}/protection`, opts);
+      return { value: 'pr', protected: true, reason: `${trunk} is protected on origin — PR strategy required.` };
     } catch (_) {
       // Could be 404 (not protected) OR branch doesn't exist. Check existence:
       try {
-        execSync(`gh api repos/${nameWithOwner}/branches/develop -q .name`, opts);
-        return { value: 'local-push', protected: false, reason: 'develop exists on origin and is not protected — local-push viable.' };
+        execSync(`gh api repos/${nameWithOwner}/branches/${trunk} -q .name`, opts);
+        return { value: 'local-push', protected: false, reason: `${trunk} exists on origin and is not protected — local-push viable.` };
       } catch (_) {
-        return { value: 'pr', protected: null, reason: 'develop branch not found on origin — defaulting to pr.' };
+        return { value: 'pr', protected: null, reason: `${trunk} branch not found on origin — defaulting to pr.` };
       }
     }
   } catch (_) {
@@ -70,6 +70,34 @@ function detectMergeStrategy(cwd = process.cwd()) {
   }
 }
 
+/**
+ * Autodetect the integration trunk branch (git.trunk_branch).
+ * Order: origin/HEAD symbolic-ref → existing local `develop` → existing local
+ * `main`/`master` → 'develop'. Non-fatal: any failure returns the 'develop'
+ * back-compat default so configure keeps moving; the user can override.
+ */
+function detectTrunkBranch(cwd = process.cwd()) {
+  try {
+    const { execSync } = require('child_process');
+    const opts = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf8' };
+    try {
+      const ref = execSync('git symbolic-ref refs/remotes/origin/HEAD', opts).trim();
+      const name = ref.replace(/^refs\/remotes\/origin\//, '');
+      if (name) return { value: name, reason: `origin/HEAD points at ${name}.` };
+    } catch (_) { /* fall through to local branch probes */ }
+    const branches = (() => {
+      try { return execSync('git branch --format=%(refname:short)', opts).split('\n').map((s) => s.trim()); }
+      catch (_) { return []; }
+    })();
+    for (const cand of ['develop', 'main', 'master']) {
+      if (branches.includes(cand)) return { value: cand, reason: `local '${cand}' branch found.` };
+    }
+    return { value: 'develop', reason: 'no trunk detected — defaulting to develop.' };
+  } catch (_) {
+    return { value: 'develop', reason: 'probe failed — defaulting to develop.' };
+  }
+}
+
 function detect(cwd = process.cwd()) {
   const exists = (p) => fs.existsSync(path.join(cwd, p));
   const findFirst = (...candidates) => candidates.find(exists) || '';
@@ -282,7 +310,8 @@ function detect(cwd = process.cwd()) {
     : (exists('cypress.config.ts') || exists('cypress.config.js') || hasDep('cypress')) ? 'cypress'
     : '';
 
-  const mergeStrategyProbe = detectMergeStrategy(cwd);
+  const trunkBranchProbe = detectTrunkBranch(cwd);
+  const mergeStrategyProbe = detectMergeStrategy(cwd, trunkBranchProbe.value);
 
   // ---- Persistence layer (stack.database) --------------------------------
   let detectedDatabase = '';
@@ -344,6 +373,9 @@ function detect(cwd = process.cwd()) {
       references_dir: exists('docs/references') ? 'docs/references' : '',
       wiki_dir: exists('docs/wiki') ? 'docs/wiki' : '',
       e2e_tests_dir: e2eTestsDir,
+      metrics: exists('docs/metrics') ? 'docs/metrics' : '',
+      wiki_log: exists('tools/doc-rag/wiki_log.py') ? 'tools/doc-rag/wiki_log.py' : '',
+      high_risk_modules: [],
     },
     identity: {
       brand_name: brandName,
@@ -400,14 +432,16 @@ function detect(cwd = process.cwd()) {
       enabled: toolAdapters.defaultEnabled(cwd)
     },
     git: {
-      // Set to a plain string — the structured probe details (`protected`,
+      // Set to plain strings — the structured probe details (`protected`,
       // `reason`) are kept on a sibling key so mergePreserving stays type-safe.
+      trunk_branch: trunkBranchProbe.value,
       merge_strategy: mergeStrategyProbe.value,
     },
     _probes: {
       // Internal scratchpad — never serialized to YAML. Used by
       // interactivePrompts to surface the autodetection reasoning.
       merge_strategy: mergeStrategyProbe,
+      trunk_branch: trunkBranchProbe,
     },
   };