wize-dev-kit 0.3.0 → 0.3.1

package/src/method-skills/1-analysis/wize-document-project/templates/project-scan-report-schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qwize.io/wize-dev-kit/schemas/project-scan-report.schema.json",
+  "title": "Project Scan Report",
+  "description": "State tracking file for wize-document-project resumability",
+  "type": "object",
+  "required": ["workflow_version", "timestamps", "mode", "scan_level", "completed_steps", "current_step"],
+  "properties": {
+    "workflow_version": {
+      "type": "string",
+      "description": "Version of document-project workflow"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["started", "last_updated"],
+      "properties": {
+        "started": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow started"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last state update"
+        },
+        "completed": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow completed"
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["initial_scan", "full_rescan", "deep_dive", "quick"],
+      "description": "Workflow execution mode"
+    },
+    "scan_level": {
+      "type": "string",
+      "enum": ["quick", "deep", "exhaustive"],
+      "description": "Scan depth level"
+    },
+    "project_root": {
+      "type": "string",
+      "description": "Absolute path to project root directory"
+    },
+    "project_knowledge": {
+      "type": "string",
+      "description": "Absolute path to project knowledge folder"
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "status"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "description": "Step identifier"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["completed", "partial", "failed"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "outputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files written during this step"
+          },
+          "summary": {
+            "type": "string",
+            "description": "1-2 sentence summary of step outcome"
+          }
+        }
+      }
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step identifier for resumption"
+    },
+    "findings": {
+      "type": "object",
+      "description": "High-level summaries only",
+      "properties": {
+        "project_classification": {
+          "type": "object",
+          "properties": {
+            "repository_type": { "type": "string" },
+            "parts_count": { "type": "integer" },
+            "primary_language": { "type": "string" },
+            "architecture_type": { "type": "string" }
+          }
+        },
+        "technology_stack": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "part_id": { "type": "string" },
+              "tech_summary": { "type": "string" }
+            }
+          }
+        },
+        "batches_completed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "files_scanned": { "type": "integer" },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "outputs_generated": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of all output files generated"
+    },
+    "resume_instructions": {
+      "type": "string",
+      "description": "Instructions for resuming from current_step"
+    },
+    "validation_status": {
+      "type": "object",
+      "properties": {
+        "last_validated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validation_errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deep_dive_targets": {
+      "type": "array",
+      "description": "Track deep-dive areas analyzed",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_name": { "type": "string" },
+          "target_path": { "type": "string" },
+          "files_analyzed": { "type": "integer" },
+          "output_file": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

package/src/method-skills/1-analysis/wize-document-project/templates/source-tree-template.md

@@ -0,0 +1,142 @@
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: {{date}}
+last_refreshed: {{date}}
+---
+
+# {{project_name}} - Source Tree Analysis
+
+**Date:** {{date}}
+
+## Overview
+
+{{source_tree_overview}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project is organized into {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+- **{{part_name}}** (`{{root_path}}`): {{purpose}}
+{{/each}}
+{{/if}}
+
+## Complete Directory Structure
+
+```
+{{complete_source_tree}}
+```
+
+## Critical Directories
+
+{{#each critical_folders}}
+
+### `{{folder_path}}`
+
+{{description}}
+
+**Purpose:** {{purpose}}
+**Contains:** {{contents_summary}}
+{{#if entry_points}}**Entry Points:** {{entry_points}}{{/if}}
+{{#if integration_note}}**Integration:** {{integration_note}}{{/if}}
+
+{{/each}}
+
+{{#if is_multi_part}}
+
+## Part-Specific Trees
+
+{{#each project_parts}}
+
+### {{part_name}} Structure
+
+```
+{{source_tree}}
+```
+
+**Key Directories:**
+{{#each critical_directories}}
+
+- **`{{path}}`**: {{description}}
+{{/each}}
+
+{{/each}}
+
+## Integration Points
+
+{{#each integration_points}}
+
+### {{from_part}} → {{to_part}}
+
+- **Location:** `{{integration_path}}`
+- **Type:** {{integration_type}}
+- **Details:** {{details}}
+{{/each}}
+
+{{/if}}
+
+## Entry Points
+
+{{#if is_single_part}}
+
+- **Main Entry:** `{{main_entry_point}}`
+{{#if additional_entry_points}}
+- **Additional:**
+{{#each additional_entry_points}}
+  - `{{path}}`: {{description}}
+{{/each}}
+{{/if}}
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}}
+
+- **Entry Point:** `{{entry_point}}`
+- **Bootstrap:** {{bootstrap_description}}
+{{/each}}
+{{/if}}
+
+## File Organization Patterns
+
+{{file_organization_patterns}}
+
+## Key File Types
+
+{{#each file_type_patterns}}
+
+### {{file_type}}
+
+- **Pattern:** `{{pattern}}`
+- **Purpose:** {{purpose}}
+- **Examples:** {{examples}}
+{{/each}}
+
+## Asset Locations
+
+{{#if has_assets}}
+{{#each asset_locations}}
+
+- **{{asset_type}}**: `{{location}}` ({{file_count}} files, {{total_size}})
+{{/each}}
+{{else}}
+No significant assets detected.
+{{/if}}
+
+## Configuration Files
+
+{{#each config_files}}
+
+- **`{{path}}`**: {{description}}
+{{/each}}
+
+## Notes for Development
+
+{{development_notes}}
+
+---
+
+_Generated using Wize Dev Kit `document-project` workflow_

package/src/method-skills/1-analysis/wize-document-project/workflow.md

@@ -28,6 +28,27 @@ Skip:
 - `git log --since="1 year ago" --oneline | wc -l` to scope.
 - Any prior README / ARCHITECTURE / docs that exist.
 
+## CLI usage
+
+```bash
+wize-dev-kit document-project                # quick baseline (default)
+wize-dev-kit document-project quick          # same as default
+wize-dev-kit document-project initial_scan   # pattern-only initial scan
+wize-dev-kit document-project initial_scan deep       # reads critical directories
+wize-dev-kit document-project initial_scan exhaustive  # reads all source files in batches
+wize-dev-kit document-project full_rescan    # archives old state, re-runs initial_scan
+wize-dev-kit document-project deep_dive --target src/tools/installer
+```
+
+## Modes
+
+| Mode | What it does | Scan levels |
+|---|---|---|
+| `quick` | Writes the 6 baseline files. Does not read source files. | `quick` only |
+| `initial_scan` | Classifies project type, writes index + overview + source tree + conditional docs. | `quick`, `deep`, `exhaustive` |
+| `full_rescan` | Archives `project-scan-report.json` and re-runs `initial_scan`. | `quick`, `deep`, `exhaustive` |
+| `deep_dive` | Exhaustive analysis of a specific folder/file/feature. | `exhaustive` |
+
 ## Outputs
 
 - `.wize/knowledge/document-project/overview.md` — what the project is, who uses it, how big it is.
@@ -36,6 +57,8 @@ Skip:
 - `.wize/knowledge/document-project/dependencies.md` — runtime deps + dev deps + their roles.
 - `.wize/knowledge/document-project/risk-spots.md` — areas of concentrated complexity, undocumented behavior, or known fragility.
 - `.wize/knowledge/document-project/open-questions.md` — things the code doesn't answer; route to humans.
+- `.wize/knowledge/document-project/index.md` — master navigation with `_(To be generated)_` markers for missing conditional docs.
+- `.wize/knowledge/document-project/project-scan-report.json` — resume state.
 
 ## Steps
 

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 };