@laitszkin/apollo-toolkit 4.0.11 → 4.1.0

package/resources/project-architecture/atlas/atlas.history.undo.json

@@ -1,9 +1,9 @@
 {
   "base": {
     "meta": {
-      "title": "Project architecture",
-      "summary": "",
-      "updatedAt": "2026-05-29T13:27:29.781Z"
+      "title": "Project architecture  (+ codegraph integration overlay)",
+      "summary": "Baseline: eval 系統 (8 features). Overlay: 新增 codegraph 功能模組，包含 lifecycle 命令、discovery 命令、validation/apply 命令。 新增外部 actor: @colbymchenry/codegraph (npm 套件)。\n",
+      "updatedAt": "2026-06-03T13:18:56.775Z"
     },
     "actors": [
       {
@@ -21,9 +21,154 @@
       {
         "id": "skill-files",
         "label": "Skill Files (SKILL.md, scripts/, references/, assets/)"
+      },
+      {
+        "id": "codegraph-npm",
+        "label": "@colbymchenry/codegraph npm package"
+      },
+      {
+        "id": "tool-registry",
+        "label": "Tool Registry (@laitszkin/tool-registry)"
+      },
+      {
+        "id": "tui-lib",
+        "label": "TUI Library (@laitszkin/tui)"
       }
     ],
     "features": [
+      {
+        "slug": "codegraph",
+        "title": "CodeGraph Integration",
+        "story": "Provide LLM agents with deterministic code structure data through apltk CLI. Replaces manual grep/Read discovery with tree-sitter parsed knowledge graph queries.\n",
+        "dependsOn": [
+          "eval-cli"
+        ],
+        "submodules": [
+          {
+            "slug": "cg-lifecycle",
+            "kind": "service",
+            "role": "Manage CodeGraph index lifecycle — init, sync, status, search",
+            "functions": [
+              {
+                "name": "init",
+                "in": "projectRoot: string",
+                "out": "CodeGraph instance",
+                "side": "io",
+                "purpose": "Initialize .codegraph/ directory and optionally run full index"
+              },
+              {
+                "name": "sync",
+                "in": "projectRoot: string",
+                "out": "SyncResult",
+                "side": "io",
+                "purpose": "Incremental update of existing index"
+              },
+              {
+                "name": "status",
+                "in": "projectRoot: string",
+                "out": "GraphStats",
+                "side": "pure",
+                "purpose": "Query index statistics"
+              },
+              {
+                "name": "search",
+                "in": "query: string",
+                "out": "SearchResult[]",
+                "side": "pure",
+                "purpose": "Full-text symbol search via FTS5"
+              }
+            ],
+            "variables": [],
+            "dataflow": [],
+            "errors": []
+          },
+          {
+            "slug": "cg-discovery",
+            "kind": "service",
+            "role": "Explore and survey code structure — explore, survey, list-apis",
+            "functions": [
+              {
+                "name": "explore",
+                "in": "query: string",
+                "out": "Context (source grouped by file + relationship map)",
+                "side": "pure",
+                "purpose": "Get full context for symbols matching a query"
+              },
+              {
+                "name": "survey",
+                "in": "dirPath: string",
+                "out": "SurveyReport (submodule suggestions + edge suggestions)",
+                "side": "pure",
+                "purpose": "Survey a directory and produce atlas-compatible structure report"
+              },
+              {
+                "name": "listApis",
+                "in": "featureSlug: string",
+                "out": "APIDirectory (public functions + params + callers)",
+                "side": "pure",
+                "purpose": "List public API surface of a feature area"
+              }
+            ],
+            "variables": [],
+            "dataflow": [],
+            "errors": []
+          },
+          {
+            "slug": "cg-validation",
+            "kind": "service",
+            "role": "Verify architecture proposals and batch-apply atlas mutations",
+            "functions": [
+              {
+                "name": "verify",
+                "in": "specOverlayPath: string",
+                "out": "VerifyReport (passed/failed items)",
+                "side": "pure",
+                "purpose": "Validate that spec overlay references match actual code"
+              },
+              {
+                "name": "applyBatch",
+                "in": "proposalYaml: string",
+                "out": "ApplyResult",
+                "side": "io",
+                "purpose": "Execute multiple atlas mutations from a single YAML file"
+              },
+              {
+                "name": "generateTemplate",
+                "in": "specMdPath: string",
+                "out": "proposalYaml path",
+                "side": "io",
+                "purpose": "Generate empty proposal skeleton from SPEC.md"
+              }
+            ],
+            "variables": [],
+            "dataflow": [],
+            "errors": []
+          }
+        ],
+        "edges": [
+          {
+            "id": "cg-fe-001",
+            "from": "cg-lifecycle",
+            "to": "cg-discovery",
+            "kind": "data-row",
+            "label": "survey/list-apis 依賴已索引的資料庫"
+          },
+          {
+            "id": "cg-fe-002",
+            "from": "cg-discovery",
+            "to": "cg-validation",
+            "kind": "data-row",
+            "label": "verify 使用 discovery 的搜尋能力"
+          },
+          {
+            "id": "cg-fe-003",
+            "from": "cg-validation",
+            "to": "cg-lifecycle",
+            "kind": "data-row",
+            "label": "apply 非索引操作，不需 lifecycle — 但 template 可搭配 list-apis"
+          }
+        ]
+      },
       {
         "slug": "eval-optimizer",
         "title": "優化引擎",
@@ -34,7 +179,22 @@
             "slug": "issue-extractor",
             "kind": "service",
             "role": "從score.json提取問題、分類統計",
-            "functions": [],
+            "functions": [
+              {
+                "name": "extractIssues",
+                "in": "scores",
+                "out": "RawIssue[]",
+                "side": "pure",
+                "purpose": "從 score.json 提取問題與分類統計"
+              },
+              {
+                "name": "generateOptimizationPlan",
+                "in": "issues",
+                "out": "OptimizationPlan",
+                "side": "pure",
+                "purpose": "從去重後問題生成 FIND/REPLACE 優化 diff"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -43,7 +203,15 @@
             "slug": "dedup-engine",
             "kind": "service",
             "role": "Jaccard+Judge語意去重",
-            "functions": [],
+            "functions": [
+              {
+                "name": "deduplicateIssues",
+                "in": "issues",
+                "out": "DedupedIssue[]",
+                "side": "pure",
+                "purpose": "Jaccard+Judge 語意去重"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -70,7 +238,29 @@
             "slug": "cli-handler",
             "kind": "service",
             "role": "ToolDefinition註冊、參數解析、流程編排",
-            "functions": [],
+            "functions": [
+              {
+                "name": "evalHandler",
+                "in": "argv, context",
+                "out": "exitCode",
+                "side": "pure",
+                "purpose": "CLI 入口：解析參數、調度評測流程"
+              },
+              {
+                "name": "parseArgs",
+                "in": "argv",
+                "out": "ParsedArgs",
+                "side": "pure",
+                "purpose": "解析 CLI 參數與模式選擇"
+              },
+              {
+                "name": "tool",
+                "in": "ToolDefinition",
+                "out": "void",
+                "side": "pure",
+                "purpose": "向 tool-registry 註冊 eval 命令"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -97,7 +287,15 @@
             "slug": "workflow-trigger",
             "kind": "service",
             "role": "GitHub Actions workflow on PR skill file change",
-            "functions": [],
+            "functions": [
+              {
+                "name": "detectSkillChanges",
+                "in": "prFiles",
+                "out": "string[]",
+                "side": "pure",
+                "purpose": "檢測 PR 中技能檔案變更"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -124,7 +322,15 @@
             "slug": "tool-dispatcher",
             "kind": "service",
             "role": "工具調用攔截系統：讀取工具在workspace內真實執行、寫入工具模擬回傳、路徑穿越防護",
-            "functions": [],
+            "functions": [
+              {
+                "name": "buildSystemPrompt",
+                "in": "question",
+                "out": "string",
+                "side": "pure",
+                "purpose": "建立隔離環境的 system prompt"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -142,7 +348,15 @@
             "slug": "question-loader",
             "kind": "service",
             "role": "題目載入與JSON Schema驗證",
-            "functions": [],
+            "functions": [
+              {
+                "name": "loadQuestions",
+                "in": "specDir",
+                "out": "Question[]",
+                "side": "pure",
+                "purpose": "載入題目並進行 JSON Schema 驗證"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -151,7 +365,15 @@
             "slug": "variant-generator",
             "kind": "service",
             "role": "LLM變體生成，保留評分標準",
-            "functions": [],
+            "functions": [
+              {
+                "name": "generateVariants",
+                "in": "questions, count",
+                "out": "Question[]",
+                "side": "io",
+                "purpose": "LLM 變體生成，保留評分標準"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -169,7 +391,15 @@
             "slug": "trace-recorder",
             "kind": "service",
             "role": "多輪tool-use loop軌跡記錄：tool_call/tool_result事件序列、JSONL行號標記、.done完成標記",
-            "functions": [],
+            "functions": [
+              {
+                "name": "runSingleTest",
+                "in": "question, skillDir",
+                "out": "TraceEvent[]",
+                "side": "pure",
+                "purpose": "執行單一技能測試，記錄 tool call 軌跡"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -178,7 +408,15 @@
             "slug": "exec-api-client",
             "kind": "api",
             "role": "Exec Model HTTP client with retry",
-            "functions": [],
+            "functions": [
+              {
+                "name": "withRetry",
+                "in": "fn, options",
+                "out": "Result",
+                "side": "io",
+                "purpose": "HTTP client with retry for exec model"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -195,8 +433,16 @@
           {
             "slug": "judge-prompt-builder",
             "kind": "service",
-            "role": "評分提示詞構建（trace+criteria→prompt）",
-            "functions": [],
+            "role": "評分提示詞構建：trace事件摘要含JSONL行號(L{N})引用、三維度評分指示",
+            "functions": [
+              {
+                "name": "buildJudgePrompt",
+                "in": "trace, scoreCriteria",
+                "out": "string",
+                "side": "pure",
+                "purpose": "將 trace 事件摘要轉為評分提示詞"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -205,7 +451,15 @@
             "slug": "judge-api-client",
             "kind": "api",
             "role": "Judge Model HTTP client with parse fallback",
-            "functions": [],
+            "functions": [
+              {
+                "name": "callJudgeModel",
+                "in": "prompt, options",
+                "out": "ScoreResult",
+                "side": "io",
+                "purpose": "呼叫 Judge Model API 進行評分"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -223,7 +477,15 @@
             "slug": "report-composer",
             "kind": "service",
             "role": "Markdown報告組合與渲染",
-            "functions": [],
+            "functions": [
+              {
+                "name": "generateReport",
+                "in": "scores",
+                "out": "string",
+                "side": "pure",
+                "purpose": "彙總評分結果產出結構化 Markdown 報告"
+              }
+            ],
             "variables": [],
             "dataflow": [],
             "errors": []
@@ -234,37 +496,103 @@
     ],
     "edges": [
       {
-        "id": "e-101",
+        "id": "cg-e-001",
         "from": {
-          "feature": "eval-cli"
+          "feature": "codegraph",
+          "submodule": "cg-lifecycle"
         },
         "to": {
-          "feature": "eval-optimizer"
+          "feature": "codegraph",
+          "submodule": "cg-discovery"
         },
-        "kind": "call",
-        "label": "trigger optimization after scoring"
+        "kind": "data-row",
+        "label": "survey/list-apis 依賴已索引的資料庫"
       },
       {
-        "id": "e-102",
+        "id": "cg-e-002",
         "from": {
+          "feature": "codegraph",
+          "submodule": "cg-discovery"
+        },
+        "to": {
+          "feature": "codegraph",
+          "submodule": "cg-validation"
+        },
+        "kind": "data-row",
+        "label": "verify 使用 discovery 的搜尋能力"
+      },
+      {
+        "id": "cg-e-003",
+        "from": {
+          "feature": "codegraph",
+          "submodule": "cg-lifecycle"
+        },
+        "to": {
           "feature": "eval-cli"
         },
+        "kind": "call",
+        "label": "codegraph init --index 與 eval-cli 共用 CLI 工具基礎架構"
+      },
+      {
+        "id": "eval-cli-exec",
+        "from": {
+          "feature": "eval-cli",
+          "submodule": "cli-handler"
+        },
         "to": {
-          "feature": "eval-isolation"
+          "feature": "eval-executor",
+          "submodule": "trace-recorder"
         },
         "kind": "call",
-        "label": "setup tool mock + context isolation"
+        "label": "evalHandler 觸發 runSingleTest"
       },
       {
-        "id": "e-103",
+        "id": "eval-exec-iso",
         "from": {
-          "feature": "eval-ci-gate"
+          "feature": "eval-executor",
+          "submodule": "trace-recorder"
         },
         "to": {
-          "feature": "eval-cli"
+          "feature": "eval-isolation",
+          "submodule": "tool-dispatcher"
         },
         "kind": "call",
-        "label": "invoke apltk eval --mode standard"
+        "label": "執行隔離環境中的工具調用"
+      },
+      {
+        "id": "eval-exec-scorer",
+        "from": {
+          "feature": "eval-executor",
+          "submodule": "trace-recorder"
+        },
+        "to": {
+          "feature": "eval-scorer",
+          "submodule": "judge-prompt-builder"
+        },
+        "kind": "data-row",
+        "label": "trace events 送入評分"
+      },
+      {
+        "id": "eval-scorer-reporter",
+        "from": {
+          "feature": "eval-scorer"
+        },
+        "to": {
+          "feature": "eval-reporter"
+        },
+        "kind": "data-row",
+        "label": "ScoreResult 送入報告組合"
+      },
+      {
+        "id": "eval-exec-optimizer",
+        "from": {
+          "feature": "eval-executor"
+        },
+        "to": {
+          "feature": "eval-optimizer"
+        },
+        "kind": "data-row",
+        "label": "執行結果觸發優化"
       }
     ]
   }