wize-dev-kit 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-06-12
+
+Adds a single-command diagnostic plus traceable GitHub Releases on every tag.
+
+### Added — `wize-dev-kit doctor`
+
+Single-command snapshot of kit + project + environment, plus a ranked list of suggestions. Designed to be the first command a new developer runs in an unfamiliar wize-enabled repo, and the go-to command when something looks off. Sections covered:
+
+- **Kit versions** (installed, project-pinned in `kit_version`, registry-latest) — flags drift between any of them.
+- **Project** — name, profiles, IDE targets, languages, current phase (heuristic: brief → trigger-map → PRD → UX → tech-vision → architecture → stories → risk profile → sprint planning → implementation).
+- **IDE Adapters** — file count per target (`.claude/skills/`, `.cursor/rules/`, etc.). Flags adapters that didn't render and points at `wize-dev-kit sync`.
+- **TEA gates** — counts PASS / CONCERNS / FAIL / WAIVED across `gate.md` files in `.wize/implementation/tea/`. Flags any FAIL or CONCERNS.
+- **Knowledge baseline** — `last_refreshed` age per `document-project/*.md` file, plus inline-note count in `_pending.md`. Suggests `wize-refresh-knowledge` when files go stale (> 60 days) or pending notes pile up (≥ 5).
+- **Harness CLIs on PATH** — claude / codex / opencode, with detected install paths.
+- **Git** — branch / head, repo presence.
+
+Implementation in `tools/installer/commands/doctor.js`. 11 new unit tests cover phase detection, gate counting, knowledge parsing, adapter path mapping, and end-to-end run on a minimal install.
+
+Output is plain text (no colors) so it's grep-friendly and pipe-friendly. Section headers are stable for editors / dashboards to parse.
+
+### Added — GitHub Release on every tag
+
+After a successful `npm publish` from a `v*` tag, the workflow now:
+
+1. Extracts the matching version's CHANGELOG entry (`## [VERSION]` to the next `## [`) with a small awk filter.
+2. Creates a GitHub Release at the tag using `softprops/action-gh-release@v2`, with the CHANGELOG entry as the release body.
+3. If no CHANGELOG entry is found for the version, falls back to GitHub's auto-generated notes.
+
+Pre-release tags (`-alpha`, `-beta`, `-rc`) are marked as pre-release automatically. Requires `permissions: contents: write` (added to the publish job).
+
+### Tests
+
+- Total: **115 passing** (was 104).
+
 ## [0.2.5] — 2026-06-12
 
 Fixes a real install-time bug that bit non-TTY users (CI smoke + anyone piping input into `wize-dev-kit install`).
@@ -262,7 +296,8 @@ Ignore (handled by the suggested block): `.wize/config/user.toml`, `.wize/scratc
 - Inspired by [BMAD Method v6.8.0](https://github.com/bmad-code-org/BMAD-METHOD).
 - WDS module inspired by [bmad-method-wds-expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion).
 
-[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.5...v0.3.0
 [0.2.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.2...v0.2.3

package/README.md

@@ -144,6 +144,7 @@ npx wize-dev-kit sync            # re-render IDE adapters after editing config
 npx wize-dev-kit agent list      # list built-in + custom agents
 npx wize-dev-kit agent create    # scaffold a new custom agent (validated + dry-run)
 npx wize-dev-kit agent edit <code>  # override a built-in via .wize/custom/agents/<code>/customize.toml
+npx wize-dev-kit doctor          # diagnose kit / project / adapters / gates and suggest fixes
 npx wize-dev-kit validate        # structural checks on the kit assets
 npx wize-dev-kit uninstall       # remove .wize/ (your code is left untouched)
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/tools/installer/commands/doctor.js

@@ -0,0 +1,293 @@
+// `wize-dev-kit doctor` — single-command diagnose.
+//
+// Prints a structured snapshot of the kit + the project + the surrounding
+// environment, plus a list of actionable suggestions ranked by severity.
+// Designed to be the *first* command a new dev runs in an unfamiliar
+// wize-enabled repo, and the *go-to* command when something looks off.
+//
+// Output is plain text (no colors by default) so it's grep-friendly and pipe-
+// friendly. Sections are stable so editors / dashboards can parse them.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadProjectConfig, loadInstalledKitVersion } = require('./update.js');
+const { detectHarnessCli } = require('../baseline.js');
+const { getLatestVersion, semverGreater } = require('../version-check.js');
+
+function fileExists(p) { try { return fs.statSync(p).isFile(); } catch { return false; } }
+function dirExists(p)  { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+function readSafe(p)   { try { return fs.readFileSync(p, 'utf-8'); } catch { return ''; } }
+
+function listFilesUnder(root, pattern) {
+  if (!dirExists(root)) return [];
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries; try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile() && pattern.test(e.name)) out.push(full);
+    }
+  }
+  return out;
+}
+
+function parseGateStatus(content) {
+  // Find a `status: PASS|CONCERNS|FAIL|WAIVED` line in YAML frontmatter.
+  const m = content.match(/^status:\s*(PASS|CONCERNS|FAIL|WAIVED)\s*$/m);
+  return m ? m[1] : null;
+}
+
+function parseLastRefreshed(content) {
+  const m = content.match(/^last_refreshed:\s*([\d-]+)/m);
+  return m ? m[1] : null;
+}
+
+function daysAgo(dateStr) {
+  const t = Date.parse(dateStr);
+  if (Number.isNaN(t)) return null;
+  return Math.floor((Date.now() - t) / (24 * 3600 * 1000));
+}
+
+function adapterTargetPath(targetCode, projectRoot) {
+  // Mirror of the adapter render conventions documented in adapters/README.md.
+  switch (targetCode) {
+    case 'claude-code':  return path.join(projectRoot, '.claude/skills');
+    case 'antigravity':  return path.join(projectRoot, '.agent/skills');
+    case 'codex':        return path.join(projectRoot, '.agents/skills');
+    case 'kimi-code':    return path.join(projectRoot, '.kimi/skills');
+    case 'cursor':       return path.join(projectRoot, '.cursor/rules');
+    case 'windsurf':     return path.join(projectRoot, '.windsurf/rules');
+    case 'continue':     return path.join(projectRoot, '.continue/prompts');
+    case 'opencode':     return path.join(projectRoot, '.opencode/agents');
+    case 'generic':      return path.join(projectRoot, '.wize/agents');
+    default:             return null;
+  }
+}
+
+function countAdapterFiles(targetCode, projectRoot) {
+  const dir = adapterTargetPath(targetCode, projectRoot);
+  if (!dir || !dirExists(dir)) return 0;
+  // Be permissive on file extension; .mdc, .md, .prompt, and SKILL.md dirs all count.
+  let count = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    let entries; try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile()) count++;
+    }
+  }
+  return count;
+}
+
+function detectPhase(projectRoot) {
+  const has = (p) => fileExists(path.join(projectRoot, p)) || dirExists(path.join(projectRoot, p));
+  if (!dirExists(path.join(projectRoot, '.wize'))) return 'no-install';
+  if (!has('.wize/planning/brief.md')) return '1-analysis (brief pending)';
+  if (!has('.wize/planning/ux/trigger-map.md')) return '1-analysis (trigger map pending)';
+  if (!has('.wize/planning/prd.md')) return '2-plan (PRD pending)';
+  if (!has('.wize/planning/ux/ux-scenarios.md')) return '2-plan (UX scenarios pending)';
+  if (!has('.wize/planning/tech-vision.md')) return '2→3 boundary (Fury pending)';
+  if (!has('.wize/solutioning/architecture.md')) return '3-solutioning (architecture pending)';
+  if (!dirExists(path.join(projectRoot, '.wize/solutioning/stories')) ||
+      listFilesUnder(path.join(projectRoot, '.wize/solutioning/stories'), /\.md$/).length === 0)
+    return '3-solutioning (stories pending)';
+  if (!has('.wize/implementation/tea/risk-profile.md')) return '3-closeout (risk profile pending)';
+  if (!has('.wize/implementation/sprint-status.md')) return '4-implementation (sprint planning pending)';
+  return '4-implementation';
+}
+
+function gateStats(projectRoot) {
+  const root = path.join(projectRoot, '.wize/implementation/tea');
+  const files = listFilesUnder(root, /^gate\.md$/);
+  const stats = { PASS: 0, CONCERNS: 0, FAIL: 0, WAIVED: 0, total: files.length };
+  for (const f of files) {
+    const s = parseGateStatus(readSafe(f));
+    if (s && stats[s] !== undefined) stats[s]++;
+  }
+  return stats;
+}
+
+function knowledgeStatus(projectRoot) {
+  const root = path.join(projectRoot, '.wize/knowledge/document-project');
+  const exists = dirExists(root);
+  if (!exists) return { exists: false };
+  const files = ['overview.md', 'architecture-snapshot.md', 'conventions.md', 'dependencies.md', 'risk-spots.md']
+    .map(name => path.join(root, name))
+    .filter(fileExists);
+  const refreshed = files.map(f => ({
+    name: path.basename(f),
+    days: daysAgo(parseLastRefreshed(readSafe(f)))
+  }));
+  const pendingFile = path.join(root, '_pending.md');
+  const pendingLines = fileExists(pendingFile)
+    ? readSafe(pendingFile).split('\n').filter(l => l.trim() && !l.startsWith('#')).length
+    : 0;
+  return { exists: true, files: refreshed, pendingLines };
+}
+
+function gitInfo(projectRoot) {
+  const dotGit = path.join(projectRoot, '.git');
+  if (!dirExists(dotGit)) return { isRepo: false };
+  let branch = '?'; let head = '?';
+  try {
+    const HEAD = readSafe(path.join(dotGit, 'HEAD')).trim();
+    if (HEAD.startsWith('ref: ')) {
+      branch = HEAD.slice(5).replace('refs/heads/', '');
+    } else {
+      head = HEAD.slice(0, 7);
+    }
+  } catch (_) {}
+  return { isRepo: true, branch, head };
+}
+
+function severityIcon(level) {
+  return level === 'error' ? '✖' : level === 'warn' ? '⚠' : 'ℹ';
+}
+
+async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const cwd = projectRoot;
+  const cfg = loadProjectConfig(cwd);
+  const installed = loadInstalledKitVersion(kitRoot);
+  const phase = detectPhase(cwd);
+  const gates = gateStats(cwd);
+  const knowledge = knowledgeStatus(cwd);
+  const git = gitInfo(cwd);
+  const targets = (cfg.install && cfg.install.ide_targets) || [];
+  const profiles = (cfg.install && cfg.install.profiles) || [];
+  const harnesses = detectHarnessCli({ preferIde: targets });
+
+  // Try registry — best-effort, never blocks.
+  let registryLatest = null;
+  try { registryLatest = await getLatestVersion(); } catch (_) {}
+
+  const suggestions = [];
+
+  // -- Section: Kit --
+  log('');
+  log('Wize Dev Kit — Doctor');
+  log('─────────────────────');
+  log(`Kit version (installed):   ${installed || '?'}`);
+  log(`Kit version (project):     ${cfg.project && cfg.project.kit_version || '— (no install)'}`);
+  log(`Kit version (registry):    ${registryLatest || '(offline or skipped)'}`);
+  if (installed && cfg.project && cfg.project.kit_version && installed !== cfg.project.kit_version) {
+    suggestions.push({ level: 'warn', text: `Project pinned to ${cfg.project.kit_version} but ${installed} is installed. Run \`npx wize-dev-kit update\` to refresh adapters.` });
+  }
+  if (registryLatest && installed && semverGreater(registryLatest, installed)) {
+    suggestions.push({ level: 'info', text: `Registry has ${registryLatest}; you're on ${installed}. Run \`npx wize-dev-kit@latest update\` to pick it up.` });
+  }
+
+  // -- Section: Project --
+  log('');
+  log('Project');
+  log('───────');
+  if (!cfg.project) {
+    log('No .wize/config/project.toml — kit is not installed here.');
+    suggestions.push({ level: 'error', text: 'Run `npx wize-dev-kit install` to set the kit up in this repo.' });
+  } else {
+    log(`Name:                 ${cfg.project.name || '?'}`);
+    log(`Profiles:             ${profiles.join(', ') || '(none)'}`);
+    log(`IDE targets:          ${targets.join(', ') || '(none)'}`);
+    log(`Communication lang:   ${cfg.language && cfg.language.communication || '?'}`);
+    log(`Document lang:        ${cfg.language && cfg.language.document_output || '?'}`);
+    log(`Current phase:        ${phase}`);
+  }
+
+  // -- Section: Adapters --
+  if (cfg.install) {
+    log('');
+    log('IDE Adapters');
+    log('────────────');
+    for (const t of targets) {
+      const dir = adapterTargetPath(t, cwd);
+      const count = countAdapterFiles(t, cwd);
+      const status = count > 0 ? `✓ ${count} files` : '✖ none';
+      log(`  ${t.padEnd(14)} ${status.padEnd(15)} ${dir ? path.relative(cwd, dir) : '(no path)'}`);
+      if (count === 0) suggestions.push({ level: 'warn', text: `Adapter "${t}" has no rendered files. Run \`npx wize-dev-kit sync\`.` });
+    }
+  }
+
+  // -- Section: TEA gates --
+  if (gates.total > 0) {
+    log('');
+    log('TEA gates');
+    log('─────────');
+    log(`Total gate.md files:  ${gates.total}`);
+    log(`PASS:      ${gates.PASS}`);
+    log(`CONCERNS:  ${gates.CONCERNS}`);
+    log(`FAIL:      ${gates.FAIL}`);
+    log(`WAIVED:    ${gates.WAIVED}`);
+    if (gates.FAIL > 0) suggestions.push({ level: 'error', text: `${gates.FAIL} story gate(s) at FAIL. Stories must not merge until resolved (advisory mode) or are blocking (enforcing mode).` });
+    if (gates.CONCERNS > 0) suggestions.push({ level: 'warn', text: `${gates.CONCERNS} story gate(s) at CONCERNS. Review findings before next sprint.` });
+  }
+
+  // -- Section: Knowledge --
+  if (knowledge.exists) {
+    log('');
+    log('Knowledge baseline (`document-project/`)');
+    log('────────────────────────────────────────');
+    for (const f of knowledge.files) {
+      const age = f.days == null ? 'no last_refreshed' : `${f.days}d ago`;
+      log(`  ${f.name.padEnd(28)} ${age}`);
+      if (f.days != null && f.days > 60) {
+        suggestions.push({ level: 'warn', text: `\`${f.name}\` last refreshed ${f.days}d ago. Run \`wize-refresh-knowledge\` after current sprint.` });
+      }
+    }
+    if (knowledge.pendingLines > 0) {
+      log(`  _pending.md:                ${knowledge.pendingLines} inline note(s) waiting consolidation`);
+      if (knowledge.pendingLines >= 5) {
+        suggestions.push({ level: 'info', text: `${knowledge.pendingLines} notes piled up in _pending.md. Time to run \`wize-refresh-knowledge\`.` });
+      }
+    }
+  }
+
+  // -- Section: Harness CLIs --
+  log('');
+  log('AI Harness CLIs on PATH');
+  log('───────────────────────');
+  if (harnesses.length === 0) {
+    log('  (none detected)');
+    suggestions.push({ level: 'info', text: 'No harness CLI detected. Brownfield baseline + auto-run features only work in your IDE; the headless flow is unavailable.' });
+  } else {
+    for (const h of harnesses) log(`  ${h.binary.padEnd(10)} ${h.path}`);
+  }
+
+  // -- Section: Git --
+  log('');
+  log('Git');
+  log('───');
+  if (!git.isRepo) {
+    log('  (not a git repo)');
+    suggestions.push({ level: 'warn', text: 'Not a git repository. Run `git init` before installing the kit so version history is recorded.' });
+  } else {
+    log(`  branch: ${git.branch}`);
+    log(`  head:   ${git.head}`);
+  }
+
+  // -- Section: Suggestions --
+  log('');
+  log('Suggestions');
+  log('───────────');
+  if (suggestions.length === 0) {
+    log('  ✓ Everything looks good.');
+  } else {
+    for (const s of suggestions) log(`  ${severityIcon(s.level)} ${s.text}`);
+  }
+  log('');
+
+  return { suggestions, phase, gates, knowledge, targets, profiles, installed, registryLatest };
+}
+
+module.exports = {
+  cmdDoctor,
+  // exported for tests:
+  detectPhase, gateStats, knowledgeStatus, gitInfo, adapterTargetPath, countAdapterFiles
+};

package/tools/installer/wize-cli.js

@@ -20,6 +20,7 @@ const { detectHarnessCli, runHeadlessBaseline, manualInstructions, defaultPrompt
 const { printUpdateHintIfAny } = require('./version-check.js');
 const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
 const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
+const { cmdDoctor } = require('./commands/doctor.js');
 
 const INTERACTIVE = process.stdout.isTTY && process.stdin.isTTY;
 
@@ -72,6 +73,7 @@ Commands:
   agent <create|list>     Manage agents (built-in or custom).
   workflow <create|list>  Manage workflows.
   validate                Run schema + lint + dry-run validators.
+  doctor                  Diagnose the kit + project state, suggest fixes.
   help                    Show this message.
 
 Documentation:
@@ -540,7 +542,7 @@ function cmdValidate() {
 // for `update` (already updating), `install` (already setting up), `uninstall`
 // (already leaving), `validate` (developer-tool), and `version` (the user is
 // already asking about versions).
-const HINT_COMMANDS = new Set(['list', 'sync', 'agent', 'workflow', 'help']);
+const HINT_COMMANDS = new Set(['list', 'sync', 'agent', 'workflow', 'help', 'doctor']);
 
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
@@ -561,6 +563,7 @@ async function main() {
     case 'agent':     return cmdAgent(rest);
     case 'workflow':  return cmdWorkflow(rest);
     case 'validate':  return cmdValidate();
+    case 'doctor':    return cmdDoctor({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
     case 'version':
     case '--version':
     case '-v':