@hongmaple0820/scale-engine 0.43.0 → 0.45.0

package/dist/topology/TourGenerator.js

@@ -0,0 +1,120 @@
+const LAYER_DESCRIPTIONS = {
+    api: 'API layer — handles external requests and routes them to the appropriate services',
+    service: 'Service layer — contains business logic and orchestrates operations',
+    data: 'Data layer — manages data persistence, models, and storage',
+    ui: 'UI layer — renders the user interface and handles user interactions',
+    utility: 'Utility layer — provides shared helpers and common functionality',
+    config: 'Configuration layer — defines settings and initialization',
+    test: 'Test layer — verifies correctness through automated tests',
+    unknown: 'Unclassified component',
+};
+export function generateTour(graph, options = {}) {
+    const maxStops = options.maxStops ?? 20;
+    const entryPoints = findEntryPoints(graph);
+    const orderedNodes = bfsFromEntries(graph, entryPoints);
+    const stops = [];
+    for (const nodeId of orderedNodes) {
+        if (stops.length >= maxStops)
+            break;
+        const node = graph.nodes.find(n => n.id === nodeId);
+        if (!node)
+            continue;
+        const relatedNodes = findRelatedNodes(graph, nodeId);
+        stops.push({
+            nodeId,
+            title: formatNodeTitle(node),
+            description: generateStopDescription(node, graph),
+            layer: node.layer ?? 'unknown',
+            relatedNodes,
+            order: stops.length + 1,
+        });
+    }
+    return {
+        name: options.focusDomain
+            ? `${options.focusDomain} Architecture Tour`
+            : 'Architecture Tour',
+        stops,
+        estimatedMinutes: Math.max(1, Math.ceil(stops.length * 0.5)),
+    };
+}
+function findEntryPoints(graph) {
+    const incomingCount = new Map();
+    for (const edge of graph.edges) {
+        incomingCount.set(edge.target, (incomingCount.get(edge.target) ?? 0) + 1);
+    }
+    // Entry points: nodes with no incoming edges, preferring main/index/app/server
+    const noIncoming = graph.nodes.filter(n => (incomingCount.get(n.id) ?? 0) === 0);
+    const priorityNames = ['main', 'index', 'app', 'server', 'cli', 'entry', 'run', 'start'];
+    const sorted = noIncoming.sort((a, b) => {
+        const aPriority = priorityNames.findIndex(name => a.name.toLowerCase().includes(name));
+        const bPriority = priorityNames.findIndex(name => b.name.toLowerCase().includes(name));
+        const aRank = aPriority === -1 ? 999 : aPriority;
+        const bRank = bPriority === -1 ? 999 : bPriority;
+        return aRank - bRank;
+    });
+    // If no entry points found, use all file-level nodes
+    if (sorted.length === 0) {
+        return graph.nodes.filter(n => n.kind === 'file').slice(0, 5).map(n => n.id);
+    }
+    return sorted.slice(0, 10).map(n => n.id);
+}
+function bfsFromEntries(graph, entries) {
+    const visited = new Set();
+    const order = [];
+    const queue = [...entries];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        order.push(current);
+        // Follow outgoing edges (dependencies, calls)
+        for (const edge of graph.edges) {
+            if (edge.source === current && !visited.has(edge.target)) {
+                queue.push(edge.target);
+            }
+        }
+    }
+    // Add any unvisited nodes at the end
+    for (const node of graph.nodes) {
+        if (!visited.has(node.id)) {
+            order.push(node.id);
+        }
+    }
+    return order;
+}
+function findRelatedNodes(graph, nodeId) {
+    const related = new Set();
+    for (const edge of graph.edges) {
+        if (edge.source === nodeId)
+            related.add(edge.target);
+        if (edge.target === nodeId)
+            related.add(edge.source);
+    }
+    return Array.from(related).slice(0, 5);
+}
+function formatNodeTitle(node) {
+    const layerTag = node.layer ? `[${node.layer.toUpperCase()}] ` : '';
+    const kindTag = node.kind === 'file' ? '' : ` (${node.kind})`;
+    return `${layerTag}${node.name}${kindTag}`;
+}
+function generateStopDescription(node, graph) {
+    const layerDesc = LAYER_DESCRIPTIONS[node.layer ?? 'unknown'];
+    const parts = [layerDesc];
+    if (node.filePath) {
+        parts.push(`Located in ${node.filePath}`);
+    }
+    // Count connections
+    const outgoing = graph.edges.filter(e => e.source === node.id).length;
+    const incoming = graph.edges.filter(e => e.target === node.id).length;
+    if (outgoing > 0 || incoming > 0) {
+        const connDesc = [];
+        if (outgoing > 0)
+            connDesc.push(`depends on ${outgoing}`);
+        if (incoming > 0)
+            connDesc.push(`depended on by ${incoming}`);
+        parts.push(`Connections: ${connDesc.join(', ')}`);
+    }
+    return parts.join('. ') + '.';
+}
+//# sourceMappingURL=TourGenerator.js.map

package/dist/topology/TourGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourGenerator.js","sourceRoot":"","sources":["../../src/topology/TourGenerator.ts"],"names":[],"mappings":"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"}

package/dist/topology/index.d.ts

@@ -0,0 +1,3 @@
+export { classifyLayers, getLayerColor, DEFAULT_LAYER_RULES, type LayerRule } from './LayerClassifier.js';
+export { mapDomains, type BusinessDomain, type DomainFlow, type DomainMapping } from './DomainMapper.js';
+export { generateTour, type TourStop, type GuidedTour } from './TourGenerator.js';

package/dist/topology/index.js

@@ -0,0 +1,4 @@
+export { classifyLayers, getLayerColor, DEFAULT_LAYER_RULES } from './LayerClassifier.js';
+export { mapDomains } from './DomainMapper.js';
+export { generateTour } from './TourGenerator.js';
+//# sourceMappingURL=index.js.map

package/dist/topology/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAkB,MAAM,sBAAsB,CAAA;AACzG,OAAO,EAAE,UAAU,EAA4D,MAAM,mBAAmB,CAAA;AACxG,OAAO,EAAE,YAAY,EAAkC,MAAM,oBAAoB,CAAA"}

package/docs/README.md

@@ -63,6 +63,9 @@
 
 | 文档 | 说明 |
 | --- | --- |
+| [architecture/README.md](architecture/README.md) | **架构总览** — Mermaid 图解系统架构、核心引擎、数据流 |
+| [reference/cli.md](reference/cli.md) | **CLI 参考** — 完整命令列表和用法示例 |
+| [migration/v0.38-to-v0.44.md](migration/v0.38-to-v0.44.md) | **迁移指南** — v0.38 到 v0.44 的破坏性变更和升级步骤 |
 | [00-OVERVIEW.md](00-OVERVIEW.md) | 系统概览 |
 | [01-ARCHITECTURE.md](01-ARCHITECTURE.md) | 架构设计 |
 | [02-DATA-MODEL.md](02-DATA-MODEL.md) | 数据模型 |

package/docs/architecture/README.md

@@ -0,0 +1,248 @@
+# SCALE Engine Architecture
+
+## System Overview
+
+SCALE Engine is an AI Engineering Operating System that provides governance, workflow automation, and continuous evolution for AI-assisted development.
+
+```mermaid
+graph TB
+    subgraph "Entry Points"
+        CLI[CLI]
+        MCP[MCP Server]
+        HTTP[HTTP API]
+    end
+
+    subgraph "Core Engines"
+        Shield[Shield<br/>Security Hooks]
+        Orch[Orchestrator<br/>Declarative Workflow]
+        Cortex[Cortex<br/>Continuous Evolution]
+    end
+
+    subgraph "Intelligence Layer"
+        CodeGraph[CodeGraph<br/>AST Analysis]
+        Memory[Memory<br/>3-Layer Architecture]
+        Skills[Skills<br/>Capability Routing]
+    end
+
+    subgraph "Workflow Pipeline"
+        Define[Define]
+        Plan[Plan]
+        Build[Build]
+        Verify[Verify]
+        Review[Review]
+        Ship[Ship]
+    end
+
+    subgraph "Storage"
+        SQLite[(SQLite)]
+        JSON[JSON Files]
+        Git[Git]
+    end
+
+    CLI --> Shield
+    CLI --> Orch
+    CLI --> Cortex
+    MCP --> CodeGraph
+    HTTP --> Memory
+
+    Shield --> Skills
+    Orch --> Define
+    Cortex --> Memory
+
+    Define --> Plan --> Build --> Verify --> Review --> Ship
+
+    CodeGraph --> SQLite
+    Memory --> SQLite
+    Skills --> JSON
+    Orch --> Git
+```
+
+## Core Engines
+
+### Shield
+
+Hook-based security engine that intercepts dangerous commands.
+
+```mermaid
+graph LR
+    YAML[YAML Policies] --> Compiler[Compiler]
+    Compiler --> Hooks[Shell Hooks]
+    Hooks --> Intercept[Intercept]
+    Intercept --> Block[Block]
+    Intercept --> Allow[Allow]
+    Intercept --> Warn[Warn]
+```
+
+### Orchestrator
+
+Declarative orchestration daemon with git worktree isolation.
+
+```mermaid
+graph TB
+    Config[Config] --> Engine[Engine]
+    Engine --> Tracker[Tracker]
+    Engine --> Worktree[Worktree]
+    Engine --> Loop[Coordination Loop]
+    Loop --> Task[Task]
+    Loop --> Evidence[Evidence]
+    Loop --> Gate[Gate]
+```
+
+### Cortex
+
+Evidence-driven continuous evolution with instinct extraction.
+
+```mermaid
+graph LR
+    Obs[Observations] --> Extract[Extract]
+    Extract --> Instincts[Instincts]
+    Instincts --> Inject[Inject]
+    Inject --> Session[Session]
+    Session --> Metrics[Metrics]
+```
+
+## Intelligence Layer
+
+### CodeGraph
+
+AST-based code intelligence using tree-sitter.
+
+```mermaid
+graph TB
+    Source[Source Code] --> Parser[Tree-sitter]
+    Parser --> AST[AST]
+    AST --> Graph[Knowledge Graph]
+    Graph --> Query[Query Engine]
+    Query --> Impact[Impact Analysis]
+    Query --> Context[Context Building]
+```
+
+### Memory (3-Layer Architecture)
+
+```mermaid
+graph TB
+    L1[L1: Trace<br/>Raw observations] --> Refine1[Refine]
+    Refine1 --> L2[L2: Policy<br/>Extracted patterns]
+    L2 --> Refine2[Refine]
+    Refine2 --> L3[L3: World Model<br/>Consolidated knowledge]
+    L3 --> Crystal[Crystallized<br/>Global wisdom]
+```
+
+### Skills
+
+Capability routing with supply chain safety.
+
+```mermaid
+graph LR
+    Task[Task] --> Recommend[Recommend]
+    Recommend --> Skills[Skills]
+    Skills --> Safety[Safety Check]
+    Safety --> Install[Install]
+    Install --> Evidence[Evidence]
+```
+
+## Workflow Pipeline
+
+```mermaid
+stateDiagram-v2
+    [*] --> Define
+    Define --> Plan
+    Plan --> Build
+    Build --> Verify
+    Verify --> Review
+    Review --> Ship
+    Ship --> [*]
+
+    Define --> Define: Scope unclear
+    Plan --> Plan: Missing info
+    Build --> Build: Tests fail
+    Verify --> Verify: Gates fail
+    Review --> Review: Issues found
+    Ship --> Ship: Checks fail
+```
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant Engine
+    participant Memory
+    participant CodeGraph
+
+    User->>CLI: scale define "task"
+    CLI->>Engine: Create artifact
+    Engine->>Memory: Query similar
+    Memory-->>Engine: Context
+
+    User->>CLI: scale build
+    CLI->>Engine: Execute TDD
+    Engine->>CodeGraph: Query symbols
+    CodeGraph-->>Engine: Impact analysis
+
+    User->>CLI: scale verify
+    CLI->>Engine: Run gates
+    Engine->>Memory: Record evidence
+    Memory-->>Engine: Confirmation
+```
+
+## Storage Architecture
+
+```mermaid
+graph TB
+    subgraph ".scale/"
+        SQLite[(brain.sqlite)]
+        Instincts[instincts/]
+        Evidence[evidence/]
+        Specs[specs/]
+        Memory[memory/]
+    end
+
+    subgraph "Project"
+        SRC[src/]
+        TESTS[tests/]
+        DOCS[docs/]
+    end
+
+    SQLite --> Memory
+    Instincts --> Cortex
+    Evidence --> Runtime
+    Specs --> Inject
+```
+
+## Integration Points
+
+### MCP Server
+
+Model Context Protocol server over stdio for AI agent integration.
+
+```mermaid
+graph LR
+    Agent[AI Agent] -->|JSON-RPC| MCP[MCP Server]
+    MCP --> Tools[Tools]
+    Tools --> Scale[SCALE Engine]
+    Scale --> Results[Results]
+    Results --> Agent
+```
+
+### HTTP API
+
+Hono-based HTTP server for dashboard and external integrations.
+
+```mermaid
+graph LR
+    Client[Client] -->|HTTP| Hono[Hono Server]
+    Hono --> Routes[Routes]
+    Routes --> Engine[SCALE Engine]
+    Engine --> Response[Response]
+    Response --> Client
+```
+
+## Key Design Decisions
+
+1. **SQLite over PostgreSQL**: Embedded, zero-config, sufficient for project-scoped data
+2. **Functional composition**: Pure functions over classes for testability
+3. **Evidence-first**: All decisions backed by observable evidence
+4. **Progressive governance**: Gradual adoption of governance practices
+5. **Supply chain safety**: Every external dependency verified before use

package/docs/migration/v0.38-to-v0.44.md

@@ -0,0 +1,232 @@
+# Migration Guide: v0.38 → v0.44
+
+This guide covers breaking changes and migration steps from SCALE Engine v0.38 to v0.44.
+
+## Breaking Changes
+
+### 1. CLI Command Restructuring
+
+The CLI has been reorganized into modular subcommands:
+
+| Old Command | New Command |
+|-------------|-------------|
+| `scale session start` | `scale session start` (unchanged) |
+| `scale gate pre-tool` | `scale gate pre-tool` (unchanged) |
+| `scale shield compile` | `scale shield compile` (unchanged) |
+| `scale orch start` | `scale orch start` (unchanged) |
+| `scale cortex extract` | `scale cortex extract` (unchanged) |
+
+Most commands remain backward-compatible. New phase-aligned commands added:
+
+```bash
+scale define "task description" --level M
+scale plan
+scale build
+scale verify
+scale review
+scale ship
+```
+
+### 2. Memory Provider Configuration
+
+Memory providers now use a unified configuration file:
+
+**Before:** Inline configuration in various places
+**After:** `.scale/memory-providers.json`
+
+```json
+{
+  "version": "1.0",
+  "routing": {
+    "mode": "external-first",
+    "defaultOrder": ["gbrain", "memos", "agentmemory", "scale-local"]
+  },
+  "providers": [...]
+}
+```
+
+Initialize with:
+```bash
+scale memory provider init
+```
+
+### 3. Gate System Changes
+
+Gates G16-G22 have been added:
+
+| Gate | Name | Default | Blocking |
+|------|------|---------|----------|
+| G16 | Commit Discipline | yes | yes |
+| G17 | Documentation Hygiene | yes | no (M) / yes (L) |
+| G18 | Runtime Evidence | yes | yes |
+| G19 | Code Review | profile | yes (L+) |
+| G20 | Supply Chain | yes | yes |
+| G21 | Context Budget | yes | no |
+| G22 | Session Health | yes | no |
+
+### 4. Memory Architecture
+
+MemoryBrain now uses a 3-layer architecture:
+
+- **L1-trace**: Raw observations (default for new nodes)
+- **L2-policy**: Extracted patterns from L1 traces
+- **L3-world-model**: Consolidated knowledge from L2 policies
+- **crystallized**: High-confidence global wisdom
+
+Run `scale memory dream` to see layer statistics.
+
+### 5. Code Intelligence
+
+CodeGraph and code-review-graph integration:
+
+```bash
+# Initialize codegraph
+scale codegraph init
+
+# Query symbols
+scale codegraph query "UserService"
+
+# Analyze impact
+scale codegraph impact src/auth/login.ts
+```
+
+## New Features
+
+### 1. MCP Server
+
+SCALE now includes an MCP server for AI agent integration:
+
+```bash
+scale mcp  # Start MCP server over stdio
+```
+
+### 2. HTTP API
+
+Hono-based HTTP server for dashboard:
+
+```bash
+scale serve  # Start HTTP server
+```
+
+### 3. Skills System
+
+Skills are now managed through a repository:
+
+```bash
+scale skill scan        # Scan for available skills
+scale skill recommend   # Get recommendations
+scale skill repo        # Browse repository
+```
+
+### 4. Memory Providers
+
+External memory providers supported:
+
+- **gbrain**: Graph memory (CLI mode)
+- **MemOS**: 3-layer memory architecture
+- **agentmemory**: Semantic search (self-hosted)
+- **scale-local**: Local SQLite (zero deps)
+
+### 5. Code Review Graph
+
+Integration with code-review-graph for blast radius analysis:
+
+```bash
+pip install code-review-graph
+code-review-graph build
+
+# Use in SCALE
+scale codegraph status
+```
+
+## Configuration Changes
+
+### 1. Settings Location
+
+```
+.scale/
+├── memory-providers.json    # Memory provider config
+├── code-intelligence.json   # Code intelligence config
+├── policy.yaml              # Shield policy
+├── instincts/               # Cortex instincts
+├── memory/                  # Memory brain
+└── specs/                   # Scoped specs
+```
+
+### 2. Hook System
+
+Hooks are now in `.claude/hooks/`:
+
+```
+.claude/hooks/
+├── session-start-reminder.sh
+├── gate-execute-phase.sh
+├── crg-incremental-update.sh
+└── shield-pre-tool.js
+```
+
+### 3. Environment Variables
+
+New environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `GBRAIN_API_KEY` | GBrain API key |
+| `MEMOS_API_KEY` | MemOS API key |
+| `MEMOS_BASE_URL` | MemOS endpoint |
+| `AGENTMEMORY_ENDPOINT` | AgentMemory endpoint |
+
+## Upgrade Steps
+
+### 1. Backup Current State
+
+```bash
+cp -r .scale .scale.backup
+cp .claude/settings.json .claude/settings.json.backup
+```
+
+### 2. Update Package
+
+```bash
+npm update @hongmaple0820/scale-engine
+```
+
+### 3. Run Doctor
+
+```bash
+scale doctor
+```
+
+### 4. Reinitialize if Needed
+
+```bash
+scale init
+scale setup --interactive
+```
+
+### 5. Verify Installation
+
+```bash
+scale preflight
+scale shield status
+scale cortex verify
+```
+
+## Rollback
+
+If issues occur:
+
+```bash
+# Restore backup
+cp -r .scale.backup .scale
+cp .claude/settings.json.backup .claude/settings.json
+
+# Reinstall previous version
+npm install @hongmaple0820/scale-engine@0.38.0
+```
+
+## Support
+
+- GitHub Issues: https://github.com/your-org/scale-engine/issues
+- Documentation: docs/README.md
+- Migration help: `scale doctor --migration`