@brunosps00/dev-workflow 1.4.0 → 1.5.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.5.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.5.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`. |

package/lib/constants.js

@@ -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.' },
@@ -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,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.4.0",
+  "version": "1.5.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"

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-analyze-project.md

@@ -225,6 +225,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.
@@ -740,7 +744,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).

package/scaffold/en/commands/dw-context-budget.md

@@ -21,6 +21,15 @@ You are the context budget auditor for dev-workflow.
    - Claude/OpenCode agent files with provider-incompatible tool or permission fields.
 4. Recommend the top 5 savings with concrete paths.
 
+## Part B — Runtime spend (actual token cost)
+
+Static overhead (above) is what the harness *loads*; this part is what sessions actually *cost*. Report from `.dw/metrics/costs.jsonl` (appended by the `session-cost` SessionEnd hook — one row per session with per-model token usage + estimated USD):
+
+1. Read `.dw/metrics/costs.jsonl` if present. If absent, note "no runtime cost data yet (hook disabled or no session has ended)" and skip this part — never fail.
+2. Dedupe by `session_id` (latest row per session wins).
+3. Report: estimated spend today and over the last 7 days; the 3 most expensive sessions; and the per-model split (which model burned the most).
+4. USD is a best-effort estimate from `.dw/scripts/lib/model-prices.json` — token counts are exact, prices may drift. Flag any model that resolved to `_default`/`_unknown` (missing price entry to add).
+
 ## Output
 Write a concise report in chat. If `.dw/reports/` exists, also write `.dw/reports/context-budget.md`.
 

package/scaffold/en/commands/dw-harness-audit.md

@@ -26,6 +26,9 @@ You are the dev-workflow harness auditor.
 4. Cite missing paths, broken references, stale managed files, and skills without a structured return.
 5. Recommend the top 3 fixes.
 
+## Runtime degradation triage (on-demand)
+The scorecard above is deterministic **install** health. If instead the *agent* is misbehaving at runtime (loops, objective drift, hallucinated edits, degraded reasoning), that is a different diagnosis: point the user to `.agents/skills/dw-debug-protocol/references/agent-degradation.md` (symptom→cause table + ordered recovery). Advisory only — it does not affect the scorecard.
+
 ## Output
 Return a scorecard and do not mutate files. Tell the user to run `dev-workflow repair` for managed-file drift.
 

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

@@ -0,0 +1,41 @@
+<system_instructions>
+You are the learning synthesizer for dev-workflow. You turn what this project's work has ALREADY recorded into atomic, confidence-weighted **instincts** the team can reuse — and you NEVER write anything without explicit approval.
+
+## When to Use
+- After a run of related work (a few tasks, a bugfix batch) to capture what was learned.
+- When the user says "learn from this", "what patterns emerged", or "promote what we learned".
+- Periodically, to propose constitution principles grounded in real, repeated practice.
+
+Do NOT invent best practices from nothing — every instinct must be grounded in this project's records.
+
+## Sources (read-only; there is NO always-on observer)
+Gather signals only from what is already persisted:
+1. `.dw/spec/*/MEMORY.md` — durable decisions, especially those tagged `[confidence: …]` (see the `dw-memory` skill).
+2. `.dw/bugfixes/*/SUMMARY.md` — recurring root causes and the guards added.
+3. `.dw/spec/*/deviations.md` — where the plan met reality.
+4. Recent git history — `git log --oneline -50` and commit-message patterns.
+5. Existing `.dw/memory/instincts/*.md` — to UPDATE confidence, not duplicate.
+
+## Process
+1. **Cluster** repeated signals into candidate instincts. A candidate needs **≥2 independent confirmations** (two tasks, a decision + a bugfix, a repeated commit pattern). A one-off is NOT an instinct.
+2. **Score** each candidate's confidence (0.3–0.9) using the `dw-memory` confidence rule; name the evidence.
+3. **Classify** `domain` (code-style / testing / error-handling / git / workflow / security) and `scope` (project by default).
+4. **Present** candidates in chat as a markdown list — id, trigger, action, confidence, evidence. Do NOT write yet.
+5. **Ask**: "Approve which to store? (ids, or 'all', or 'none'). Any to promote to a constitution principle?"
+6. On approval:
+   - Write each approved instinct to `.dw/memory/instincts/<slug>.md` in the format from `.agents/skills/dw-memory/references/instincts.md` (create or update; never duplicate an existing id).
+   - For any the user chooses to promote, hand off to the constitution flow — propose a `P-NNN` principle at `severity: info` for `/dw-analyze-project` Step 8. Do NOT edit `.dw/constitution.md` directly without the user re-confirming.
+7. Update confidence on existing instincts that new evidence reconfirms or contradicts.
+
+## Rules
+- Never write an instinct or a constitution change without explicit approval (mirrors constitution + STATE handling).
+- Ground every instinct in cited evidence; drop candidates you cannot ground in ≥2 confirmations.
+- Keep instincts atomic — one trigger, one action. Split compound learnings.
+- Project scope by default; mark `global` only when the pattern is seen across projects.
+- This command reads and proposes; it NEVER modifies source code.
+
+## Output
+A list of proposed/updated instincts (id, trigger, action, confidence, evidence); then, after approval, the files written under `.dw/memory/instincts/` and any constitution proposals handed off.
+
+Final marker: `## LEARN COMPLETE`
+</system_instructions>

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

@@ -70,6 +70,8 @@ The tool is mandatory for planning because it preserves explicit user choices an
 
 If `.dw/intel/` doesn't exist, fall back to `.dw/rules/` and direct grep. Suggest `/dw-intel --build` to populate intel for richer downstream context.
 
+If `.dw/memory/instincts/` has entries, load any with confidence ≥0.7 whose `trigger` matches the feature (lazy, by trigger only) — they encode learned project conventions from `/dw-learn` worth respecting in the spec.
+
 ## Stage 1 — PRD generation
 
 Runs when default mode OR `plan prd`.

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

@@ -139,6 +139,7 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
    - General patterns: no `any` types in TS, no `console.log` in prod, error handling, multi-tenancy.
    - Backend patterns from `.dw/rules/<backend>.md`: Clean Architecture, use-case return types, DTOs, parameterized queries.
    - Frontend patterns from `.dw/rules/<frontend>.md`: Server Components default, forms patterns, design system.
+   - Curated baseline: check the diff against the active stack's `.dw/rules-library/<stack>.md` (+ `common.md`) as the declarative bar. The project's own `.dw/rules/` and `.dw/constitution.md` override it where they differ.
 
 3. **Constitution compliance** (against `.dw/constitution.md`):
    - For each principle, check diff for violations per the principle's Enforcement line.

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

@@ -31,6 +31,7 @@ When available under `./.agents/skills/`, these skills are invoked per task:
 
 - `dw-verify`: **ALWAYS** — before each task's commit, produces a Verification Report (test + lint + build all GREEN). Without PASS, no commit. The Iron Law of verification.
 - `dw-memory`: **ALWAYS** — reads workflow memory at task start; updates at task end with the promotion test (lessons that apply to next task get promoted to shared MEMORY.md).
+- Instincts (lazy): at task start, also load any high-confidence instinct (`.dw/memory/instincts/`, confidence ≥0.7) whose `trigger` matches the task — learned project conventions promoted by `/dw-learn`. Match by trigger only; never bulk-load the set.
 - `dw-execute-phase`: provides `plan-checker` (6-dimension goal-backward verification before any code is touched in plan mode) and `executor` (atomic commit + deviation handling) agents.
 - `dw-testing-discipline`: applies the placement doctrine, 6 agent guardrails, and 25 anti-patterns when adding tests during the task.
 - `dw-ui-discipline`: when the task touches UI, the 4 grounding questions must be answered before any visual decision lands.

package/scaffold/pt-br/commands/dw-analyze-project.md

@@ -213,6 +213,10 @@ Para cada projeto/módulo detectado, identificar:
 | **Containerização** | Dockerfile, docker-compose.yml |
 | **Monorepo tools** | Turborepo, Nx, Lerna, pnpm workspaces |
 
+#### Baseline curada (rules-library)
+
+Após detectar a(s) stack(s), consulte `.dw/config/stack-mappings.json`: cada stack casada aponta para sua baseline curada em `.dw/rules-library/` (`common.md` + `<stack>.md`) — o default declarativo "como um bom código se parece aqui". **Referencie** esses arquivos (NÃO copie para `.dw/rules/`): as rules analíticas que você escreve descrevem o que o código É; a library descreve o que ele DEVERIA ser. Carregue só os arquivos das stacks casadas para proteger o budget de contexto.
+
 #### Baseline de Saúde do Frontend
 
 Quando React for detectado, execute `npx react-doctor@latest --verbose` e inclua o health score nas rules geradas como métrica baseline.
@@ -680,7 +684,7 @@ Três opções:
 
 **Opção A — Sintetizar:**
 
-1. Ler `.dw/rules/index.md` + cada `.dw/rules/{module}.md`.
+1. Ler `.dw/rules/index.md` + cada `.dw/rules/{module}.md`, mais a baseline curada da(s) stack(s) detectada(s) em `.dw/rules-library/` (`common.md` + `<stack>.md`). Um princípio da baseline que o projeto já segue é uma proposta bem-fundamentada — cite o arquivo da rules-library como evidência.
 2. Propor 5–8 princípios. Cada um deve:
    - Ter ID único `P-NNN`.
    - Mapear para uma observação em `.dw/rules/` (citar o arquivo + seção).

package/scaffold/pt-br/commands/dw-context-budget.md

@@ -21,6 +21,15 @@ Voce e o auditor de orcamento de contexto do dev-workflow.
    - agentes Claude/OpenCode com campos de tools ou permissions incompativeis com o provider.
 4. Recomende as 5 maiores economias com caminhos concretos.
 
+## Parte B — Gasto em runtime (custo real de token)
+
+O overhead estatico (acima) e o que o harness *carrega*; esta parte e o que as sessoes de fato *custam*. Reporte a partir de `.dw/metrics/costs.jsonl` (append pelo hook `session-cost` de SessionEnd — uma linha por sessao com uso de tokens por modelo + USD estimado):
+
+1. Leia `.dw/metrics/costs.jsonl` se existir. Se ausente, registre "sem dados de custo runtime ainda (hook desabilitado ou nenhuma sessao encerrada)" e pule esta parte — nunca falhe.
+2. Deduplique por `session_id` (a linha mais recente por sessao vence).
+3. Reporte: gasto estimado hoje e nos ultimos 7 dias; as 3 sessoes mais caras; e o split por modelo (qual modelo gastou mais).
+4. USD e estimativa best-effort de `.dw/scripts/lib/model-prices.json` — contagem de tokens e exata, precos podem defasar. Sinalize modelos que resolveram para `_default`/`_unknown` (falta entrada de preco).
+
 ## Saida
 Responda com um relatorio conciso. Se `.dw/reports/` existir, escreva tambem `.dw/reports/context-budget.md`.
 

package/scaffold/pt-br/commands/dw-harness-audit.md

@@ -26,6 +26,9 @@ Voce e o auditor do harness dev-workflow.
 4. Cite paths ausentes, referencias quebradas, arquivos gerenciados stale, e skills sem retorno estruturado.
 5. Recomende os 3 principais fixes.
 
+## Triagem de degradacao em runtime (sob demanda)
+O scorecard acima e saude deterministica da **instalacao**. Se o problema for o *agente* se comportando mal em runtime (loops, desvio do objetivo, edicoes alucinadas, raciocinio degradado), o diagnostico e outro: aponte o usuario para `.agents/skills/dw-debug-protocol/references/agent-degradation.md` (tabela sintoma→causa + recovery ordenado). Apenas informativo — nao afeta o scorecard.
+
 ## Saida
 Retorne um scorecard e nao altere arquivos. Para drift de arquivo gerenciado, indique `dev-workflow repair`.
 

package/scaffold/pt-br/commands/dw-learn.md

@@ -0,0 +1,41 @@
+<system_instructions>
+Voce e o sintetizador de aprendizado do dev-workflow. Voce transforma o que o trabalho deste projeto JA registrou em **instincts** atomicos e ponderados por confianca que o time pode reusar — e NUNCA escreve nada sem aprovacao explicita.
+
+## Quando Usar
+- Apos uma leva de trabalho relacionado (algumas tasks, um lote de bugfixes) para capturar o que foi aprendido.
+- Quando o usuario disser "aprenda com isso", "que padroes emergiram" ou "promova o que aprendemos".
+- Periodicamente, para propor principios de constitution fundamentados em pratica real e repetida.
+
+NAO invente boas praticas do nada — todo instinct precisa estar fundamentado nos registros deste projeto.
+
+## Fontes (somente leitura; NAO ha observador sempre-ligado)
+Colete sinais apenas do que ja esta persistido:
+1. `.dw/spec/*/MEMORY.md` — decisoes duraveis, especialmente as marcadas com `[confidence: …]` (veja a skill `dw-memory`).
+2. `.dw/bugfixes/*/SUMMARY.md` — causas-raiz recorrentes e os guards adicionados.
+3. `.dw/spec/*/deviations.md` — onde o plano encontrou a realidade.
+4. Historico git recente — `git log --oneline -50` e padroes de mensagem de commit.
+5. `.dw/memory/instincts/*.md` existentes — para ATUALIZAR confianca, nao duplicar.
+
+## Processo
+1. **Clusterize** sinais repetidos em candidatos a instinct. Um candidato precisa de **≥2 confirmacoes independentes** (duas tasks, uma decisao + um bugfix, um padrao de commit repetido). Um caso unico NAO e instinct.
+2. **Pontue** a confianca de cada candidato (0.3–0.9) pela regra de confianca do `dw-memory`; nomeie a evidencia.
+3. **Classifique** `domain` (code-style / testing / error-handling / git / workflow / security) e `scope` (project por padrao).
+4. **Apresente** os candidatos no chat como lista markdown — id, trigger, action, confidence, evidence. NAO escreva ainda.
+5. **Pergunte**: "Aprovar quais para armazenar? (ids, ou 'todos', ou 'nenhum'). Algum para promover a principio de constitution?"
+6. Na aprovacao:
+   - Grave cada instinct aprovado em `.dw/memory/instincts/<slug>.md` no formato de `.agents/skills/dw-memory/references/instincts.md` (crie ou atualize; nunca duplique um id existente).
+   - Para os que o usuario escolher promover, encaminhe ao fluxo de constitution — proponha um principio `P-NNN` em `severity: info` para o Step 8 do `/dw-analyze-project`. NAO edite `.dw/constitution.md` direto sem o usuario reconfirmar.
+7. Atualize a confianca de instincts existentes que a nova evidencia reconfirme ou contradiga.
+
+## Regras
+- Nunca escreva um instinct ou mudanca de constitution sem aprovacao explicita (espelha o tratamento de constitution + STATE).
+- Fundamente todo instinct em evidencia citada; descarte candidatos que nao consiga fundamentar em ≥2 confirmacoes.
+- Mantenha instincts atomicos — um trigger, uma action. Divida aprendizados compostos.
+- Scope `project` por padrao; marque `global` so quando o padrao aparece entre projetos.
+- Este comando le e propoe; NUNCA modifica codigo-fonte.
+
+## Saida
+Uma lista de instincts propostos/atualizados (id, trigger, action, confidence, evidence); depois, apos aprovacao, os arquivos gravados em `.dw/memory/instincts/` e quaisquer propostas de constitution encaminhadas.
+
+Marcador final: `## LEARN COMPLETE`
+</system_instructions>

package/scaffold/pt-br/commands/dw-plan.md

@@ -70,6 +70,8 @@ A ferramenta e obrigatoria no planejamento porque preserva escolhas explicitas d
 
 Se `.dw/intel/` não existir, caia para `.dw/rules/` e grep direto. Sugira `/dw-intel --build` para popular o intel.
 
+Se `.dw/memory/instincts/` tiver entradas, carregue as de confidence ≥0.7 cujo `trigger` case com a feature (lazy, só por trigger) — codificam convenções aprendidas pelo `/dw-learn` que valem respeitar no spec.
+
 ## Estágio 1 — Geração de PRD
 
 Roda em modo padrão OU `plan prd`.

package/scaffold/pt-br/commands/dw-review.md

@@ -139,6 +139,7 @@ Se FALTANDO > 0, o veredicto sugere revisitar `/dw-plan tasks` pra escopar ou `/
    - Padrões gerais: sem `any` em TS, sem `console.log` em prod, error handling, multi-tenancy.
    - Backend patterns de `.dw/rules/<backend>.md`: Clean Architecture, use-case return types, DTOs, queries parametrizadas.
    - Frontend patterns de `.dw/rules/<frontend>.md`: Server Components default, forms patterns, design system.
+   - Baseline curada: verifique o diff contra a `.dw/rules-library/<stack>.md` (+ `common.md`) da stack ativa como régua declarativa. As `.dw/rules/` do projeto e a `.dw/constitution.md` sobrepõem onde diferirem.
 
 3. **Constitution compliance** (contra `.dw/constitution.md`):
    - Para cada princípio, checar diff por violações conforme linha Enforcement do princípio.

package/scaffold/pt-br/commands/dw-run.md

@@ -31,6 +31,7 @@ Quando disponíveis em `./.agents/skills/`, estas skills são invocadas por task
 
 - `dw-verify`: **SEMPRE** — antes do commit de cada task, produz Verification Report (test + lint + build GREEN). Sem PASS, sem commit. Iron Law de verificação.
 - `dw-memory`: **SEMPRE** — lê workflow memory no início; atualiza no fim com promotion test (lições que valem pra próxima task são promovidas pra MEMORY.md compartilhada).
+- Instincts (lazy): no início da task, carregue também qualquer instinct de alta confiança (`.dw/memory/instincts/`, confidence ≥0.7) cujo `trigger` case com a task — convenções aprendidas promovidas pelo `/dw-learn`. Case por trigger; nunca carregue o conjunto inteiro.
 - `dw-execute-phase`: fornece agentes `plan-checker` (verificação goal-backward em 6 dimensões antes do código ser tocado) e `executor` (commit atômico + deviation handling).
 - `dw-testing-discipline`: aplica placement doctrine, 6 agent guardrails e 25 anti-patterns ao adicionar testes.
 - `dw-ui-discipline`: quando task toca UI, as 4 grounding questions precisam ser respondidas antes de qualquer decisão visual.

package/scaffold/rules/README.md

@@ -0,0 +1,22 @@
+# Rules library — curated declarative baseline
+
+Curated "what good code SHOULD look like" per stack, installed to `.dw/rules-library/`. This is the third
+leg of the rules model:
+
+| Source | Type | Answers | Authored by |
+|---|---|---|---|
+| `.dw/rules-library/` | Curated baseline (this) | what good code looks like in `<stack>` | dev-workflow (shipped) |
+| `.dw/rules/` | Analytical | what THIS code **is** (observed patterns) | `/dw-analyze-project` |
+| `.dw/constitution.md` | Declarative, committed | what THIS project **commits to** | `/dw-analyze-project` (Step 8) |
+
+## Precedence
+
+A language file overrides `common` where idioms differ. The project's own `.dw/rules/` and
+`.dw/constitution.md` override the library — they describe THIS project; the library is only the default a
+project starts from.
+
+## Loading (lazy — protect the context budget)
+
+Commands load ONLY the files for the **active stack**, resolved via `.dw/config/stack-mappings.json`
+(`common.md` + `<stack>.md`). Never load the whole library. `/dw-analyze-project` uses it to seed
+constitution proposals; `/dw-review` reads the active stack's baseline as the declarative bar.

package/scaffold/rules/common.md

@@ -0,0 +1,29 @@
+# Baseline rules — common (all languages)
+
+Declarative baseline: what code SHOULD be, regardless of stack. Language files override or specialize these
+where idioms differ. Complements `.dw/rules/` (observed) and `.dw/constitution.md` (committed).
+
+## Code style
+- Prefer immutability: return new values, don't mutate inputs. Mutate only in a measured hot path.
+- Name for intent: `overdueInvoices`, not `data`/`tmp`/`x`. A name that needs a comment is the wrong name.
+- Keep functions small and single-purpose; extract when a block needs its own comment to be understood.
+- No magic values: name constants (except self-evident ones like HTTP codes or `0`/`-1` indexes).
+
+## Error handling
+- Never swallow errors. Handle, propagate, or log with context — never an empty catch (see `dw-silent-failure`).
+- Validate untrusted input once, where it enters the system; fail loudly at boundaries.
+- Timeout on every network/IO call; rollback partial transactional work.
+
+## Testing
+- Test behavior, not implementation. A test that breaks on a rename tested the wrong thing.
+- Cover error and edge paths (empty, null, boundary, failure), not just the happy path.
+- New bug → regression test first, then fix (see `dw-testing-discipline`).
+
+## Security
+- No secrets in code or logs. Read from env/secret store; `.env` is gitignored.
+- Validate input at the boundary; encode output at the boundary.
+- Least privilege for every credential, token, and role.
+
+## Git
+- One intent per commit; Conventional Commits subject (see `dw-git-discipline`).
+- Never force-push shared history; rebase only local branches.

package/scaffold/rules/csharp.md

@@ -0,0 +1,18 @@
+# Baseline rules — C# / .NET (extends common)
+
+## Style
+- Nullable reference types enabled; warnings as errors. `record`/`readonly` for value types.
+- `async`/`await` end-to-end; never `.Result`/`.Wait()` (deadlocks). Thread `CancellationToken` through.
+- `using` declarations for `IDisposable`; dependency injection over `new` for services.
+
+## Errors
+- Catch specific exceptions; never empty catch. Don't use exceptions for normal control flow.
+- Validate arguments at public boundaries (`ArgumentNullException.ThrowIfNull`).
+
+## Testing
+- xUnit/NUnit; test public behavior. Mock owned boundaries, not the system under test itself.
+- Arrange-Act-Assert; one behavior per test.
+
+## Security
+- Parameterized queries / EF Core — never concatenate SQL. Validate/encode at boundaries.
+- Secrets via configuration / user-secrets / Key Vault, never in source.