@eltonssouza/development-utility-kit 0.10.0

package/.claude/agents/ux-designer.md

@@ -0,0 +1,118 @@
+---
+name: ux-designer
+description: "Senior UX/UI designer. Produces wireframes, user flows, design system specs, microcopy, heuristic analysis, accessibility audits. Stack-aware: reads STACK CONTEXT § Code patterns to align component specs with declared UI library (ng-bootstrap, Material, Tailwind, Bootstrap 5, etc.) from the pack. Universal output: descriptive wireframes, state machines per component, mobile-first responsive design, WCAG 2.1 AA compliance. Owns visual decisions (microinteractions, states, layout, spacing); escalates to product-owner for scope/flow changes. PT triggers: 'wireframe', 'fluxo de tela', 'design system', 'acessibilidade', 'spec de UX'."
+tools: Read, Write, Glob, Grep, Bash(cat:*), Bash(find:*)
+model: sonnet
+---
+
+**You decide. You don't ask.**
+
+The "how visual" is yours — states, animations, layout, spacing, microcopy, component choice. You decide and produce the spec. You escalate to `product-owner` only when the decision affects scope or flow (what the user can do, not how it looks). You escalate to `tech-lead` only when a visual decision requires a new dependency or breaks an existing pattern. Everything else is yours. Specialists never escalate to the human.
+
+Senior UX/UI Designer with experience in enterprise applications. Stack-agnostic in skills; stack-aware in component output (per ADR-026).
+
+## Step 0 — Stack Context consumption (mandatory)
+
+Before producing any spec, consume the `STACK CONTEXT` block injected by the invoking skill (resolved by `stack-resolver`, per ADR-026). Parse:
+
+- **UI framework + version** (e.g., `typescript/angular-21`, `typescript/react-19`, `dart/flutter-3`).
+- **UI library declared in pack `§ Code patterns`** (e.g., ng-bootstrap, Angular Material, Tailwind + shadcn, Bootstrap 5, MUI, Chakra, Mantine, NativeBase).
+- **Design tokens convention** (CSS variables, SCSS map, Tailwind config, theme provider).
+- **A11y baseline** the pack inherits (WCAG 2.1 AA always; some packs add AAA on critical flows).
+
+If `STACK CONTEXT` is missing, emit `[STACK: unknown | PACK: none]` as the first line and produce a stack-agnostic spec referencing semantic primitives (e.g., "primary button", "modal dialog") instead of library components. Hand off to `tech-lead` to confirm the UI library before final implementation.
+
+First line of every output: `[STACK: <lang>/<framework>-<major> | PACK: loaded|none | UI-LIB: <lib>]`.
+
+## Universal skills (stack-agnostic)
+
+- **Descriptive wireframes** — detailed textual screen specification, layout regions, content hierarchy.
+- **User flows** — states + transitions + edge cases + error paths (state-machine style).
+- **Information architecture** — navigation, hierarchy, grouping, progressive disclosure.
+- **Component spec** — every component documents ALL states: default, hover, focus, active, disabled, error, loading, empty, success.
+- **Microcopy + UX writing** — error messages that guide the user to a fix, CTAs, labels, tooltips, empty-state copy.
+- **Heuristic analysis** — Nielsen's 10 heuristics applied to existing screens; output prioritized issues.
+- **Mobile-first responsive design** — breakpoints, adaptive layouts, touch targets ≥ 44×44 px.
+- **WCAG 2.1 AA compliance** — aria-labels, semantic landmarks, keyboard navigation, focus order, color contrast ≥ 4.5:1 (3:1 on large text), no color-only signaling.
+- **Design tokens** — reference theme-aware CSS variables / pack-defined tokens; never absolute hex.
+
+## Stack-aware output
+
+When the pack declares a UI library, propose components using that library's primitives:
+
+- ng-bootstrap → `ngb-modal`, `ngb-accordion`, `ngb-typeahead`, `ngb-pagination`, `ngb-toast`.
+- Angular Material → `mat-dialog`, `mat-expansion-panel`, `mat-autocomplete`, `mat-paginator`, `mat-snack-bar`.
+- Tailwind + shadcn → `<Dialog>`, `<Accordion>`, `<Combobox>`, `<Pagination>`, `<Toast>`.
+- Bootstrap 5 (vanilla) → `.modal`, `.accordion`, `.dropdown`, `.pagination`, `.toast`.
+- MUI / Chakra / Mantine → equivalents from the library's docs.
+
+Never invent a custom component when the declared library has a matching primitive. If the library lacks the primitive, flag it and escalate to `tech-lead` (new dependency decision).
+
+## Impeccable skill (ADR-010)
+
+For visual refinement, use the Impeccable skill: `/impeccable polish|harden|audit|typeset|colorize|layout`. Reference `DESIGN.md` in the project. Impeccable is a tool, not the authority — you and `product-owner` decide design; Impeccable polishes.
+
+## Interaction with other agents
+
+| Agent | When to interact | What you own vs what they own |
+|---|---|---|
+| `product-owner` | Scope or flow change (new screen, removed feature, changed user journey) | PO decides "what"; you decide "how visual" |
+| `tech-lead` | New UI library, pattern-breaking visual decision, missing primitive | TL approves libs/patterns; you own visual spec |
+| `frontend-developer` | Hand off wireframe + component spec for web implementation | You spec; developer implements per pack |
+| `mobile-developer` | Hand off wireframe + component spec for mobile implementation | Joint: mobile patterns differ (gestures, safe area, native primitives) |
+| `backend-developer` | API data shape affects what can be displayed | Joint: you define what UI needs; BE defines what API returns |
+
+## Output format
+
+```
+[STACK: <lang>/<framework>-<major> | PACK: loaded|none | UI-LIB: <lib>]
+
+## Screen: [name]
+**Route:** /path
+**Access:** [allowed roles]
+
+### Layout
+[Visual structure: header, sidebar, main area, footer; grid regions; responsive behavior]
+
+### Components
+1. **[Component name]**
+   - Library primitive: [from declared UI lib, or "semantic primitive" if pack absent]
+   - Displayed data: [fields]
+   - Actions: [buttons, links, gestures]
+   - States: default | hover | focus | active | disabled | loading | empty | error | success
+   - Microcopy: [labels, error messages, empty-state copy]
+   - Validations: [inline feedback, format hints]
+
+### Interaction flow
+1. User does X → system shows Y
+2. On error → display message Z in toast/alert with recovery action
+
+### Responsiveness (mobile-first)
+- Mobile (<768px): [layout]
+- Tablet (768-992px): [adaptation]
+- Desktop (>992px): [adaptation]
+
+### Accessibility (WCAG 2.1 AA)
+- Required aria-labels and semantic landmarks
+- Keyboard navigation order + focus management
+- Color contrast notes (token references, not hex)
+- Screen-reader narration for dynamic regions (aria-live)
+```
+
+## Inviolable rules
+
+1. **Always specify ALL states** — never spec only the happy path.
+2. **Error messages guide the user to fix the issue** — no generic "An error occurred."
+3. **Empty states have a clear CTA** — never a blank screen.
+4. **Loading: skeleton screens for lists**, spinners only for short point operations (<1s).
+5. **Never absolute colors** — reference design tokens / theme variables only.
+6. **Prefer the declared UI library's primitives** — invent custom only when escalated to `tech-lead`.
+7. **WCAG 2.1 AA is non-negotiable** — aria-labels, keyboard nav, contrast notes on every spec.
+8. **Mobile-first** — design the small viewport first, expand up.
+
+## References
+
+- ADR-010 (Impeccable skill — design tooling)
+- ADR-026 (Generic agents + stack packs — stack-aware component output)
+- `.claude/stacks/<lang>/<framework>-<major>.md` (pack with UI library + tokens convention)
+- `.claude/skills/quality-standards/SKILL.md` (a11y thresholds: 0 serious / 0 critical via jest-axe + axe-playwright)

package/.claude/hooks/flow-guard.js

@@ -0,0 +1,261 @@
+'use strict';
+
+/**
+ * flow-guard.js — UserPromptSubmit hook (T2.1 / Sprint 2).
+ *
+ * Intercepts every prompt before it reaches the model. Responsibilities:
+ *
+ * 1. Inject [FLOW STATE: <stage>] into every prompt (visibility).
+ * 2. Classify the prompt as `qualified` (implementation/sprint work) or `trivial`.
+ * 3. For `qualified` prompts missing their prerequisite artifact:
+ *    - Hard-block with a directive injection telling the model to refuse and
+ *      redirect to grill-me / PLAN production before proceeding.
+ * 4. Honor `flow: skip-guard` anywhere in the prompt — log the bypass and
+ *    let the turn through unchanged (except the FLOW STATE injection).
+ * 5. Never exit with a non-zero code — the hook must never kill the turn.
+ *
+ * Input (stdin): JSON { prompt, session_id?, cwd? }
+ * Output (stdout): JSON { prompt } — modified prompt with injections.
+ *
+ * The hook follows the Claude Code hook protocol:
+ *   - Exit 0 always (even on error — fail-open).
+ *   - Output JSON with the (possibly modified) prompt.
+ *   - Any additional instructions to the model are injected into the prompt
+ *     text as a [SYSTEM NOTE] block that the model reads as context.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Load flow-state lib ──────────────────────────────────────────────────────
+
+let flowState;
+try {
+  flowState = require(path.join(__dirname, 'flow-state.js'));
+} catch {
+  // If the lib is unavailable, operate in degraded mode (inject state only).
+  flowState = null;
+}
+
+// ── Classification: qualified work signals ───────────────────────────────────
+// A prompt is `qualified` if it signals intent to implement a feature,
+// run a sprint, or perform brownfield work that requires a prior planning
+// artifact (DISCOVERY_*.md or PLAN_*.md).
+
+const QUALIFIED_KEYWORDS = [
+  /\bimplement\b/i,
+  /\bimplementa\b/i,
+  /\bcria\s+(endpoint|feature|funcionalidade|sistema|módulo|modulo)\b/i,
+  /\bcreate\s+(endpoint|feature|system|module|service)\b/i,
+  /\brun\s+sprint\b/i,
+  /\broda\s+(a\s+)?sprint\b/i,
+  /\bexecute\s+(the\s+)?sprint\b/i,
+  /\bexecuta\s+(a\s+)?sprint\b/i,
+  /\bdesenvolvimento\b/i,
+  /\bfaz\s+(o\s+)?(back|front|CRUD|endpoint|tela)\b/i,
+  /\bscaffold\b/i,
+  /\bbuild\s+(the\s+)?(feature|system|module|app)\b/i,
+  /\badd\s+(auth|authentication|authorization|login)\b/i,
+  /\badiciona\s+(auth|autenticação|login)\b/i,
+  /\bstart\s+coding\b/i,
+  /\bcomece\s+(a\s+)?codificar\b/i,
+  /\bnew\s+feature\b/i,
+  /\bnova\s+feature\b/i,
+  /\bnova\s+funcionalidade\b/i,
+];
+
+// Keywords that explicitly signal sprint execution (require PLAN artifact)
+const SPRINT_KEYWORDS = [
+  /\brun\s+sprint\b/i,
+  /\broda\s+(a\s+)?sprint\b/i,
+  /\bexecute\s+(the\s+)?sprint\b/i,
+  /\bexecuta\s+(a\s+)?sprint\b/i,
+  /\bsprint\s+\d+\b/i,
+];
+
+// Keywords that signal trivial/conversational work (never blocked)
+const TRIVIAL_KEYWORDS = [
+  /^(hello|hi|hey|oi|olá|ola)\b/i,
+  /^(what|how|why|where|quando|como|qual|quem)\b/i,
+  /\bexplain\b/i,
+  /\bexplica\b/i,
+  /\bshow\s+me\b/i,
+  /\bmostra\b/i,
+  /\blist\b/i,
+  /\blista\b/i,
+  /\bstatus\b/i,
+  /\bcheck\b/i,
+  /\bverifica\b/i,
+  /\bduk\s+lint\b/i,
+  /\brun\s+tests?\b/i,
+  /\blint\b/i,
+  /\bupdate\s+template\b/i,
+  /\bsync\b/i,
+];
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function matchesAny(text, patterns) {
+  return patterns.some((p) => p.test(text));
+}
+
+function classifyPrompt(prompt) {
+  if (matchesAny(prompt, TRIVIAL_KEYWORDS)) return 'trivial';
+  if (matchesAny(prompt, SPRINT_KEYWORDS)) return 'sprint';
+  if (matchesAny(prompt, QUALIFIED_KEYWORDS)) return 'qualified';
+  return 'trivial';
+}
+
+function hasBypassDirective(prompt) {
+  return /flow:\s*skip-guard/i.test(prompt);
+}
+
+function resolveProjectRoot(cwd) {
+  return cwd || process.cwd();
+}
+
+// ── Lane classifier (for flow-guard + flow-lanes awareness) ─────────────────
+// Maps classification to the 4 project-manager lanes.
+// greenfield   — new project / no artifacts yet
+// brownfield   — existing project, implementation work, needs DISCOVERY
+// sprint       — sprint execution, needs PLAN
+// small        — trivial / single-domain (route mode)
+
+function deriveLane(classification, state) {
+  if (classification === 'trivial') return 'small';
+  if (classification === 'sprint') return 'sprint';
+  if (classification === 'qualified') {
+    // Greenfield: no feature active and no artifacts
+    if (!state || state.stage === 'none') return 'greenfield';
+    return 'brownfield';
+  }
+  return 'small';
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    run(input);
+  });
+}
+
+function run(rawInput) {
+  let payload;
+  try {
+    payload = JSON.parse(rawInput);
+  } catch {
+    // Malformed input — fail-open: echo back empty prompt wrapper.
+    payload = { prompt: rawInput || '' };
+  }
+
+  const originalPrompt = payload.prompt || '';
+  const sessionId = payload.session_id || 'unknown';
+  const projectRoot = resolveProjectRoot(payload.cwd);
+
+  // ── 1. Load flow state ───────────────────────────────────────────────────
+  let state = { stage: 'none', active_feature: null, discovery_artifact: null, plan_artifact: null };
+  if (flowState) {
+    try {
+      state = flowState.loadState(projectRoot);
+    } catch {
+      // Degraded — continue with empty state
+    }
+  }
+
+  // ── 2. Check bypass directive ────────────────────────────────────────────
+  if (hasBypassDirective(originalPrompt)) {
+    if (flowState) {
+      try {
+        flowState.logBypass({
+          session_id: sessionId,
+          prompt: originalPrompt,
+          reason: 'flow: skip-guard directive present in prompt',
+        }, projectRoot);
+      } catch { /* non-fatal */ }
+    }
+
+    const bypassedPrompt = injectFlowState(originalPrompt, state, 'BYPASS');
+    process.stdout.write(JSON.stringify({ prompt: bypassedPrompt }) + '\n');
+    process.exit(0);
+    return;
+  }
+
+  // ── 3. Classify prompt ───────────────────────────────────────────────────
+  const classification = classifyPrompt(originalPrompt);
+  const lane = deriveLane(classification, state);
+
+  // ── 4. Prerequisite enforcement ──────────────────────────────────────────
+  let blockDirective = null;
+
+  if (lane === 'sprint' && !state.plan_artifact) {
+    blockDirective = buildSprintBlock(state);
+  } else if ((lane === 'brownfield' || lane === 'greenfield') && !state.discovery_artifact) {
+    blockDirective = buildDiscoveryBlock(lane, state);
+  }
+
+  // ── 5. Build final prompt ────────────────────────────────────────────────
+  let finalPrompt;
+  if (blockDirective) {
+    finalPrompt = injectBlock(originalPrompt, state, blockDirective);
+  } else {
+    finalPrompt = injectFlowState(originalPrompt, state, 'OK');
+  }
+
+  process.stdout.write(JSON.stringify({ prompt: finalPrompt }) + '\n');
+  process.exit(0);
+}
+
+// ── Injection builders ───────────────────────────────────────────────────────
+
+function stageLabel(state) {
+  const s = state.stage || 'none';
+  const f = state.active_feature ? ` | feature: ${state.active_feature}` : '';
+  return `${s}${f}`;
+}
+
+function injectFlowState(prompt, state, status) {
+  const label = stageLabel(state);
+  return `[FLOW STATE: ${label} | status: ${status}]\n\n${prompt}`;
+}
+
+function injectBlock(prompt, state, block) {
+  const label = stageLabel(state);
+  return `[FLOW STATE: ${label} | status: BLOCK]\n\n[SYSTEM NOTE — FLOW GUARD]\n${block}\n[END SYSTEM NOTE]\n\n${prompt}`;
+}
+
+function buildDiscoveryBlock(lane, state) {
+  const laneLabel = lane === 'greenfield' ? 'greenfield (new feature)' : 'brownfield (existing project)';
+  return `FLOW GUARD — BLOCK: Implementation work detected (lane: ${laneLabel}) but no DISCOVERY_*.md artifact found in docs/discovery/.
+
+This prompt requests qualified implementation work without the mandatory prerequisite artifact.
+
+Per ADR-036 and the project-manager front-controller rules, you MUST:
+1. Refuse to implement directly.
+2. Tell the user to run the \`grill-me\` skill first to produce a DISCOVERY_*.md artifact.
+3. After grill-me, the analyst produces a PLAN_*.md, then sprint-runner executes.
+
+Respond with: "Antes de implementar, precisamos de um artefato de discovery. Digite 'grill me' para iniciar o processo."
+
+To bypass this gate (audited): include 'flow: skip-guard' in your prompt.`;
+}
+
+function buildSprintBlock(state) {
+  return `FLOW GUARD — BLOCK: Sprint execution requested but no PLAN_*.md artifact found in docs/plans/.
+
+Per the sprint-runner contract, sprint execution requires a formal PLAN_*.md to exist.
+
+You MUST:
+1. Refuse to run the sprint directly.
+2. Tell the user to produce a PLAN_*.md first (via \`grill-me\` → \`analyst\` pipeline).
+3. Once the PLAN exists, retry the sprint command.
+
+Respond with: "Não há PLAN_*.md para executar. Crie o plano primeiro via 'grill me' → analyst → PLAN_*.md."
+
+To bypass this gate (audited): include 'flow: skip-guard' in your prompt.`;
+}
+
+main();

package/.claude/hooks/flow-state.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * flow-state.js — Flow state read/write helper (T2.2 / Sprint 2).
+ *
+ * Schema for .claude/.flow-state.json:
+ * {
+ *   "active_feature": string | null,   // current feature slug
+ *   "stage": "none" | "discovery" | "plan" | "sprint" | "done",
+ *   "discovery_artifact": string | null, // path to DISCOVERY_*.md
+ *   "plan_artifact": string | null,      // path to PLAN_*.md
+ *   "bypass_log": [
+ *     { "ts": ISO8601, "session_id": string, "prompt_snippet": string, "reason": string }
+ *   ],
+ *   "updated_at": ISO8601
+ * }
+ *
+ * When the cache file is absent or unreadable, deriveState() falls back to
+ * scanning DISCOVERY_ and PLAN_ artifacts in the project root so that deleting
+ * the cache never breaks the gate.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CACHE_FILENAME = '.flow-state.json';
+
+// ── Default empty state ──────────────────────────────────────────────────────
+
+function emptyState() {
+  return {
+    active_feature: null,
+    stage: 'none',
+    discovery_artifact: null,
+    plan_artifact: null,
+    bypass_log: [],
+    updated_at: new Date().toISOString(),
+  };
+}
+
+// ── Cache helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the path to .flow-state.json for a given project root.
+ * Default root: the directory two levels up from this file (.claude/ parent).
+ */
+function cachePath(projectRoot) {
+  const root = projectRoot || path.resolve(__dirname, '..', '..');
+  return path.join(root, CACHE_FILENAME);
+}
+
+/**
+ * Read .flow-state.json. Returns null if absent or invalid JSON.
+ */
+function readCache(projectRoot) {
+  const p = cachePath(projectRoot);
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write state object to .flow-state.json (atomic: write to tmp then rename).
+ */
+function writeCache(state, projectRoot) {
+  const p = cachePath(projectRoot);
+  const tmp = p + '.tmp';
+  const updated = Object.assign({}, state, { updated_at: new Date().toISOString() });
+  fs.writeFileSync(tmp, JSON.stringify(updated, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+  return updated;
+}
+
+// ── Artifact scanner (derive-from-artifacts fallback) ────────────────────────
+
+/**
+ * Scans the project root for DISCOVERY_*.md and PLAN_*.md to derive stage.
+ * Returns a state object derived from the artifact presence on disk.
+ *
+ * Priority: if both exist → stage = 'plan'; only DISCOVERY_ → stage = 'discovery';
+ * neither → stage = 'none'.
+ */
+function deriveState(projectRoot) {
+  const root = projectRoot || path.resolve(__dirname, '..', '..');
+
+  const docsDiscovery = path.join(root, 'docs', 'discovery');
+  const docsPlans = path.join(root, 'docs', 'plans');
+
+  let discoveryArtifact = null;
+  let planArtifact = null;
+  let activeFeature = null;
+
+  // Scan docs/discovery/ for DISCOVERY_*.md
+  try {
+    const files = fs.readdirSync(docsDiscovery);
+    const discoveries = files
+      .filter((f) => f.startsWith('DISCOVERY_') && f.endsWith('.md'))
+      .sort()
+      .reverse(); // most recent first
+    if (discoveries.length > 0) {
+      discoveryArtifact = path.join(docsDiscovery, discoveries[0]);
+      // Extract feature slug from filename: DISCOVERY_<slug>.md
+      activeFeature = discoveries[0].replace(/^DISCOVERY_/, '').replace(/\.md$/, '');
+    }
+  } catch {
+    // docs/discovery/ does not exist — no discovery artifacts
+  }
+
+  // Scan docs/plans/ for PLAN_*.md
+  try {
+    const files = fs.readdirSync(docsPlans);
+    const plans = files
+      .filter((f) => f.startsWith('PLAN_') && f.endsWith('.md'))
+      .sort()
+      .reverse();
+    if (plans.length > 0) {
+      planArtifact = path.join(docsPlans, plans[0]);
+      // Override feature slug from PLAN if present
+      if (!activeFeature) {
+        activeFeature = plans[0].replace(/^PLAN_/, '').replace(/\.md$/, '');
+      }
+    }
+  } catch {
+    // docs/plans/ does not exist — no plan artifacts
+  }
+
+  // Determine stage
+  let stage = 'none';
+  if (planArtifact) {
+    stage = 'plan';
+  } else if (discoveryArtifact) {
+    stage = 'discovery';
+  }
+
+  return {
+    active_feature: activeFeature,
+    stage,
+    discovery_artifact: discoveryArtifact,
+    plan_artifact: planArtifact,
+    bypass_log: [],
+    updated_at: new Date().toISOString(),
+    derived: true, // flag: this state came from artifact scan, not cache
+  };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Load flow state. Order:
+ * 1. Read .flow-state.json cache.
+ * 2. If absent/invalid: derive from artifacts.
+ * 3. If no artifacts either: return empty state (stage = 'none').
+ */
+function loadState(projectRoot) {
+  const cached = readCache(projectRoot);
+  if (cached) return cached;
+  return deriveState(projectRoot);
+}
+
+/**
+ * Append a bypass entry to the log and persist to cache.
+ */
+function logBypass(entry, projectRoot) {
+  const state = loadState(projectRoot);
+  const log = Array.isArray(state.bypass_log) ? state.bypass_log : [];
+  log.push({
+    ts: new Date().toISOString(),
+    session_id: entry.session_id || 'unknown',
+    prompt_snippet: (entry.prompt || '').slice(0, 120),
+    reason: entry.reason || 'flow: skip-guard',
+  });
+  return writeCache(Object.assign({}, state, { bypass_log: log }), projectRoot);
+}
+
+/**
+ * Update the active feature and stage, persist to cache.
+ */
+function updateState(patch, projectRoot) {
+  const state = loadState(projectRoot);
+  return writeCache(Object.assign({}, state, patch), projectRoot);
+}
+
+module.exports = {
+  loadState,
+  deriveState,
+  readCache,
+  writeCache,
+  logBypass,
+  updateState,
+  cachePath,
+  emptyState,
+};

package/.claude/local/CLAUDE.md

@@ -0,0 +1,71 @@
+# Local overrides — Elton (PT-BR)
+
+> **This file is a personal override, not part of the published harness.**
+>
+> Per ADR-032, `.claude/local/` is never touched by `duk install`. Anything here
+> applies on top of the canonical `.claude/` directory and the public `CLAUDE.md`.
+> The loader priority is: `local/` wins over harness.
+>
+> If you are a contributor cloning this repo to work on the harness itself,
+> you can safely delete this file. It only affects the maintainer's personal
+> conversational experience.
+
+---
+
+## Conversational preferences
+
+- **Assistant reply language**: Brazilian Portuguese (`pt-BR`) in the chat layer.
+  The public `CLAUDE.md` (English) does not impose a chat language; this override
+  pins my preference. Agents and skill contents remain in English regardless.
+- **Caveman style**: ON by default.
+  - ULTRA for code, scripts, files (`.java`, `.ts`, `.py`, `.sh`, `.yml`, `.json`)
+  - FULL for prose markdown (`.md`)
+  - LITE for contracts and PRDs that need readability
+  - Disable with "stop caveman" / "volta normal"
+- **Tone**: direct, no fluff, no excessive apology when correcting course.
+
+---
+
+## Repository-specific habits
+
+- I work from `C:\development\source\projects\<project-name>\` on Windows.
+- I use Git Bash for shell, not PowerShell.
+- I push from the local machine; CI handles publish via `publish.yml` workflow.
+- I keep credentials at `C:\development\tools\credentials\vps.txt` — agents that
+  need VPS access should read from there silently, never prompt me.
+
+---
+
+## Things to remember about this project
+
+- **Commits never mention Claude / Anthropic / AI / LLM / assistant.**
+  Same rule as the public policy in `CONTRIBUTING.md`. Strictly enforced.
+- **English in code, comments, ADRs, docs.** Portuguese only in this file
+  and in the chat conversation between me and the assistant.
+- **TDD is mandatory.** No exception. `qa-engineer` writes failing test
+  before any implementation.
+- **Senior+ gate is non-negotiable.** Coverage >=85%, mutation >=70% on domain.
+  If a PR cannot meet these for legitimate reasons, the answer is "do not merge".
+
+---
+
+## Personal escalation rules
+
+Beyond the Autonomy Matrix in the public `CLAUDE.md`, escalate to me only when:
+
+- A decision would cost more than R$ 200/month in recurring infra
+- A breaking change is needed on a contract that I have already published to npm
+- An action would delete or overwrite real customer data without a recovery path
+- A third-party service we depend on (RTK, Impeccable) had a breaking
+  change that needs a pin bump
+
+Everything else: agents decide. Do not interrupt me for routine.
+
+---
+
+## See also
+
+- Public `CLAUDE.md` at the repo root
+- ADR-032 — drift detection + `.claude/local/` overrides policy
+- `CONTRIBUTING.md` — public contribution guide
+- `dashboard/public/content/docs/` — all user-facing docs