wize-dev-kit 0.3.0 → 0.4.0

package/src/method-skills/4-implementation/wize-code-review/workflow.md

@@ -2,118 +2,63 @@
 code: wize-code-review
 name: Code Review
 phase: 4-implementation
-owner: wize-agent-dev   # Shuri (peer Shuri — done at PR open time)
+owner: wize-agent-dev   # Shuri (peer review)
 status: ready
 ---
 
 # Code Review
 
-**Goal.** Audit **code health** on the PR. Separate from Hawkeye's `tea-review` (which audits AC fulfillment). Both run on every story PR; they're complementary.
+**Goal.** Review code changes adversarially using parallel review layers and structured triage into actionable categories.
 
-Shuri reviews peer PRs. Tony reviews when architecture is at stake.
+This is **Shuri's peer code review** — separate from Hawkeye's `wize-tea-review` (which audits AC fulfillment). Both run on every story PR; they are complementary.
 
 ## When to run
 
-Every PR that ships code. Quick-dev PRs get a lighter review (skip code-architecture checks unless they touched architecture).
+Every PR that ships code. Quick-dev PRs get a lighter review (skip architecture checks unless they touched architecture).
 
 ## Inputs
 
-- The PR (diff + tests).
-- Story file (for context — what the PR is supposed to accomplish).
-- Linked design system (when components change).
+- The diff, PR, branch, or commit range to review.
+- The spec/story file for context (optional but recommended).
+- Existing code style and project context from `.wize/knowledge/document-project/`.
 
-## Output
+## Outputs
 
-- Inline comments on the PR.
-- Final review verdict: `approve` / `request-changes` / `comment`.
+- Inline-style findings presented in the conversation.
+- Optional patch application if the user chooses to fix findings now.
+- Updated story file with a `### Review Findings` section when a spec file is provided.
+- Updated sprint status when a story key is discovered.
 
-## What this checks
+## Workflow architecture
 
-### Naming + structure
-- Are types, functions, variables named for **what they are**, not **how they're used**?
-- Are files in the right folder per the architecture?
-- Are exports minimal? Module boundaries respected?
-- Are there new abstractions justified by the story or premature?
+This skill uses **step-file architecture**:
 
-### Tests
-- Do tests cover the changed behavior (not just coverage %)?
-- Are they fast and isolated?
-- Are mocks at the boundary, not inside the unit?
-- Any `test.skip` / `.only` left in?
+- Each step is self-contained and followed exactly.
+- Sequential enforcement: complete steps in order, no skipping.
+- State tracked in frontmatter variables set at runtime.
+- Append-only building of findings.
 
-### Security (obvious-misses)
-- Input validation at boundaries.
-- Tokens / secrets / PII never logged.
-- SQL parameterized, not concatenated.
-- New deps audited; no known CVEs introduced.
-- Auth context checked on every server entry point.
+## Critical rules
 
-### Performance (obvious-misses)
-- No N+1 queries.
-- No `await` in tight loops without batching.
-- No new sync I/O on hot paths.
-- Bundle delta acceptable (size of new front-end imports).
+- **Read completely** each step file before acting.
+- **Never** load multiple step files simultaneously.
+- **Always** halt at checkpoints and wait for human input.
+- Use CWD-relative `path:line` for every code reference.
 
-### Architectural drift
-- Story didn't quietly introduce a new layer / new pattern.
-- If it did, an ADR was opened or a comment justifies it.
-- Components reused from design system; new components added to system if reusable.
+## On activation
 
-### Style + convention
-- Follows lint / format / type rules.
-- Comments explain *why*, not *what*.
-- Dead code removed.
-- TODOs have an owner + a ticket.
+1. Load `.wize/config/project.toml` and `.wize/config/user.toml`.
+2. Resolve `user_name`, `communication_language`, `document_output_language`, `implementation_artifacts`, `planning_artifacts`.
+3. Greet the user in `communication_language`.
+4. Read fully and follow `./steps/step-01-gather-context.md`.
 
-## What this does NOT check
+## Steps
 
-- Whether ACs are met — that's Hawkeye's `tea-review`.
-- Whether the design is right — that's reviewed in pull-request walk-through, ADR review, or party-mode.
-
-Don't conflate. Two reviewers, two scopes.
-
-## Comment style
-
-Use these prefixes:
-
-| Prefix | Meaning |
-|---|---|
-| `nit:` | Cosmetic; non-blocking |
-| `q:` | Question; might be a misunderstanding |
-| `praise:` | Real call-outs; teams need them |
-| `suggestion:` | Idea, the author decides |
-| `blocking:` | Must change before merge |
-| `out-of-scope:` | Real issue, separate story |
-
-Never `LGTM` without scanning. Never `LGTM` with `blocking:` open.
-
-## Verdict
-
-- **approve** — all blockings resolved.
-- **request-changes** — at least one `blocking:`.
-- **comment** — reviewed, no opinion (rare; used for early-draft PRs).
-
-## PR-open checklist (Shuri's self-review)
-
-Before opening, Shuri runs through:
-
-- [ ] CI green locally.
-- [ ] Lint + format clean.
-- [ ] Type-check clean.
-- [ ] No `console.log` / `dbg!` / debug printf.
-- [ ] No `test.skip` / `.only`.
-- [ ] Reading the diff right now, can I explain every line?
-- [ ] Self-walk: open the changed screen / call the changed endpoint.
-- [ ] Story status flipped to `ready-for-review`.
-
-## Anti-patterns Shuri rejects in herself
-
-- Approving without reading.
-- Approving on the basis of green CI alone.
-- "Big PR; will trust" — refuse and ask for slicing.
-- Inline suggestions for full rewrites — open a follow-up instead.
-- Demanding stylistic preferences not in the lint config.
+1. `step-01-gather-context.md` — identify the diff source, construct `{diff_output}`, set `{review_mode}` and `{spec_file}`.
+2. `step-02-review.md` — launch parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor).
+3. `step-03-triage.md` — normalize, deduplicate, and classify findings into `decision_needed`, `patch`, `defer`, `dismiss`.
+4. `step-04-present.md` — present findings, resolve decisions, apply patches, update story status.
 
 ## Hand-off
 
-> Reviewed PR #418 (E02-S02). 2 nits, 1 blocking on auth-context check missing in one new route. Shuri to fix; re-review needed; then Hawkeye runs `tea-review`.
+> Code review complete for `{story_key or change}`. `{decision_needed}` decision(s), `{patch}` patch(es), `{defer}` deferred, `{dismissed}` dismissed as noise. Next: re-run review or continue to `wize-tea-review` (Hawkeye).

package/src/method-skills/module.yaml

@@ -97,9 +97,28 @@ agents:
     team: software-development
     description: "Wakanda forever — agora compila. TDD red-green-refactor, segurança, performance, código limpo. Estilo: gênio inovadora, rápida, protetora do ecossistema, sem fluff."
 
+# Notable skills shipped by method (discovery is automatic via workflow.md/skill.md walkers).
+skills:
+  - code: wize-market-research
+    name: "Market Research"
+    description: "Competition and customer research for the product brief and PRD."
+  - code: wize-domain-research
+    name: "Domain Research"
+    description: "Industry, regulatory, and technical-trend research."
+  - code: wize-technical-research
+    name: "Technical Research"
+    description: "Technology, architecture, and implementation-pattern research."
+  - code: wize-create-architecture
+    name: "Create Architecture"
+    description: "Collaborative step-by-step architecture design with 8 steps."
+  - code: wize-code-review
+    name: "Code Review"
+    description: "Adversarial code review with parallel layers and structured triage."
+
 # Phase directories (declarative discovery for the installer):
 phases:
   - "1-analysis"
   - "2-plan-workflows"
   - "3-solutioning"
   - "4-implementation"
+

package/src/tea-skills/wize-tea-risk/workflow.md

@@ -19,6 +19,7 @@ Hawkeye drives. Tony co-signs. Runs **once**, right after architecture is signed
 - `.wize/solutioning/epics/`
 - `.wize/planning/nfr-principles.md`
 - `.wize/knowledge/document-project/risk-spots.md` (brownfield)
+- `.wize/knowledge/document-project/index.md` (documentation gap markers)
 
 ## Output
 
@@ -115,6 +116,16 @@ The narrative explains the matrix; the YAML is the structured truth. Hawkeye wri
 - Other stories follow the default 70/20/10 split.
 ```
 
+## Documentation gap risk category
+
+In brownfield repos, missing or stale documentation is an operational risk: new contributors make unsafe assumptions, AI agents hallucinate context, and reviews miss implicit contracts. Hawkeye treats it as a first-class risk area.
+
+| Symptom | Severity | Rationale | Mitigation |
+|---|---|---|---|
+| `index.md` contains `_(To be generated)_` markers | medium | Conditional docs were skipped; the baseline is incomplete. | Schedule `wize-document-project initial_scan` for the next cooldown. |
+| Baseline files older than 60 days | medium | Docs may no longer reflect the codebase. | Run `wize-refresh-knowledge` at sprint end. |
+| No baseline exists in a brownfield repo | high | Team is flying blind; architecture and conventions are tribal knowledge. | Run `wize-dev-kit document-project quick` immediately. |
+
 ## Anti-patterns Hawkeye rejects
 
 - **Findings without mitigation.** A finding without a contract is a wish.

package/tools/installer/commands/doctor.js

@@ -130,7 +130,21 @@ function knowledgeStatus(projectRoot) {
   const pendingLines = fileExists(pendingFile)
     ? readSafe(pendingFile).split('\n').filter(l => l.trim() && !l.startsWith('#')).length
     : 0;
-  return { exists: true, files: refreshed, pendingLines };
+
+  const indexPath = path.join(root, 'index.md');
+  const indexContent = fileExists(indexPath) ? readSafe(indexPath) : '';
+  const toBeGeneratedMarkers = (indexContent.match(/_\(To be generated\)_/g) || []).length;
+
+  const statePath = path.join(root, 'project-scan-report.json');
+  const stateExists = fileExists(statePath);
+  const stateContent = stateExists ? readSafe(statePath) : '';
+  let stateAgeDays = null;
+  try {
+    const state = JSON.parse(stateContent);
+    stateAgeDays = daysAgo(state.timestamps && state.timestamps.last_updated);
+  } catch (_) {}
+
+  return { exists: true, files: refreshed, pendingLines, toBeGeneratedMarkers, stateExists, stateAgeDays };
 }
 
 function gitInfo(projectRoot) {
@@ -247,6 +261,18 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
         suggestions.push({ level: 'info', text: `${knowledge.pendingLines} notes piled up in _pending.md. Time to run \`wize-refresh-knowledge\`.` });
       }
     }
+    const markerText = knowledge.toBeGeneratedMarkers > 0 ? `${knowledge.toBeGeneratedMarkers} marker(s)` : 'none';
+    log(`  To be generated markers:    ${markerText}`);
+    if (knowledge.toBeGeneratedMarkers >= 5) {
+      suggestions.push({ level: 'warn', text: `${knowledge.toBeGeneratedMarkers} docs marked "To be generated" in index.md. Run \`wize-dev-kit document-project initial_scan deep\` to fill them.` });
+    }
+    const stateText = knowledge.stateExists
+      ? (knowledge.stateAgeDays == null ? 'project-scan-report.json exists (age unknown)' : `project-scan-report.json ${knowledge.stateAgeDays}d old`)
+      : 'no project-scan-report.json';
+    log(`  Scan state:                 ${stateText}`);
+    if (!knowledge.stateExists) {
+      suggestions.push({ level: 'info', text: 'No scan state file found. Run `wize-dev-kit document-project quick` to create a baseline + state.' });
+    }
   }
 
   // -- Section: Harness CLIs --

package/tools/installer/commands/document-project.js

@@ -0,0 +1,93 @@
+// `wize-dev-kit document-project` — CLI command entry point.
+//
+// Parses mode + flags and delegates to the appropriate scan implementation.
+// Non-quick modes are stubs here; later stories fill them in.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { runQuick } = require('../document-project/modes/quick.js');
+const { runInitialScan } = require('../document-project/modes/initial-scan.js');
+const { runFullRescan } = require('../document-project/modes/full-rescan.js');
+const { runDeepDive } = require('../document-project/modes/deep-dive.js');
+const { loadState, archiveOldState } = require('../document-project/state.js');
+
+const VALID_MODES = new Set(['quick', 'initial_scan', 'full_rescan', 'deep_dive']);
+const VALID_SCAN_LEVELS = new Set(['quick', 'deep', 'exhaustive']);
+
+function parseMode(args) {
+  let mode = 'quick';
+  let resume = false;
+  let scanLevel = 'quick';
+  let target = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--resume') {
+      resume = true;
+      continue;
+    }
+    if (arg === '--target') {
+      target = args[i + 1];
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      return { mode: null, error: `unknown option: ${arg}` };
+    }
+    if (VALID_SCAN_LEVELS.has(arg)) {
+      scanLevel = arg;
+      continue;
+    }
+    if (mode === 'quick' && VALID_MODES.has(arg)) {
+      mode = arg;
+    } else if (mode === 'quick') {
+      return { mode: null, error: `unknown mode: ${arg}. Valid modes: ${[...VALID_MODES].join(', ')}` };
+    } else {
+      return { mode: null, error: `unexpected extra argument: ${arg}` };
+    }
+  }
+
+  if (!VALID_MODES.has(mode)) {
+    return { mode: null, error: `unknown mode: ${mode}. Valid modes: ${[...VALID_MODES].join(', ')}` };
+  }
+
+  return { mode, resume, scanLevel, target };
+}
+
+function cmdDocumentProject({ kitRoot, projectRoot, args = [], opts = {} }) {
+  const log = opts.log || console.log;
+  const parsed = parseMode(args);
+
+  if (parsed.mode === null) {
+    log(parsed.error);
+    return { ok: false, error: parsed.error, exitCode: 1 };
+  }
+
+  if (parsed.mode === 'quick') {
+    const r = runQuick(projectRoot, { log });
+    return { ok: true, mode: 'quick', ...r };
+  }
+
+  if (parsed.mode === 'initial_scan') {
+    const r = runInitialScan(projectRoot, { scanLevel: parsed.scanLevel, log });
+    return { ok: true, mode: 'initial_scan', ...r };
+  }
+
+  if (parsed.mode === 'full_rescan') {
+    const r = runFullRescan(projectRoot, { scanLevel: parsed.scanLevel, log });
+    return { ok: true, mode: 'full_rescan', ...r };
+  }
+
+  if (parsed.mode === 'deep_dive') {
+    const r = runDeepDive(projectRoot, { target: parsed.target, log });
+    return r;
+  }
+
+  log(`document-project ${parsed.mode} not implemented`);
+  return { ok: false, error: 'not implemented', exitCode: 1 };
+}
+
+module.exports = { cmdDocumentProject, parseMode };
+

package/tools/installer/document-project/batch-scanner.js

@@ -0,0 +1,93 @@
+// Batch scanner for `wize-dev-kit document-project`.
+//
+// Walks a repo in subfolder-sized batches, skipping noise directories.
+// Returns summaries without loading entire trees into memory.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_IGNORE = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.cache',
+  '.tmp',
+  '.wize',
+  '.claude',
+  '.cursor',
+  '.kimi',
+  '.opencode',
+  '.windsurf',
+  '.continue',
+  '.codex',
+  '.antigravity'
+]);
+
+const MAX_FILE_LOC = 5000;
+
+function shouldIgnore(name, customIgnore = []) {
+  if (DEFAULT_IGNORE.has(name)) return true;
+  for (const pattern of customIgnore) {
+    if (name === pattern || (pattern.startsWith('*') && name.endsWith(pattern.slice(1)))) return true;
+  }
+  return false;
+}
+
+function listSubfolders(rootDir, options = {}) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(rootDir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (shouldIgnore(e.name, options.ignore)) continue;
+    out.push(path.join(rootDir, e.name));
+  }
+  return out;
+}
+
+function scanFolder(folderPath, options = {}) {
+  const files = [];
+  let totalLoc = 0;
+  const stack = [folderPath];
+  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()) {
+        if (!shouldIgnore(e.name, options.ignore)) stack.push(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (/\.(min\.js|map)$/.test(e.name)) continue;
+      const stat = fs.statSync(full);
+      const loc = stat.size; // proxy; exact line count is optional
+      const info = {
+        path: full,
+        relative: path.relative(folderPath, full),
+        size: stat.size,
+        loc: loc > MAX_FILE_LOC ? MAX_FILE_LOC : loc,
+        skipped: loc > MAX_FILE_LOC
+      };
+      files.push(info);
+      totalLoc += info.loc;
+    }
+  }
+  return { folder: folderPath, files, totalLoc, fileCount: files.length };
+}
+
+function batchScanner(rootDir, options = {}) {
+  const folders = options.folders || listSubfolders(rootDir, options);
+  const results = [];
+  for (const folder of folders) {
+    results.push(scanFolder(folder, options));
+  }
+  return results;
+}
+
+module.exports = { batchScanner, listSubfolders, scanFolder, shouldIgnore, MAX_FILE_LOC };

package/tools/installer/document-project/classify.js

@@ -0,0 +1,170 @@
+// Project-type classifier for `wize-dev-kit document-project`.
+//
+// Detects the project type(s) of a repo from file patterns, then decides
+// whether the repo is a monolith, multi-part, or monorepo.
+// No source files are read — this is pattern-only detection.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MULTI_PART_FOLDERS = ['client', 'server', 'api', 'web', 'app', 'frontend', 'backend', 'mobile', 'desktop'];
+
+function toBool(v) {
+  return String(v).toLowerCase() === 'true';
+}
+
+function splitPatterns(str) {
+  if (!str || str === 'N/A') return [];
+  return str.split(';').map(s => s.trim()).filter(Boolean);
+}
+
+function loadRequirements(csvPath) {
+  const content = fs.readFileSync(csvPath, 'utf-8');
+  const lines = content.split(/\r?\n/).filter(l => l.trim());
+  const header = lines[0].split(',').map(h => h.trim());
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(',').map(v => v.trim());
+    const row = {};
+    for (let j = 0; j < header.length; j++) {
+      const key = header[j];
+      const raw = values[j];
+      if (key.startsWith('requires_')) {
+        row[key] = toBool(raw);
+      } else {
+        row[key] = raw || '';
+      }
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+function globMatch(rootDir, pattern) {
+  // Very small pattern matcher: supports * wildcard and trailing / for dirs.
+  const isDirPattern = pattern.endsWith('/');
+  const base = isDirPattern ? pattern.slice(0, -1) : pattern;
+  const parts = base.split('/');
+  return walkMatch(rootDir, parts, 0, isDirPattern);
+}
+
+function walkMatch(dir, parts, depth, isDirPattern) {
+  if (depth >= parts.length) return true;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+  const part = parts[depth];
+  const isLast = depth === parts.length - 1;
+  const regex = globToRegex(part);
+  for (const e of entries) {
+    if (!regex.test(e.name)) continue;
+    if (isLast) {
+      if (isDirPattern && e.isDirectory()) return true;
+      if (!isDirPattern && e.isFile()) return true;
+      if (!isDirPattern && e.isDirectory()) {
+        // pattern like vite.config.* can match a directory named vite.config.ts? no.
+        // But pattern may be a prefix; treat directory match as false for files.
+        return false;
+      }
+    } else if (e.isDirectory()) {
+      if (walkMatch(path.join(dir, e.name), parts, depth + 1, isDirPattern)) return true;
+    }
+  }
+  return false;
+}
+
+function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`);
+}
+
+function scorePart(rootDir, row, { prefer = [] } = {}) {
+  let score = 0;
+  const keyPatterns = splitPatterns(row.key_file_patterns);
+  const dirPatterns = splitPatterns(row.critical_directories);
+  for (const p of keyPatterns) {
+    if (globMatch(rootDir, p)) score += 2;
+  }
+  for (const p of dirPatterns) {
+    if (globMatch(rootDir, p)) score += 1;
+  }
+  if (prefer.includes(row.project_type_id)) score += 0.5;
+  return score;
+}
+
+function detectParts(rootDir) {
+  const parts = [];
+  const candidates = [];
+  let entries;
+  try { entries = fs.readdirSync(rootDir, { withFileTypes: true }); } catch { return parts; }
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!MULTI_PART_FOLDERS.includes(e.name.toLowerCase())) continue;
+    candidates.push(e.name);
+  }
+
+  if (candidates.length < 2) return parts;
+
+  const rows = loadRequirements(requirementsPath());
+  for (const partId of candidates) {
+    const partRoot = path.join(rootDir, partId);
+    const prefer = partId.toLowerCase() === 'server' || partId.toLowerCase() === 'backend' ? ['backend'] : [];
+    const scored = rows.map(r => ({ ...r, score: scorePart(partRoot, r, { prefer }) }));
+    scored.sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    if (best && best.score > 0) {
+      parts.push({ part_id: partId, project_type_id: best.project_type_id, root_path: partRoot });
+    }
+  }
+  return parts;
+}
+
+function isMultiPart(rootDir) {
+  return detectParts(rootDir).length >= 2;
+}
+
+function classifyProject(rootDir, options = {}) {
+  const csvPath = options.csvPath || requirementsPath();
+  const rows = loadRequirements(csvPath);
+  const parts = detectParts(rootDir);
+
+  if (parts.length >= 2) {
+    return { projectTypes: [...new Set(parts.map(p => p.project_type_id))], parts };
+  }
+
+  const scored = rows.map(r => ({ ...r, score: scorePart(rootDir, r, { prefer: options.prefer || [] }) }));
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  const tied = scored.filter(s => s.score === best.score).map(s => s.project_type_id);
+
+  if (!best || best.score === 0) {
+    return { projectTypes: [], parts: [] };
+  }
+
+  // Cli + library often appear together; prefer both when tied at the top.
+  const projectTypes = tied.includes('cli') && tied.includes('library')
+    ? ['cli', 'library']
+    : [best.project_type_id];
+
+  return {
+    projectTypes,
+    parts: [{ part_id: 'root', project_type_id: best.project_type_id, root_path: rootDir }]
+  };
+}
+
+function requirementsPath() {
+  // When running from the installed package, the CSV is next to this file under
+  // node_modules/wize-dev-kit/... When running from the source repo, resolve from
+  // the repo root via the known relative path.
+  const installed = path.resolve(__dirname, '..', '..', '..', 'src', 'method-skills', '1-analysis', 'wize-document-project', 'documentation-requirements.csv');
+  if (fs.existsSync(installed)) return installed;
+  // Fallback for source repo layout.
+  return path.resolve(__dirname, '..', '..', '..', '..', 'src', 'method-skills', '1-analysis', 'wize-document-project', 'documentation-requirements.csv');
+}
+
+module.exports = { classifyProject, loadRequirements, isMultiPart, scorePart, requirementsPath, globMatch };