@hongmaple0820/scale-engine 0.23.0 → 0.24.0

package/docs/DEPENDENCY_AUDIT.md

@@ -0,0 +1,89 @@
+# Dependency Audit
+
+Dependency Audit is the G7 dependency sub-gate for SCALE Engine.
+It adds supply-chain checks without introducing a separate gate number such as `G6.8`.
+
+## Scope
+
+The auditor is intentionally bounded:
+
+- reads `package-lock.json`
+- audits direct dependencies by default
+- supports `--changed-packages` for lockfile-diff workflows
+- scans only selected package roots under `node_modules`
+- caps package count and files per package
+- does not contact the registry by default
+- does not run install scripts
+
+This keeps local verification usable while still catching high-risk dependency behavior.
+
+## Commands
+
+```bash
+scale dependency audit
+scale dependency audit --json
+scale dependency audit --mode strict
+scale dependency audit --changed-packages left-pad,@scope/tool --json
+```
+
+The command exits non-zero when the active mode has blocking findings.
+
+## G7 Integration
+
+`SecurityGate` now emits two first-class evidence sources:
+
+- `built-in-security-scan`: source code security scan
+- `dependency-audit`: dependency supply-chain scan
+
+Both remain under `G7 Security`.
+
+## Policy
+
+Policy lives at `.scale/security/dependency-policy.json`:
+
+```json
+{
+  "version": 1,
+  "mode": "compatibility",
+  "maxPackages": 50,
+  "maxPackageFiles": 25,
+  "allowPackages": [],
+  "baselineFindings": []
+}
+```
+
+Modes:
+
+- `compatibility`: blocks `CRITICAL`
+- `strict`: blocks `CRITICAL` and `HIGH`
+- `offline`: keeps local-only behavior; current offline findings follow compatibility blocking
+
+Use `baselineFindings` for accepted legacy dependency risk:
+
+```json
+{
+  "baselineFindings": [
+    {
+      "packageName": "legacy-tool",
+      "version": "1.2.3",
+      "ruleId": "dependency.install-script",
+      "reason": "Pinned and reviewed during migration window."
+    }
+  ]
+}
+```
+
+Prefer a baseline over `allowPackages` when only one finding is accepted. `allowPackages` suppresses all findings for that package.
+
+## Current Findings
+
+The first implementation detects:
+
+- install lifecycle scripts
+- executable bin scripts
+- deprecated packages from lockfile metadata
+- dynamic code execution: `eval`, `new Function`
+- shell execution patterns
+- suspicious network access patterns
+
+Future network-backed checks can add npm registry metadata and `npm audit --json` ingestion, but they should stay optional and evidence-backed.

package/docs/EVOLUTION_SHADOW_MODE.md

@@ -0,0 +1,63 @@
+# Evolution Shadow Mode
+
+SCALE V2 keeps self-evolution useful without letting one-off failures become hard blockers too early.
+
+## Flow
+
+```text
+Gate Failure
+  -> Defect
+  -> Lesson
+  -> Proposed Rule
+  -> Shadow Rule
+  -> Candidate Hook
+  -> Approved Blocking Hook
+```
+
+## Gate Failure To Defect
+
+`GateSystem` emits `gate.failed` for failed gate results. `AutoDefectCreator` tracks consecutive failures per session and gate stage.
+
+Default behavior:
+
+- three consecutive failures create one `Defect`
+- a passing `gate.executed` event resets the streak
+- defect payload uses `rootCauseCategory=gate_failure`
+- the original blockers, evidence, evidence record id, stage, and streak count are stored in defect context
+
+This is evidence capture only. It does not change source code or generate a hook.
+
+## Rule Maturity
+
+New rules start in `shadow` mode. Shadow rules can record hits, but they do not block development.
+
+Promotion requires:
+
+- shadow hits >= 10
+- at least one defect evidence id
+- rollback method present
+- false positive rate within threshold
+- explicit approval before a blocking hook is allowed
+
+`RuleMaturity` exposes:
+
+- `createShadowRuleMaturity`
+- `recordShadowHit`
+- `evaluateRulePromotion`
+- `approveRuleMaturity`
+
+## Hook Boundary
+
+`HookGenerator` still requires `rule.approved === true`.
+
+For V2 rules that carry maturity metadata, it also requires:
+
+```text
+rule.maturity.stage === "approved-blocking"
+```
+
+That means proposed or shadow rules can be observed and improved, but cannot become blocking hooks until explicitly promoted.
+
+## Current Scope
+
+This release slice wires the core library path and gate events. CLI approval commands and persistent rule-maturity storage can be added later without changing the safety model.

package/docs/GOVERNANCE_DASHBOARD.md

@@ -32,11 +32,27 @@ The dashboard reads existing local evidence:
 
 | Area | Source |
 | --- | --- |
-| Runtime evidence | `.scale/evidence/runtime/` |
-| Workflow eval | `.scale/evals/runs/` and `.scale/evals/failures/` |
-| Memory Brain | `.scale/memory/brain.sqlite` |
-| Resource Governance | workspace files plus `.scale/resource-policy.json` and `.scale/assets.json` |
-| HTML artifacts | task artifact manifests and rendered HTML files |
+| Runtime evidence | `.scale/evidence/runtime/` |
+| Workflow eval | `.scale/evals/runs/` and `.scale/evals/failures/` |
+| Workflow metrics | `.scale/metrics/tasks.jsonl` |
+| Gate evidence | `.scale/evidence/GATE-*.json` |
+| Command runs | `.scale/evidence/command-runs/` |
+| Model usage | `.scale/model-usage/usage.jsonl` |
+| Memory Brain | `.scale/memory/brain.sqlite` |
+| Resource Governance | workspace files plus `.scale/resource-policy.json` and `.scale/assets.json` |
+| HTML artifacts | task artifact manifests and rendered HTML files |
+
+## Aggregated Metrics
+
+V2.0 adds `MetricsAggregator` as the dashboard aggregation layer. It keeps the dashboard read-only and derives the following metrics from existing evidence:
+
+- recent task count and first-pass rate
+- average fix iterations
+- gate failure distribution
+- command output compression token savings
+- model usage and prompt-cache savings
+
+Each number must trace back to local JSON/JSONL evidence. If a source is absent, the dashboard reports zero rather than inventing values.
 
 ## Status Model
 

package/docs/README.md

@@ -12,13 +12,15 @@
 | [start/artifact-lifecycle.md](start/artifact-lifecycle.md) | Artifact 生命周期完整 walkthrough |
 | [../README.md](../README.md) | 项目主页和能力总览 |
 
-## 当前治理能力
-
-| 文档 | 说明 |
-| --- | --- |
+## 当前治理能力
+
+| 文档 | 说明 |
+| --- | --- |
 | [RESOURCE_GOVERNANCE.md](RESOURCE_GOVERNANCE.md) | 文档、报告、媒体、脚本、临时产物的生命周期治理 |
-| [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md) | 日志、安全、ORM、框架、测试、部署等工程规范 |
-| [TOOL_ORCHESTRATION.md](TOOL_ORCHESTRATION.md) | skills、MCP、CLI、浏览器、桌面自动化的编排策略 |
+| [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md) | 日志、安全、ORM、框架、测试、部署等工程规范 |
+| [BACKGROUND_HUNTER.md](BACKGROUND_HUNTER.md) | Background Hunter 只读主动巡检、诊断交接和 ignore baseline |
+| [DEPENDENCY_AUDIT.md](DEPENDENCY_AUDIT.md) | 供应链依赖审计、G7 dependency 子门禁和 dependency policy |
+| [TOOL_ORCHESTRATION.md](TOOL_ORCHESTRATION.md) | skills、MCP、CLI、浏览器、桌面自动化的编排策略 |
 | [RUNTIME_EVIDENCE.md](RUNTIME_EVIDENCE.md) | 会话 ledger、运行时证据和最终交付检查 |
 | [MEMORY_FABRIC.md](MEMORY_FABRIC.md) | Runtime evidence、session events、knowledge recall 和 graph status 的预算化上下文包 |
 | [MEMORY_BRAIN.md](MEMORY_BRAIN.md) | 证据驱动的长期记忆、矛盾检测、dream 整理和 failure replay 沉淀 |
@@ -32,12 +34,20 @@
 | [DOCUMENT_STANDARDS.md](DOCUMENT_STANDARDS.md) | 文档编写与维护规范 |
 | [GITLAB_FLOW.md](GITLAB_FLOW.md) | GitLab Flow 分支、发版、tag 和临时 worktree 生命周期规范 |
 | [SKILL-REPOSITORY.md](SKILL-REPOSITORY.md) | 受治理 skill repository 和安装安全策略 |
-| [VIBE-TEMPLATES.md](VIBE-TEMPLATES.md) | 可复制的 Vibe Coding 提示词模板 |
-| [LEADERSHIP-PRESETS.md](LEADERSHIP-PRESETS.md) | CEO、CTO、PM、Architect 等内置领导者角色预设 |
-
-## 架构与参考
-
-| 文档 | 说明 |
+| [VIBE-TEMPLATES.md](VIBE-TEMPLATES.md) | 可复制的 Vibe Coding 提示词模板 |
+| [LEADERSHIP-PRESETS.md](LEADERSHIP-PRESETS.md) | CEO、CTO、PM、Architect 等内置领导者角色预设 |
+
+## 当前规划与执行蓝图
+
+这些文档描述计划中的架构演进，不代表当前 CLI 已全部实现。进入实现前应按文档中的验收标准和红线逐项拆分任务。
+
+| 文档 | 说明 |
+| --- | --- |
+| [plans/2026-05-20-scale-engine-v2-final-architecture-plan.md](plans/2026-05-20-scale-engine-v2-final-architecture-plan.md) | SCALE Engine V2.0 最终架构落地方案：Prompt Cache、Dashboard 聚合、Background Hunter、供应链门禁、动态/视觉验证和 Evolution Shadow Mode |
+
+## 架构与参考
+
+| 文档 | 说明 |
 | --- | --- |
 | [00-OVERVIEW.md](00-OVERVIEW.md) | 系统概览 |
 | [01-ARCHITECTURE.md](01-ARCHITECTURE.md) | 架构设计 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "type": "module",
   "bin": {
@@ -19,18 +19,22 @@
     "docs/README.md",
     "docs/CODE_INTELLIGENCE.md",
     "docs/CONTEXT_BUDGET.md",
+    "docs/BACKGROUND_HUNTER.md",
+    "docs/DEPENDENCY_AUDIT.md",
+    "docs/ACTIVE_SECURITY_VISUAL_GATES.md",
+    "docs/EVOLUTION_SHADOW_MODE.md",
     "docs/WORKFLOW_EVAL.md",
     "docs/SKILL_RADAR.md",
     "docs/MEMORY_BRAIN.md",
     "docs/GOVERNANCE_DASHBOARD.md",
-    "docs/GITLAB_FLOW.md",
-    "docs/MEMORY_FABRIC.md",
-    "docs/RUNTIME_EVIDENCE.md",
-    "docs/RESOURCE_GOVERNANCE.md",
-    "docs/start",
-    "image",
-    "examples/demo-projects/agent-governance-demo"
-  ],
+    "docs/GITLAB_FLOW.md",
+    "docs/MEMORY_FABRIC.md",
+    "docs/RUNTIME_EVIDENCE.md",
+    "docs/RESOURCE_GOVERNANCE.md",
+    "docs/start",
+    "image",
+    "examples/demo-projects/agent-governance-demo"
+  ],
   "publishConfig": {
     "access": "public"
   },