@brunosps00/dev-workflow 1.4.0 → 1.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "author": {
     "name": "Bruno Santos"
   },

package/README.md

@@ -12,11 +12,11 @@ This will:
 1. Ask you to select a language (English or Portuguese)
 2. Create `.dw/commands/` with workflow commands
 3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
-4. Create `.dw/rules/` (populated by `/dw-analyze-project`)
+4. Create `.dw/rules/` (populated by `/dw-analyze-project`) + a curated `.dw/rules-library/` declarative baseline per stack (loaded lazily via `.dw/config/stack-mappings.json`)
 5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
 6. Generate skill wrappers and project agents for Claude Code, Codex, Copilot, and OpenCode
 7. Configure MCP servers (Context7 + Playwright)
-8. Install enforcement hooks (git guardrails) + a statusline into `.claude/settings.json` (merge-aware — your own hooks/statusline are never overwritten)
+8. Install enforcement hooks (git guardrails + a `SessionEnd` token-cost tracker → `.dw/metrics/costs.jsonl`) + a statusline (branch · active spec · minimalism mode · today's estimated spend) into `.claude/settings.json` (merge-aware — your own hooks/statusline are never overwritten)
 
 > **Compozy-inspired disciplines.** Since 0.5.0, dev-workflow bundles three primitives — `dw-verify`, `dw-memory`, `dw-review-rigor` — adapted from the [Compozy](https://github.com/compozy/compozy) project and invoked internally by existing commands. See [docs/compozy-integration.md](docs/compozy-integration.md) for what was ported and what was not.
 
@@ -42,7 +42,7 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v1.4.0 ships **36 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.6.0 ships **37 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 
@@ -69,7 +69,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
 | **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Tier 3 — Specialty (11)
+### Tier 3 — Specialty (12)
 
 | Command | What |
 |---------|------|
@@ -80,6 +80,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-context-budget`** | Audits context overhead from commands, skills, agents, instruction files, and MCPs. |
 | **`/dw-harness-audit`** | Deterministic health scorecard for the dev-workflow install, agents, wrappers, MCPs, and gates. |
 | **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references. |
+| **`/dw-learn`** | Synthesizes durable decisions (confidence-tagged), bugfixes, deviations, and git history into atomic confidence-weighted **instincts** you approve at `.dw/memory/instincts/`; can propose constitution principles. On-demand and human-in-the-loop — **no always-on observer**. |
 | **`/dw-new-project`** | Bootstrap a new project from empty directory. Stack interview, wraps official `create-*` tools, composes docker-compose for dev, seeds `.env`, scripts, CI, `.dw/rules/`. |
 | **`/dw-dockerize`** | Reads existing project, detects stack + runtime deps, proposes Dockerfile + docker-compose for dev/prod with explicit trade-offs (Conservative/Balanced/Bold). |
 | **`/dw-install-azure-skills`** | **Opt-in.** Clones curated Azure skills from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0) into `.agents/skills/azure/` and registers the [Microsoft Learn MCP Server](https://learn.microsoft.com/en-us/training/support/mcp-get-started) (HTTP, no-auth). Interactive category selection (Compute / Data & Storage / AI & ML / Networking / Identity & Security / DevOps / Observability / Integration / Architecture / All). Re-run to refresh from upstream. Also available as CLI: `npx @brunosps00/dev-workflow install-azure-skills`. |
@@ -376,7 +377,7 @@ Optional Azure integration (v1.0.3). The `/dw-install-azure-skills` command and
 
 Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex) formalized in `CLAUDE.md`/`AGENTS.md` above the Trigger Map; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
 
-Four patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding new commands or skills** — instead they fold into the existing surface as internal modes and inline guidance: (1) **grill-with-docs** → `/dw-brainstorm` `grill` mode (interview discipline that stress-tests plan vocabulary against `.dw/rules/`); (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same release also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
+Patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding any new public command** (the public command count is unchanged): (1) **grill** — a native, stateful alignment session reimplemented (clean-room, no upstream prose copied) from [`skills/engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md), [`skills/productivity/grilling`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md), and [`skills/engineering/domain-modeling`](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md). It is the `/dw-brainstorm` `grill` mode, backed by two **internal, non-exported** bundled skills — `dw-grilling` (dependency-ordered decision-tree interview, one decision per turn with a recommended answer, facts looked up rather than asked, shared-understanding gate) and `dw-domain-modeling` (canonical glossary, fuzzy/overloaded-term challenge, rare ADRs). Intentional `.dw/` differences: the curated glossary lives in **`.dw/domain/**`** (not upstream's root `CONTEXT.md`, and not our auto-generated `.dw/rules/`); Grill requires **one explicit authorization** before it writes and is mutually exclusive with the option matrix; alignment emits an idea one-pager at **schema `1.1`** consumed by `/dw-plan` without re-asking; and ADR creation is gated on the 3-criteria test and routed via `/dw-adr --scope=repo|prd`. (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same line of work also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
 
 Opportunity discovery and the explicit `/dw-refactor` surface were inspired by patterns observed in [`pedronauck/skills`](https://github.com/pedronauck/skills), especially `game-changing-features` (10x opportunity framing) and `refactoring-analysis` (Fowler-smell prioritization). dev-workflow does not install or depend on that repository at runtime, and the command text here is a clean-room adaptation of the workflow shape rather than copied skill content.
 

package/lib/constants.js

@@ -1,9 +1,9 @@
 const COMMANDS = {
   en: [
-    { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost.' },
+    { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost. --scope=repo writes .dw/adrs/ (works before any PRD); --scope=prd writes under the active PRD. Gated on hard-to-reverse + surprising + genuine trade-off.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
     { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. First invocation plans and stops; second invocation resumes via dw-goal, then commit and PR.' },
-    { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Modes: ideation, --research, --onepager, --council. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
+    { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Auto-dispatches internal modes via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill is a native stateful alignment session (a direct grill-me phrase or --mode=grill) that writes canonical vocabulary to .dw/domain/. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
     { name: 'dw-claude-run', userInvoked: true, description: 'Trigger when user asks to run/fire Claude (claude -p headless) in a dedicated worktree to implement a prepared prompt/spec. Claude adapter over the dw-cli-run protocol: durable audit log, resumable session via --session-id, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
     { name: 'dw-codex-run', userInvoked: true, description: 'Trigger when user asks to run/fire Codex (codex exec) in a dedicated worktree to implement a prepared prompt/spec. Codex adapter over the dw-cli-run protocol: durable audit log, resumable per-task session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
@@ -20,6 +20,7 @@ const COMMANDS = {
     { name: 'dw-install-aws-skills', description: 'Trigger when user asks to install AWS expertise, setup AWS MCP server, or add AWS agent skills. Opt-in: clones curated skills from aws/agent-toolkit-for-aws into .agents/skills/aws/ and registers the unified AWS MCP Server (stdio via mcp-proxy-for-aws). Requires uv, aws cli, and AWS credentials.' },
     { name: 'dw-install-azure-skills', description: 'Trigger when user asks to install Azure expertise, setup Microsoft docs MCP, or add Azure agent skills. Opt-in: clones curated skills from MicrosoftDocs/Agent-Skills into .agents/skills/azure/ and registers the Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
+    { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
@@ -38,10 +39,10 @@ const COMMANDS = {
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
-    { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam.' },
+    { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam. --scope=repo escreve em .dw/adrs/ (funciona antes de qualquer PRD); --scope=prd escreve sob o PRD ativo. Gated em dificil-de-reverter + surpreendente + trade-off real.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
     { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Primeira invocacao planeja e para; segunda retoma via dw-goal, depois commit e PR.' },
-    { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Modos: ideacao, --research, --onepager, --council. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
+    { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Auto-dispatch de modos internos via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill e uma sessao nativa de alinhamento com estado (frase direta tipo me-questione ou --mode=grill) que escreve vocabulario canonico em .dw/domain/. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
     { name: 'dw-claude-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Claude (claude -p headless) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Claude sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel via --session-id, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
     { name: 'dw-codex-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Codex (codex exec) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Codex sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel por tarefa, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
@@ -58,6 +59,7 @@ const COMMANDS = {
     { name: 'dw-install-aws-skills', description: 'Trigger quando usuario pede pra instalar expertise AWS, configurar MCP da AWS, ou adicionar agent skills AWS. Opt-in: clona skills curadas de aws/agent-toolkit-for-aws para .agents/skills/aws/ e registra o AWS MCP Server unificado (stdio via mcp-proxy-for-aws). Requer uv, aws cli e credenciais AWS.' },
     { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure. Opt-in: clona skills curadas de MicrosoftDocs/Agent-Skills para .agents/skills/azure/ e registra o Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
+    { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },

package/lib/hooks.js

@@ -7,6 +7,8 @@ const HOOKS_DIR_MARKER = '.dw/scripts/hooks/';
 const GIT_GUARDRAILS_CMD = 'node .dw/scripts/hooks/git-guardrails.mjs';
 const STATUSLINE_CMD = 'node .dw/scripts/hooks/statusline.mjs';
 const GIT_GUARDRAILS_SCRIPT = 'git-guardrails.mjs';
+const SESSION_COST_CMD = 'node .dw/scripts/hooks/session-cost.mjs';
+const SESSION_COST_SCRIPT = 'session-cost.mjs';
 
 function isOurs(command) {
   return typeof command === 'string' && command.includes(HOOKS_DIR_MARKER);
@@ -31,13 +33,48 @@ function installHooks(projectRoot) {
   const before = JSON.stringify(settings);
 
   const hooksResult = reconcilePreToolUseGitGuardrails(settings);
+  const sessionCostResult = reconcileSessionEndCost(settings);
   const statusLineResult = reconcileStatusLine(settings);
 
   if (JSON.stringify(settings) !== before) {
     writeSettings(projectRoot, settings);
   }
 
-  return { hooks: hooksResult, statusLine: statusLineResult };
+  return { hooks: hooksResult, sessionCost: sessionCostResult, statusLine: statusLineResult };
+}
+
+/**
+ * Reconcile the SessionEnd cost-tracking hook (marker-based, merge-aware — same
+ * contract as the git guardrail). No matcher: fires on every session end.
+ * Returns 'added' | 'updated' | 'unchanged'.
+ */
+function reconcileSessionEndCost(settings) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
+
+  const groups = settings.hooks.SessionEnd;
+
+  const existed = groups.some(
+    (g) => g && Array.isArray(g.hooks) && g.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(SESSION_COST_SCRIPT)),
+  );
+  const exactPresent = groups.some(
+    (g) => g && Array.isArray(g.hooks) && g.hooks.some((h) => h && h.command === SESSION_COST_CMD),
+  );
+
+  if (exactPresent) return 'unchanged';
+
+  // Drop any stale/relocated copies of OUR hook, preserving user hooks.
+  for (const group of groups) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    group.hooks = group.hooks.filter(
+      (h) => !(h && typeof h.command === 'string' && h.command.includes(SESSION_COST_SCRIPT)),
+    );
+  }
+  settings.hooks.SessionEnd = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+
+  settings.hooks.SessionEnd.push({ hooks: [{ type: 'command', command: SESSION_COST_CMD }] });
+
+  return existed ? 'updated' : 'added';
 }
 
 function reconcilePreToolUseGitGuardrails(settings) {
@@ -105,17 +142,21 @@ function removeHooks(projectRoot) {
   const settings = readSettings(projectRoot);
   let removed = 0;
 
-  if (settings.hooks && Array.isArray(settings.hooks.PreToolUse)) {
-    for (const group of settings.hooks.PreToolUse) {
-      if (!group || !Array.isArray(group.hooks)) continue;
-      const kept = group.hooks.filter((h) => !(h && isOurs(h.command)));
-      removed += group.hooks.length - kept.length;
-      group.hooks = kept;
+  // Remove OUR hook entries from every event (PreToolUse, SessionEnd, PostToolUse, …),
+  // identified by the .dw/scripts/hooks/ marker; never touch user-added hooks.
+  if (settings.hooks && typeof settings.hooks === 'object') {
+    for (const event of Object.keys(settings.hooks)) {
+      const groups = settings.hooks[event];
+      if (!Array.isArray(groups)) continue;
+      for (const group of groups) {
+        if (!group || !Array.isArray(group.hooks)) continue;
+        const kept = group.hooks.filter((h) => !(h && isOurs(h.command)));
+        removed += group.hooks.length - kept.length;
+        group.hooks = kept;
+      }
+      settings.hooks[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+      if (settings.hooks[event].length === 0) delete settings.hooks[event];
     }
-    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
-      (g) => g && Array.isArray(g.hooks) && g.hooks.length > 0,
-    );
-    if (settings.hooks.PreToolUse.length === 0) delete settings.hooks.PreToolUse;
     if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
   }
 
@@ -134,4 +175,5 @@ module.exports = {
   HOOKS_DIR_MARKER,
   GIT_GUARDRAILS_CMD,
   STATUSLINE_CMD,
+  SESSION_COST_CMD,
 };

package/lib/init.js

@@ -170,6 +170,30 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     console.log();
   }
 
+  // 3.9. Copy curated rules library + stack mappings (declarative baseline per stack,
+  // loaded lazily by the detected stack). Managed: reconciled on update/repair.
+  const rulesLibSrc = path.join(SCAFFOLD_DIR, 'rules');
+  if (require('fs').existsSync(rulesLibSrc)) {
+    console.log('  Rules library:');
+    const rlResults = copyDir(rulesLibSrc, path.join(projectRoot, '.dw', 'rules-library'), managedForce);
+    totalCreated += rlResults.created;
+    totalSkipped += rlResults.skipped;
+    totalOverwritten += rlResults.overwritten;
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.dw', 'rules-library')));
+    console.log(`    ${rlResults.created} created, ${rlResults.skipped} skipped, ${rlResults.overwritten} overwritten\n`);
+  }
+  const stackMapSrc = path.join(SCAFFOLD_DIR, 'config', 'stack-mappings.json');
+  if (require('fs').existsSync(stackMapSrc)) {
+    const cfgDir = path.join(projectRoot, '.dw', 'config');
+    ensureDir(cfgDir);
+    const stackMapDest = path.join(cfgDir, 'stack-mappings.json');
+    const smStatus = writeFile(stackMapDest, require('fs').readFileSync(stackMapSrc, 'utf-8'), managedForce);
+    if (smStatus === 'created') totalCreated++;
+    else if (smStatus === 'overwritten') totalOverwritten++;
+    else totalSkipped++;
+    touchedFiles.push(stackMapDest);
+  }
+
   // 4. Create .dw/rules/ with README
   if (!isUpdate) {
     console.log('  Rules:');
@@ -233,6 +257,30 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     touchedFiles.push(gitkeepPath);
   }
 
+  // 5.25. Ensure .dw/metrics/ + .gitignore (runtime cost tracking; costs.jsonl is
+  // machine-local so it is gitignored). Created if missing on both init and update.
+  {
+    const metricsDir = path.join(projectRoot, '.dw', 'metrics');
+    ensureDir(metricsDir);
+    const metricsGitignore = path.join(metricsDir, '.gitignore');
+    const mStatus = writeFile(metricsGitignore, 'costs.jsonl\n', false);
+    if (mStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(metricsGitignore);
+  }
+
+  // 5.26. Ensure .dw/memory/instincts/ (durable learnings promoted by /dw-learn;
+  // format in the dw-memory skill's references/instincts.md). Init only; preserved on update.
+  if (!isUpdate) {
+    const instinctsDir = path.join(projectRoot, '.dw', 'memory', 'instincts');
+    ensureDir(instinctsDir);
+    const instinctsKeep = path.join(instinctsDir, '.gitkeep');
+    const ikStatus = writeFile(instinctsKeep, '', false);
+    if (ikStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(instinctsKeep);
+  }
+
   // 5.3. Create local ephemeral subtask handoff directories.
   ensureSubtaskLayout(projectRoot);
   touchedFiles.push(path.join(projectRoot, '.dw', 'subtasks', '.gitignore'));
@@ -317,7 +365,7 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
   // refreshes our entries, never touches user-defined hooks/statusLine).
   console.log('  Hooks & statusline:');
   const hookResults = installHooks(projectRoot);
-  console.log(`    git-guardrails: ${hookResults.hooks}, statusline: ${hookResults.statusLine}\n`);
+  console.log(`    git-guardrails: ${hookResults.hooks}, session-cost: ${hookResults.sessionCost}, statusline: ${hookResults.statusLine}\n`);
   if (hookResults.statusLine === 'skipped-user') {
     console.log('    Note: a custom statusLine is set; to show dev-workflow state add `node .dw/scripts/hooks/statusline.mjs`.\n');
   }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"
   },
   "scripts": {
+    "test": "node --test test/*.test.js",
     "validate": "node lib/validate.js",
-    "build:plugin": "node lib/build-plugin.js"
+    "build:plugin": "node lib/build-plugin.js",
+    "pack:check": "npm pack --dry-run"
   },
   "files": [
     "bin/",

package/scaffold/config/stack-mappings.json

@@ -0,0 +1,40 @@
+{
+  "_note": "Maps a detected stack to its curated baseline rule files (in .dw/rules-library/), relevant bundled skills, and safe default permissions. Consumed by /dw-analyze-project (detect + seed constitution) and /dw-review (declarative bar). Load ONLY the active stack's rules — never the whole library. Indicators: a bare filename means 'file exists'; 'file:substring' means the file contains the substring.",
+  "stacks": [
+    {
+      "id": "typescript",
+      "indicators": ["tsconfig.json", "package.json:typescript"],
+      "rules": ["common", "typescript"],
+      "skills": ["dw-testing-discipline", "dw-simplification"],
+      "permissions": { "allow": ["npx tsc", "npx eslint", "npm test", "pnpm test"], "deny": ["npm publish"] }
+    },
+    {
+      "id": "react",
+      "indicators": ["package.json:react"],
+      "rules": ["common", "typescript", "react"],
+      "skills": ["dw-ui-discipline", "vercel-react-best-practices", "dw-testing-discipline"],
+      "permissions": { "allow": ["npm test", "pnpm test", "npx vitest"], "deny": [] }
+    },
+    {
+      "id": "python",
+      "indicators": ["pyproject.toml", "requirements.txt", "setup.py"],
+      "rules": ["common", "python"],
+      "skills": ["dw-testing-discipline", "dw-silent-failure"],
+      "permissions": { "allow": ["pytest", "ruff", "mypy"], "deny": [] }
+    },
+    {
+      "id": "rust",
+      "indicators": ["Cargo.toml"],
+      "rules": ["common", "rust"],
+      "skills": ["dw-testing-discipline"],
+      "permissions": { "allow": ["cargo test", "cargo clippy", "cargo check"], "deny": [] }
+    },
+    {
+      "id": "csharp",
+      "indicators": [".csproj", ".sln"],
+      "rules": ["common", "csharp"],
+      "skills": ["dw-testing-discipline"],
+      "permissions": { "allow": ["dotnet test", "dotnet build"], "deny": [] }
+    }
+  ]
+}

package/scaffold/en/commands/dw-adr.md

@@ -1,36 +1,71 @@
 <system_instructions>
-You are an architectural-decision recorder. Your job is to create an **Architecture Decision Record (ADR)** documenting an important technical decision made during the current PRD phase.
+You are an architectural-decision recorder. Your job is to create an **Architecture Decision Record (ADR)** documenting an important technical decision — either repo-wide (`--scope=repo`, valid even before any PRD exists) or bound to an active PRD (`--scope=prd`).
 
 ## When to Use
 - Use when an architectural or design decision has been made and needs to be recorded for future reference (library choice, communication pattern, performance tradeoff, compliance-imposed constraint, etc.)
 - Use during `/dw-plan techspec` or `/dw-run` when the rationale for the decision does not fit in the techspec or the task file
+- Use **before any PRD exists** to record a repo-wide decision — pass `--scope=repo` (writes to `.dw/adrs/`).
 - Do NOT use for trivial or cheaply-reversible decisions (variable names, import order)
 - Do NOT use to record bugs or incidents (use `/dw-bugfix` or operational notes)
 
+<critical>Offer or create an ADR ONLY when all three criteria hold: (1) **hard to reverse**, (2) **surprising without context**, and (3) a **genuine trade-off** (a real alternative was considered and chosen against). If any one is missing, skip the ADR — do not turn the ADR log into noise. Creation ALWAYS needs explicit user approval, even when all three hold.</critical>
+
 ## Pipeline Position
-**Predecessor:** any point in the pipeline after `/dw-plan prd` | **Successor:** continue the previous flow (techspec, task, review)
+**Predecessor:** any point (repo-scoped ADRs work even before `/dw-plan prd`) | **Successor:** continue the previous flow (techspec, task, review)
 
 The ADR is **additive**: it does not replace any pipeline stage. Any existing command can invoke `/dw-adr` when a non-trivial decision needs a permanent record.
 
+## Scope (`--scope=repo|prd`)
+
+| Scope | Directory | When |
+|-------|-----------|------|
+| `repo` | `.dw/adrs/adr-NNN.md` | Repo-wide decision, and any decision made **before a PRD exists**. |
+| `prd` | `{{PRD_PATH}}/adrs/adr-NNN.md` | Decision bound to a specific active PRD. |
+
+**Default resolution** when `--scope` is not given (`--scope=` is always authoritative and overrides this):
+
+1. Determine the **candidate active PRDs** (see "Active PRD" below) — PRD directories in `.dw/spec/prd-*/` that are NOT terminal/historical.
+2. Exactly one candidate → default to `prd` (that PRD).
+3. Zero candidates (no PRD exists, or every PRD is terminal) → default to `repo`.
+4. Two or more candidates with no disambiguating signal → **ask** which PRD (or `repo`); never guess.
+
+### Active PRD (operational definition)
+
+Distinguish an **active** PRD from a **historical/terminal** one deterministically and conservatively, using evidence already in the repo — in this precedence:
+
+1. **Explicit target** — a PRD named in the request or passed as `{{PRD_PATH}}`. Wins outright.
+2. **Active session** — the PRD referenced by `.dw/STATE.md` (the current working spec), when present.
+3. **Current branch** — a `feat/prd-<slug>` checkout points at `prd-<slug>`.
+
+A PRD directory is **terminal/historical** (excluded from candidates) when its `prd.md` frontmatter/status marks it shipped, merged, delivered, done, archived, superseded, or cancelled. When none of signals 1–3 disambiguate and more than one non-terminal PRD remains, **ask** — do not guess. This reads only what the repo already records; it never invents state, a status field, or a migration.
+
+Numbering (`NNN`) is sequential **within the chosen scope's** ADR directory — repo ADRs and per-PRD ADRs have independent counters.
+
 ## Input Variables
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to the active PRD folder | `.dw/spec/prd-my-feature` |
+| `{{SCOPE}}` | `repo` or `prd` (optional; resolved by default rules above) | `repo` |
+| `{{PRD_PATH}}` | Path to the active PRD folder (only for `scope=prd`) | `.dw/spec/prd-my-feature` |
 | `{{TITLE}}` | Short imperative title of the decision | "Use PostgreSQL instead of MongoDB" |
 
-If `{{PRD_PATH}}` is not provided, ask the user which PRD is active (read `.dw/spec/` and list). If `{{TITLE}}` is not provided, ask.
+If `{{SCOPE}}` is not provided, resolve it per the Scope section (unique PRD → `prd`; no PRD → `repo`; multiple PRDs → ask). For `scope=prd`, if `{{PRD_PATH}}` is not provided, ask the user which PRD is active (read `.dw/spec/` and list). If `{{TITLE}}` is not provided, ask.
 
 ## File Locations
 
-- ADR directory: `{{PRD_PATH}}/adrs/`
-- New file: `{{PRD_PATH}}/adrs/adr-NNN.md` (NNN zero-padded to 3 digits)
+- **`scope=repo`** → directory `.dw/adrs/`, new file `.dw/adrs/adr-NNN.md`.
+- **`scope=prd`** → directory `{{PRD_PATH}}/adrs/`, new file `{{PRD_PATH}}/adrs/adr-NNN.md`.
+- NNN zero-padded to 3 digits, sequential within the chosen scope's directory.
 - Template: `.dw/templates/adr-template.md`
 
 ## Workflow
 
+### 0. Resolve scope
+- Determine `scope` from `--scope=` or the default resolution (unique active PRD → `prd`; no PRD → `repo`; ambiguous multiple PRDs → ask). Set the target ADR directory accordingly (`.dw/adrs/` for repo, `{{PRD_PATH}}/adrs/` for prd).
+- Confirm the three-criterion gate holds (hard to reverse + surprising + genuine trade-off) and get explicit user approval before writing.
+
 ### 1. Discover the next number
-- List files in `{{PRD_PATH}}/adrs/` (create the directory if missing)
+- List files in the target ADR directory (create it if missing)
 - Next number is `max(existing) + 1`, or `1` if empty
 
 ### 2. Gather context (minimum questions)
@@ -52,8 +87,9 @@ id: NNN
 status: Proposed | Accepted | Deprecated | Superseded
 title: [ADR title]
 date: YYYY-MM-DD
-prd: [PRD slug]
-schema_version: "1.0"
+scope: repo | prd
+prd: [PRD slug for scope=prd, or "n/a" for scope=repo]
+schema_version: "1.1"
 ---
 
 # ADR-NNN: [Title]
@@ -86,11 +122,13 @@ schema_version: "1.0"
 
 ### 4. Update cross-references
 
-If the ADR is created **during** a PRD execution, add a line to the "Related ADRs" section of related artifacts:
+If the ADR is created with **`scope=prd`** (during a PRD execution), add a line to the "Related ADRs" section of related artifacts:
 - `prd.md`, `techspec.md`, or `[N]_task.md`, matching the decision's scope
 
 If the "Related ADRs" section does not exist in the file, add it at the end.
 
+For **`scope=repo`** ADRs there is no owning PRD — set `prd: n/a` in the frontmatter and link related artifacts only when they genuinely apply (e.g. `.dw/constitution.md`, `.dw/rules/`). Repo ADRs are the natural home for decisions taken during a greenfield Grill session before any PRD exists.
+
 ### 5. Report
 
 Present to the user:
@@ -110,7 +148,7 @@ This command is inspired by the ADR pattern in `/tmp/compozy/.agents/skills/cy-c
 
 - Paths are `.dw/spec/<prd>/adrs/` instead of `.compozy/tasks/<name>/adrs/`
 - 4 minimum questions instead of Compozy's longer interactive flow (aligned with the concise style of other dw-* commands)
-- Explicit integration with `schema_version` of v1.0 templates
+- Explicit integration with `schema_version` v1.1 templates (adds `scope`; the PRD link is conditional so repo-scoped ADRs are coherent)
 
 Credit: Compozy project.
 

package/scaffold/en/commands/dw-analyze-project.md

@@ -32,6 +32,7 @@ The rules generated by this command are consumed by:
 <critical>This command ONLY generates documentation. Do NOT modify any project source code.</critical>
 <critical>Read actual source files to verify patterns — do not guess from file names alone.</critical>
 <critical>Include real code examples from the project in the generated rules.</critical>
+<critical>PRESERVE the Grill flow's domain artifacts. `.dw/domain/**` (glossary / context-map / per-context files) is human-curated canonical vocabulary owned by `/dw-brainstorm` grill — this command must NEVER regenerate, merge, or overwrite it. When `.dw/domain/**` exists, READ it and LINK it from `.dw/rules/index.md`; do not copy its terms into the auto-generated `.dw/rules/` files. This command owns `.dw/rules/**`; the Grill flow owns `.dw/domain/**`.</critical>
 
 ## Objective
 
@@ -225,6 +226,10 @@ For each module/project detected, identify:
 | **Auth** | NextAuth, Passport, Keycloak, Auth0, etc. | Dependencies + auth-related files |
 | **API Style** | REST, GraphQL, tRPC, gRPC | Route definitions, schema files |
 
+#### Curated baseline (rules-library)
+
+After detecting the stack(s), consult `.dw/config/stack-mappings.json`: each matched stack points to its curated baseline in `.dw/rules-library/` (`common.md` + `<stack>.md`) — the declarative "what good code looks like here" default. **Reference** these files (do NOT copy them into `.dw/rules/`): the analytical rules you write describe what the code IS; the library describes what it SHOULD be. Load only the matched stacks' files to protect the context budget.
+
 #### Frontend Health Baseline
 
 When React is detected, run `npx react-doctor@latest --verbose` and include the health score in the generated rules as a baseline metric.
@@ -494,8 +499,11 @@ workspace-root/
 
 - See [{module}]({module}.md) for detailed rules per module
 - See [integrations.md](integrations.md) for inter-project communication (if monorepo)
+- See [domain glossary](../domain/glossary.md) — or [context map](../domain/context-map.md) — for canonical vocabulary (only when `.dw/domain/` exists; owned by Grill, read-only here, never regenerated)
 ```
 
+> When `.dw/domain/**` exists, add the Domain Vocabulary link(s) above to the generated `index.md` and leave the domain files untouched. When it does not exist, omit the link — this command never creates `.dw/domain/**` (only `/dw-brainstorm` grill does, after explicit authorization).
+
 #### 7.2 `.dw/rules/{module}.md` (per module)
 
 ```markdown
@@ -740,7 +748,7 @@ Three options:
 
 **Option A — Synthesize:**
 
-1. Read `.dw/rules/index.md` + each `.dw/rules/{module}.md`.
+1. Read `.dw/rules/index.md` + each `.dw/rules/{module}.md`, plus the curated baseline for the detected stack(s) in `.dw/rules-library/` (`common.md` + `<stack>.md`). A baseline principle the project already follows is a well-grounded proposal — cite the rules-library file as its evidence.
 2. Propose 5–8 principles. Each must:
    - Have a unique `P-NNN` ID.
    - Map to an observation in `.dw/rules/` (cite the rule file + section).
@@ -873,6 +881,7 @@ Before declaring the analysis complete, verify:
 - [ ] Step 9 (concerns map) presented candidates, awaited approval, wrote `.dw/rules/concerns.md` (or noted no signals)
 - [ ] Step 10 (design authority) ran for frontend projects: existing authority respected, or `DESIGN.md` generated from real tokens, or curated-defaults bootstrap recommended
 - [ ] Preserved-marker blocks in concerns.md kept verbatim on refresh
+- [ ] `.dw/domain/**` (glossary / context-map) preserved verbatim and linked from index.md when present — never regenerated or overwritten
 - [ ] Topology analysis completed (god nodes, coupling metrics, dependency graph)
 - [ ] Critical nodes table generated with Ca, Ce, instability
 - [ ] Circular dependencies identified and documented