@unlaxer/dve-toolkit 4.1.0

package/graph/schema.ts

@@ -0,0 +1,169 @@
+// DVE Data Model v2 — Node/Edge/Query types
+
+// ─── Nodes ───
+
+export interface Session {
+  id: string;
+  date: string;
+  theme: string;
+  flow: "quick" | "design-review" | "brainstorm" | string;
+  structure: "roundtable" | "tribunal" | "wargame" | "pitch" | "consult" | "investigation" | string;
+  characters: string[];
+  file_path: string;
+  content?: string;  // full markdown content (included in graph.json for static rendering)
+}
+
+export interface Gap {
+  id: string;           // "{session_id}#G-{n}"
+  session_id: string;
+  summary: string;
+  category: string;
+  severity: "Critical" | "High" | "Medium" | "Low" | "Unknown";
+  status: "Active" | "Void" | "Archived";
+  line_ref: number;
+  discovered_by: string[];
+}
+
+export interface Decision {
+  id: string;           // "DD-001"
+  title: string;
+  date: string;
+  rationale: string;
+  status: "active" | "overturned";
+  supersedes: string[];
+  superseded_by: string[];
+  gap_refs: string[];
+  session_refs: string[];
+  file_path: string;
+  content?: string;     // full markdown content
+}
+
+export interface Spec {
+  id: string;
+  title: string;
+  type: "UC" | "TECH" | "DD" | "DQ" | "ACT";
+  status: "draft" | "reviewed" | "migrated";
+  decision_refs: string[];
+  migrated_to?: string;
+  file_path: string;
+  content?: string;
+}
+
+export type AnnotationAction = "comment" | "fork" | "overturn" | "constrain" | "drift";
+
+export interface Annotation {
+  id: string;           // "A-001"
+  target: { type: "session" | "gap" | "decision"; id: string };
+  target_line?: number;
+  author: string;
+  date: string;
+  body: string;
+  action: AnnotationAction;
+}
+
+// ─── Edges ───
+
+export type EdgeType = "contains" | "discovers" | "resolves" | "supersedes" | "annotates" | "produces" | "implements";
+export type Confidence = "explicit" | "inferred";
+
+export interface Edge {
+  source: string;
+  target: string;
+  type: EdgeType;
+  confidence: Confidence;
+  evidence?: string;
+}
+
+// ─── Graph Node wrapper ───
+
+export type NodeType = "session" | "dialogue" | "gap" | "decision" | "spec" | "annotation";
+
+export interface GraphNode {
+  type: NodeType;
+  id: string;
+  data: Session | Gap | Decision | Spec | Annotation;
+  confidence: number;   // 0.0 - 1.0
+  warnings: string[];
+}
+
+// ─── Graph output ───
+
+export interface DVEGraph {
+  version: string;
+  generated_at: string;
+  stats: {
+    sessions: number;
+    gaps: number;
+    decisions: number;
+    annotations: number;
+    specs?: number;
+  };
+  nodes: GraphNode[];
+  edges: Edge[];
+  warnings: { file: string; message: string }[];
+  glossary?: GlossaryEntry[];
+}
+
+// ─── Parse result ───
+
+export interface ParseResult<T> {
+  node: Partial<T>;
+  confidence: number;
+  warnings: string[];
+  source: { file: string; line?: number };
+}
+
+// ─── Multi-project ───
+
+export interface MultiProjectGraph {
+  version: string;
+  generated_at: string;
+  projects: {
+    name: string;
+    path: string;
+    graph: DVEGraph;
+  }[];
+}
+
+// ─── Glossary ───
+
+export interface GlossaryEntry {
+  term: string;
+  definition: string;
+  source: string;
+  aliases?: string[];
+}
+
+// ─── Changelog ───
+
+export interface Changelog {
+  since: string;
+  new_nodes: string[];
+  removed_nodes: string[];
+  changed_statuses: { id: string; from: string; to: string }[];
+}
+
+// ─── ContextBundle ───
+
+export interface ContextBundle {
+  type: "dve-context-bundle";
+  version: "1.0.0";
+  origin: {
+    node_type: NodeType;
+    node_id: string;
+    file: string;
+  };
+  summary: {
+    theme: string;
+    date_range: string;
+    prior_decisions: string[];
+    prior_gaps: { id: string; summary: string; status: string }[];
+    characters_used: string[];
+    session_count: number;
+    key_dialogue_excerpt?: string;
+  };
+  new_constraints: string[];
+  annotations: { date: string; action: string; body: string }[];
+  suggested_action: "revisit" | "deep_dive" | "new_angle" | "override";
+  prompt_template: string;
+}

package/install.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# DVE toolkit installer
+# Sets up dve/ directories, builds kit, installs app dependencies
+
+REAL_PATH="$(readlink -f "$0" 2>/dev/null || realpath "$0" 2>/dev/null || echo "$0")"
+SCRIPT_DIR="$(cd "$(dirname "${REAL_PATH}")" && pwd)"
+TARGET_DIR="${1:-.}"
+
+# Resolve source
+SRC="${SCRIPT_DIR}"
+if [ ! -f "${SRC}/version.txt" ]; then
+  echo "Error: Cannot find DVE toolkit files."
+  exit 1
+fi
+
+SRC_VERSION="$(cat "${SRC}/version.txt" 2>/dev/null || echo "unknown")"
+
+echo "DVE toolkit — install v${SRC_VERSION}"
+echo ""
+
+# Create directories
+mkdir -p "${TARGET_DIR}/dve/annotations"
+mkdir -p "${TARGET_DIR}/dve/contexts"
+mkdir -p "${TARGET_DIR}/dve/dist"
+
+# Initialize .dre/ state machine if not exists
+if [ ! -f "${TARGET_DIR}/.dre/state-machine.yaml" ]; then
+  if [ -f "${SCRIPT_DIR}/../../../dre/kit/engine/engine.js" ]; then
+    echo "  Initializing DRE workflow engine..."
+    node "${SCRIPT_DIR}/../../../dre/kit/engine/engine.js" init 2>/dev/null || true
+  fi
+fi
+
+# Compile kit if dist doesn't exist
+if [ ! -d "${SRC}/dist" ]; then
+  echo "  Compiling DVE kit..."
+  (cd "${SRC}" && npx tsc 2>/dev/null || true)
+fi
+
+# Install app dependencies if needed
+APP_DIR="${SCRIPT_DIR}/../app"
+if [ -d "${APP_DIR}" ] && [ ! -d "${APP_DIR}/node_modules" ]; then
+  echo "  Installing DVE app dependencies..."
+  (cd "${APP_DIR}" && npm install 2>/dev/null || true)
+fi
+
+# Install skills
+SKILLS_DIR="${TARGET_DIR}/.claude/skills"
+mkdir -p "${SKILLS_DIR}"
+
+if [ -d "${SRC}/skills" ]; then
+  for SKILL in "${SRC}/skills/"*.md; do
+    [ -f "${SKILL}" ] || continue
+    FNAME="$(basename "${SKILL}")"
+    if [ ! -f "${SKILLS_DIR}/${FNAME}" ]; then
+      cp "${SKILL}" "${SKILLS_DIR}/${FNAME}"
+      echo "  [new] .claude/skills/${FNAME}"
+    fi
+  done
+fi
+
+# Build graph.json
+if [ -f "${SRC}/dist/cli/dve-tool.js" ]; then
+  echo ""
+  echo "  Building graph.json..."
+  (cd "${TARGET_DIR}" && node "${SRC}/dist/cli/dve-tool.js" build 2>/dev/null || true)
+fi
+
+echo ""
+echo "DVE toolkit v${SRC_VERSION} installed."
+echo ""
+echo "  Usage:"
+echo "    node dve/kit/dist/cli/dve-tool.js build     Build graph"
+echo "    node dve/kit/dist/cli/dve-tool.js serve      Start Web UI"
+echo "    node dve/kit/dist/cli/dve-tool.js status     Show project state"
+echo ""

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@unlaxer/dve-toolkit",
+  "version": "4.1.0",
+  "description": "DVE (Decision Visualization Engine) — DGE の決定プロセスを可視化するツールキット",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opaopa6969/DxE-suite"
+  },
+  "bin": {
+    "dve": "./cli/dve-tool.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/"
+  },
+  "dependencies": {
+    "unified": "^11.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "yaml": "^2.4.0",
+    "chokidar": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/parser/annotation-parser.ts

@@ -0,0 +1,77 @@
+// Annotation parser — extract annotations from dve/annotations/*.md
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import type { Annotation, AnnotationAction, ParseResult } from "../graph/schema.js";
+
+const VALID_ACTIONS: AnnotationAction[] = ["comment", "fork", "overturn", "constrain", "drift"];
+
+export function parseAnnotation(filePath: string): ParseResult<Annotation> {
+  const content = readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const warnings: string[] = [];
+  const stem = path.basename(filePath, ".md");
+
+  // Parse YAML frontmatter
+  const fm: Record<string, string> = {};
+  let inFrontmatter = false;
+  let bodyStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "---") {
+      if (!inFrontmatter) {
+        inFrontmatter = true;
+        continue;
+      } else {
+        bodyStart = i + 1;
+        break;
+      }
+    }
+    if (inFrontmatter) {
+      const m = line.match(/^(\w[\w_]*)\s*:\s*(.+)/);
+      if (m) fm[m[1]] = m[2].trim();
+    }
+  }
+
+  const target = fm["target"] ?? "";
+  const action = fm["action"] ?? "comment";
+  const date = fm["date"] ?? "";
+  const author = fm["author"] ?? "";
+  const targetLine = fm["target_line"] ? parseInt(fm["target_line"], 10) : undefined;
+
+  // Body is everything after frontmatter
+  const body = lines.slice(bodyStart).join("\n").trim();
+
+  // Determine target type
+  let targetType: "session" | "gap" | "decision" = "decision";
+  if (target.includes("#G-")) targetType = "gap";
+  else if (target.startsWith("DD-")) targetType = "decision";
+  else targetType = "session";
+
+  // Validate action
+  const validAction = VALID_ACTIONS.includes(action as AnnotationAction)
+    ? (action as AnnotationAction)
+    : "comment";
+  if (action !== validAction) {
+    warnings.push(`Unknown action "${action}", defaulting to "comment"`);
+  }
+
+  if (!target) warnings.push("No target specified");
+  if (!body) warnings.push("Empty annotation body");
+
+  return {
+    node: {
+      id: `A-${stem}`,
+      target: { type: targetType, id: target },
+      target_line: targetLine,
+      author,
+      date,
+      body,
+      action: validAction,
+    },
+    confidence: target && body ? 1.0 : 0.5,
+    warnings,
+    source: { file: filePath },
+  };
+}

package/parser/decision-parser.ts

@@ -0,0 +1,104 @@
+// Decision parser — extract DD from dge/decisions/DD-*.md
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import type { Decision, ParseResult } from "../graph/schema.js";
+
+const DD_ID_RE = /^DD-(\d+)/;
+const FIELD_RE = /^-\s+\*{0,2}(\w[\w\s/]*?)\*{0,2}[:：]\s*(.+)/;
+const SESSION_LINK_RE = /\[([^\]]+)\]\(\.\.\/sessions\/([^)]+)\)/g;
+const GAP_REF_RE = /#(\d+)/g;
+const SUPERSEDES_RE = /Supersedes[:：]\s*(DD-\d+(?:\s*,\s*DD-\d+)*)/i;
+const SUPERSEDED_BY_RE = /Superseded\s+by[:：]\s*(DD-\d+(?:\s*,\s*DD-\d+)*)/i;
+
+export function parseDecision(filePath: string): ParseResult<Decision> {
+  const content = readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const warnings: string[] = [];
+  const stem = path.basename(filePath, ".md");
+
+  // ID from filename
+  const idMatch = stem.match(DD_ID_RE);
+  const id = idMatch ? `DD-${idMatch[1]}` : stem;
+
+  // Title from H1
+  const h1 = lines.find((l) => l.startsWith("# "));
+  const title = h1?.replace(/^#\s+/, "").replace(/^DD-\d+[:：]?\s*/, "") ?? "";
+
+  // Fields from frontmatter-style metadata
+  const fields: Record<string, string> = {};
+  for (const line of lines) {
+    const m = line.match(FIELD_RE);
+    if (m) fields[m[1].trim().toLowerCase()] = m[2].trim();
+  }
+
+  const date = fields["date"] ?? "";
+
+  // Session refs from links
+  const sessionRefs: string[] = [];
+  for (const match of content.matchAll(SESSION_LINK_RE)) {
+    const sessionFile = match[2].replace(".md", "");
+    sessionRefs.push(sessionFile);
+  }
+
+  // Gap refs from # numbers
+  const gapRefs: string[] = [];
+  const gapField = fields["gap"] ?? "";
+  for (const match of gapField.matchAll(GAP_REF_RE)) {
+    gapRefs.push(match[0]);
+  }
+
+  // Supersedes
+  const supersedes: string[] = [];
+  const supMatch = content.match(SUPERSEDES_RE);
+  if (supMatch) {
+    supersedes.push(...supMatch[1].split(/\s*,\s*/));
+  }
+
+  // Superseded by
+  const supersededBy: string[] = [];
+  const supByMatch = content.match(SUPERSEDED_BY_RE);
+  if (supByMatch) {
+    supersededBy.push(...supByMatch[1].split(/\s*,\s*/));
+  }
+
+  // Rationale — text under ## Rationale or ## Decision
+  let rationale = "";
+  let inRationale = false;
+  for (const line of lines) {
+    if (/^##\s+(Rationale|Decision)/i.test(line)) {
+      inRationale = true;
+      continue;
+    }
+    if (inRationale && line.startsWith("## ")) break;
+    if (inRationale && line.trim()) {
+      rationale += (rationale ? " " : "") + line.trim();
+    }
+  }
+
+  // Status — check frontmatter for explicit status, otherwise default to active
+  const statusField = fields["status"]?.toLowerCase();
+  const status = statusField === "overturned" ? "overturned" as const : "active" as const;
+
+  if (!date) warnings.push("date not found");
+  if (sessionRefs.length === 0) warnings.push("no session references found");
+
+  return {
+    node: {
+      id,
+      title,
+      date,
+      rationale,
+      status,
+      supersedes,
+      superseded_by: supersededBy,
+      gap_refs: gapRefs,
+      session_refs: sessionRefs,
+      file_path: filePath,
+      content,
+    },
+    confidence: date && title ? 1.0 : 0.7,
+    warnings,
+    source: { file: filePath },
+  };
+}

package/parser/drift-detector.ts

@@ -0,0 +1,45 @@
+// Drift detector — detect decisions that may have diverged from implementation
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { GraphNode, Decision } from "../graph/schema.js";
+
+export interface DriftResult {
+  ddId: string;
+  commitsSince: number;
+  latestCommit: string;
+  ddDate: string;
+}
+
+export function detectDrift(ddNodes: GraphNode[], cwd: string): DriftResult[] {
+  const results: DriftResult[] = [];
+
+  for (const dd of ddNodes) {
+    const data = dd.data as Partial<Decision>;
+    if (!data.date || data.status === "overturned") continue;
+
+    try {
+      const log = execSync(
+        `git log --oneline --since="${data.date}" -- .`,
+        { cwd, encoding: "utf-8", timeout: 5000 }
+      ).trim();
+
+      const commits = log ? log.split("\n").length : 0;
+      // Heuristic: if more than 10 commits since DD date, it might have drifted
+      if (commits > 10) {
+        const latest = log.split("\n")[0] ?? "";
+        results.push({
+          ddId: dd.id,
+          commitsSince: commits,
+          latestCommit: latest,
+          ddDate: data.date,
+        });
+      }
+    } catch {
+      // git not available
+    }
+  }
+
+  return results;
+}

package/parser/git-linker.ts

@@ -0,0 +1,62 @@
+// git-linker — scan git log for "Ref: DD-*" and create implements edges
+
+import { execSync } from "node:child_process";
+import type { Edge } from "../graph/schema.js";
+
+const REF_RE = /Ref:\s*(DD-\d+)/gi;
+
+export interface GitLink {
+  commit: string;
+  date: string;
+  message: string;
+  ddRef: string;
+}
+
+export function scanGitLog(cwd: string, maxCommits = 500): GitLink[] {
+  const links: GitLink[] = [];
+
+  try {
+    const log = execSync(
+      `git log --oneline --format="%H|%aI|%s" -${maxCommits}`,
+      { cwd, encoding: "utf-8", timeout: 10000 }
+    );
+
+    for (const line of log.split("\n")) {
+      if (!line.trim()) continue;
+      const [commit, date, ...msgParts] = line.split("|");
+      const message = msgParts.join("|");
+
+      for (const match of message.matchAll(REF_RE)) {
+        links.push({
+          commit: commit.trim(),
+          date: date?.trim() ?? "",
+          message: message.trim(),
+          ddRef: match[1],
+        });
+      }
+    }
+  } catch {
+    // git not available or not a repo — return empty
+  }
+
+  return links;
+}
+
+export function gitLinkerEdges(cwd: string, existingDDIds: Set<string>): Edge[] {
+  const links = scanGitLog(cwd);
+  const edges: Edge[] = [];
+
+  for (const link of links) {
+    if (existingDDIds.has(link.ddRef)) {
+      edges.push({
+        source: link.ddRef,
+        target: `commit:${link.commit.slice(0, 7)}`,
+        type: "implements",
+        confidence: "explicit",
+        evidence: `git commit ${link.commit.slice(0, 7)}: ${link.message}`,
+      });
+    }
+  }
+
+  return edges;
+}

package/parser/glossary-builder.ts

@@ -0,0 +1,116 @@
+// Glossary builder — auto-extract terms from DDs, sessions, specs + custom glossary
+
+import { readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import type { DVEGraph } from "../graph/schema.js";
+
+export interface GlossaryEntry {
+  term: string;
+  definition: string;
+  source: string;       // "DD-001" | "session:xxx" | "custom"
+  aliases?: string[];   // alternative forms
+}
+
+export interface Glossary {
+  entries: GlossaryEntry[];
+}
+
+// Auto-extract terms from graph data
+export function buildGlossary(graph: DVEGraph, projectPath: string): Glossary {
+  const entries: GlossaryEntry[] = [];
+  const seen = new Set<string>();
+
+  function add(term: string, definition: string, source: string, aliases?: string[]) {
+    const key = term.toLowerCase();
+    if (seen.has(key) || term.length < 2) return;
+    seen.add(key);
+    entries.push({ term, definition, source, aliases });
+  }
+
+  // 1. DD titles → terms
+  for (const node of graph.nodes) {
+    if (node.type === "decision") {
+      const d = node.data as any;
+      add(node.id, d.title ?? "", node.id);
+    }
+  }
+
+  // 2. Gap categories as terms
+  const categories = new Set<string>();
+  for (const node of graph.nodes) {
+    if (node.type === "gap") {
+      const d = node.data as any;
+      if (d.category && d.category !== "Unknown") categories.add(d.category);
+    }
+  }
+  const categoryDefs: Record<string, string> = {
+    "missing-logic": "ロジックの欠落 — 実装すべき処理が spec に記述されていない",
+    "missing logic": "ロジックの欠落 — 実装すべき処理が spec に記述されていない",
+    "spec-impl-mismatch": "仕様と実装の不整合 — spec と実際のコードが矛盾",
+    "spec-impl mismatch": "仕様と実装の不整合 — spec と実際のコードが矛盾",
+    "error-quality": "エラー品質 — エラーメッセージやハンドリングの不足",
+    "error quality": "エラー品質 — エラーメッセージやハンドリングの不足",
+    "integration": "統合の問題 — コンポーネント間の接続や依存の欠陥",
+    "UX": "ユーザー体験 — 操作性、表示、フィードバックの問題",
+    "test-coverage": "テストカバレッジ — テストが不足している領域",
+    "test coverage": "テストカバレッジ — テストが不足している領域",
+  };
+  for (const cat of categories) {
+    add(cat, categoryDefs[cat] ?? `Gap カテゴリ: ${cat}`, "system");
+  }
+
+  // 3. DxE-specific terms
+  const dxeTerms: [string, string, string[]][] = [
+    ["DGE", "Design-Gap Extraction — 会話劇で設計の穴を発見するメソッド", ["Dialogue-driven Gap Extraction"]],
+    ["DRE", "Document Rule Engine — rules/skills/agents をパッケージ化して配布", []],
+    ["DVE", "Decision Visualization Engine — 決定プロセスの可視化ツール", []],
+    ["DDE", "Document-Deficit Extraction — ドキュメントの穴を LLM+CLI で補完", []],
+    ["DD", "Design Decision — 設計判断の記録。DGE session から生まれる", ["Design Decision"]],
+    ["Gap", "設計の穴 — DGE の会話劇で発見される未定義・矛盾・考慮漏れ", []],
+    ["Session", "DGE の会話劇セッション。キャラクターが設計について議論し Gap を発見する", []],
+    ["Annotation", "後から追加するコメント・異議・撤回。session を汚さず別レイヤーで保存", []],
+    ["Spec", "Gap から生成された仕様書。UC/TECH/DD/DQ/ACT の5タイプ", []],
+    ["ContextBundle", "DVE → DGE の橋渡しデータ。過去の文脈を復元して DGE に渡す", []],
+    ["orphan gap", "DD に紐づかない孤立 Gap。まだ決定されていない設計の穴", ["孤立Gap"]],
+    ["overturn", "決定の撤回。DD のステータスが overturned に変わる", ["撤回"]],
+    ["drift", "現実との乖離。DD の内容と実際のコードが食い違っている状態", ["ドリフト"]],
+    ["supersedes", "DD の置き換え。新しい DD が古い DD を supersede する", []],
+    ["enforcement", "Hook ベースのルール強制。PostToolUse + Stop hook で検証", []],
+  ];
+  for (const [term, def, aliases] of dxeTerms) {
+    add(term, def, "system", aliases);
+  }
+
+  // 4. Characters
+  const charDefs: Record<string, string> = {
+    "今泉": "The Innocent Questioner — 前提を問う。5つの問いパターン（そもそも/要するに/他にないの/誰が困る/前もそうだった）",
+    "ヤン": "The Lazy Strategist — 最もシンプルな解を見つける。「要らなくない？」",
+    "千石": "品質を守る。「お客様への侮辱です」",
+    "リヴァイ": "The Implementation Enforcer — 動くものを要求する。「汚い。作り直せ。」",
+    "深澤": "The UX Feeler — ユーザーの感情と体験を言語化する",
+    "ビーン": "The Data Evangelist — 「データは何て言ってる？」",
+    "僕": "The Small-Scale Survivor — scope を縮小する。「もっと小規模にできませんか？」",
+    "Red Team": "セキュリティ/攻撃視点。「競合がこうしたら？」",
+    "ハウス": "隠れた問題を見つける。「全員嘘をついている」",
+    "ソクラテス": "前提を問い続ける。「なぜそう思う？ もし逆だったら？」",
+  };
+  for (const [name, def] of Object.entries(charDefs)) {
+    add(name, def, "character");
+  }
+
+  // 5. Custom glossary file
+  const customPath = path.join(projectPath, "dve", "glossary.json");
+  if (existsSync(customPath)) {
+    try {
+      const custom = JSON.parse(readFileSync(customPath, "utf-8"));
+      for (const entry of custom.entries ?? []) {
+        add(entry.term, entry.definition, "custom", entry.aliases);
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Sort by term length descending (longer terms match first)
+  entries.sort((a, b) => b.term.length - a.term.length);
+
+  return { entries };
+}