@hongmaple0820/scale-engine 0.25.0 → 0.26.0

package/docs/ACTIVE_SECURITY_VISUAL_GATES.md

@@ -1,87 +1,87 @@
-# Active Security And Visual Gates
-
-SCALE V2 adds two optional verification layers for projects that can provide a runnable local target:
-
-- `ActiveRedTeam`: bounded dynamic security probes for configured HTTP targets.
-- `VisualGate`: structured visual review evidence for UI routes and UI specs.
-
-Both are conditional. A library or backend project with no runtime target should not pay the cost.
-
-## Active Security
-
-Active security is configured under `.scale/verification.json`:
-
-```json
-{
-  "security": {
-    "active": {
-      "enabled": true,
-      "baseUrl": "http://localhost:3000",
-      "startCommand": "npm run dev",
-      "targets": ["/api/login", "/api/users"],
-      "timeoutMs": 5000,
-      "maxRequests": 20
-    }
-  }
-}
-```
-
-Behavior:
-
-- missing or disabled config returns `SKIPPED`
-- invalid enabled config returns `FAILED` before sending probes
-- probes are capped by `maxRequests`
-- every request has a timeout
-- reflected probe payloads are `HIGH` findings and block
-- request errors and server errors are recorded as findings, but only configured blocker severity should fail the gate
-
-The first implementation exposes `runActiveRedTeam()` as a library API. It does not start a server by itself yet. CLI orchestration can wire `startCommand` later, but startup failure must become a `FAILED` result when that runner is added.
-
-## Visual Gate
-
-Visual verification is configured under `.scale/verification.json`:
-
-```json
-{
-  "visual": {
-    "enabled": true,
-    "baseUrl": "http://localhost:5173",
-    "specPath": "docs/ui/UI-SPEC.md",
-    "routes": ["/", "/settings"],
-    "reportPath": "docs/worklog/tasks/TASK-123/visual-report.json",
-    "blockingSeverities": ["critical", "high"]
-  }
-}
-```
-
-`VisualGate` consumes a structured report:
-
-```json
-{
-  "screenshots": [
-    { "route": "/", "path": "screenshots/home.png" }
-  ],
-  "findings": [
-    {
-      "severity": "high",
-      "route": "/",
-      "message": "Primary action overlaps the navigation bar.",
-      "evidence": "overlap ratio 0.42"
-    }
-  ]
-}
-```
-
-Behavior:
-
-- missing or disabled config passes with a `Visual gate skipped` evidence item
-- enabled config requires `baseUrl`, `specPath`, `routes`, and `reportPath`
-- missing or invalid visual report fails
-- default blockers are `critical` and `high`
-- VLM comments may be recorded in the report, but the gate blocks only on structured severity thresholds
-
-## Gate Numbering
-
-`VisualGate` uses `G9` when explicitly registered. It is not registered by default because meta governance also uses the G9-G15 range. Projects should register it only in UI verification profiles or dedicated task flows.
-
-Active security remains a security sub-check instead of a fractional gate number. It belongs under the broader G7 security lifecycle when wired into a concrete workflow.
+# Active Security And Visual Gates
+
+SCALE V2 adds two optional verification layers for projects that can provide a runnable local target:
+
+- `ActiveRedTeam`: bounded dynamic security probes for configured HTTP targets.
+- `VisualGate`: structured visual review evidence for UI routes and UI specs.
+
+Both are conditional. A library or backend project with no runtime target should not pay the cost.
+
+## Active Security
+
+Active security is configured under `.scale/verification.json`:
+
+```json
+{
+  "security": {
+    "active": {
+      "enabled": true,
+      "baseUrl": "http://localhost:3000",
+      "startCommand": "npm run dev",
+      "targets": ["/api/login", "/api/users"],
+      "timeoutMs": 5000,
+      "maxRequests": 20
+    }
+  }
+}
+```
+
+Behavior:
+
+- missing or disabled config returns `SKIPPED`
+- invalid enabled config returns `FAILED` before sending probes
+- probes are capped by `maxRequests`
+- every request has a timeout
+- reflected probe payloads are `HIGH` findings and block
+- request errors and server errors are recorded as findings, but only configured blocker severity should fail the gate
+
+The first implementation exposes `runActiveRedTeam()` as a library API. It does not start a server by itself yet. CLI orchestration can wire `startCommand` later, but startup failure must become a `FAILED` result when that runner is added.
+
+## Visual Gate
+
+Visual verification is configured under `.scale/verification.json`:
+
+```json
+{
+  "visual": {
+    "enabled": true,
+    "baseUrl": "http://localhost:5173",
+    "specPath": "docs/ui/UI-SPEC.md",
+    "routes": ["/", "/settings"],
+    "reportPath": "docs/worklog/tasks/TASK-123/visual-report.json",
+    "blockingSeverities": ["critical", "high"]
+  }
+}
+```
+
+`VisualGate` consumes a structured report:
+
+```json
+{
+  "screenshots": [
+    { "route": "/", "path": "screenshots/home.png" }
+  ],
+  "findings": [
+    {
+      "severity": "high",
+      "route": "/",
+      "message": "Primary action overlaps the navigation bar.",
+      "evidence": "overlap ratio 0.42"
+    }
+  ]
+}
+```
+
+Behavior:
+
+- missing or disabled config passes with a `Visual gate skipped` evidence item
+- enabled config requires `baseUrl`, `specPath`, `routes`, and `reportPath`
+- missing or invalid visual report fails
+- default blockers are `critical` and `high`
+- VLM comments may be recorded in the report, but the gate blocks only on structured severity thresholds
+
+## Gate Numbering
+
+`VisualGate` uses `G9` when explicitly registered. It is not registered by default because meta governance also uses the G9-G15 range. Projects should register it only in UI verification profiles or dedicated task flows.
+
+Active security remains a security sub-check instead of a fractional gate number. It belongs under the broader G7 security lifecycle when wired into a concrete workflow.

package/docs/BACKGROUND_HUNTER.md

@@ -1,62 +1,62 @@
-# Background Hunter
-
-Background Hunter is the readonly proactive scan layer for SCALE Engine V2.
-It turns existing governance signals into an actionable hunt queue without editing application code.
-
-## Boundary
-
-Default behavior is intentionally conservative:
-
-- scan only, no automatic code changes
-- no automatic LLM repair
-- no automatic commit or pull request
-- no release bypass
-- ignore decisions are explicit and written to `.scale/hunt/ignored-findings.json`
-
-The hunter reuses existing checks instead of creating a second rule system. The first implementation consumes:
-
-- `EngineeringStandards`
-- `ReviewAnalyzer` when status and diff input are provided by callers
-
-## Commands
-
-```bash
-scale hunt scan
-scale hunt scan --json
-scale hunt report
-scale hunt diagnose <finding-id>
-scale hunt ignore <finding-id> --reason "Accepted legacy debt tracked elsewhere"
-```
-
-`hunt scan` and `hunt report` do not modify source files. They classify findings as `open` or `ignored`.
-
-`hunt diagnose <finding-id>` creates a normal `DiagnosticLoop` from the finding. This keeps the debugging workflow evidence-first:
-
-- reproducible command
-- expected failure
-- changed files
-- verification commands
-- hypotheses and cleanup checklist
-
-`hunt ignore` records the finding id and stable fingerprint. The same finding will remain visible in the report as `ignored`, but it is removed from the open queue.
-
-## Finding Identity
-
-Every finding gets:
-
-- `id`: short deterministic SHA-256 id derived from the fingerprint
-- `fingerprint`: stable source/rule/path/line/message tuple
-- `source`: currently `engineering-standards` or `review-analyzer`
-- `diagnosticInput`: ready-to-use `DiagnosticLoopInput`
-
-This allows repeated scans to avoid noisy duplicates and lets teams explicitly accept or defer known debt.
-
-## Recommended Flow
-
-1. Run `scale hunt scan --json`.
-2. Triage open findings.
-3. For real issues, run `scale hunt diagnose <finding-id> --json`.
-4. Fix through the normal plan/TDD/verify workflow.
-5. For accepted legacy debt, run `scale hunt ignore <finding-id> --reason "..."`
-
-Do not promote Background Hunter to automatic repair until the project has enough evidence that its findings are stable and low-noise.
+# Background Hunter
+
+Background Hunter is the readonly proactive scan layer for SCALE Engine V2.
+It turns existing governance signals into an actionable hunt queue without editing application code.
+
+## Boundary
+
+Default behavior is intentionally conservative:
+
+- scan only, no automatic code changes
+- no automatic LLM repair
+- no automatic commit or pull request
+- no release bypass
+- ignore decisions are explicit and written to `.scale/hunt/ignored-findings.json`
+
+The hunter reuses existing checks instead of creating a second rule system. The first implementation consumes:
+
+- `EngineeringStandards`
+- `ReviewAnalyzer` when status and diff input are provided by callers
+
+## Commands
+
+```bash
+scale hunt scan
+scale hunt scan --json
+scale hunt report
+scale hunt diagnose <finding-id>
+scale hunt ignore <finding-id> --reason "Accepted legacy debt tracked elsewhere"
+```
+
+`hunt scan` and `hunt report` do not modify source files. They classify findings as `open` or `ignored`.
+
+`hunt diagnose <finding-id>` creates a normal `DiagnosticLoop` from the finding. This keeps the debugging workflow evidence-first:
+
+- reproducible command
+- expected failure
+- changed files
+- verification commands
+- hypotheses and cleanup checklist
+
+`hunt ignore` records the finding id and stable fingerprint. The same finding will remain visible in the report as `ignored`, but it is removed from the open queue.
+
+## Finding Identity
+
+Every finding gets:
+
+- `id`: short deterministic SHA-256 id derived from the fingerprint
+- `fingerprint`: stable source/rule/path/line/message tuple
+- `source`: currently `engineering-standards` or `review-analyzer`
+- `diagnosticInput`: ready-to-use `DiagnosticLoopInput`
+
+This allows repeated scans to avoid noisy duplicates and lets teams explicitly accept or defer known debt.
+
+## Recommended Flow
+
+1. Run `scale hunt scan --json`.
+2. Triage open findings.
+3. For real issues, run `scale hunt diagnose <finding-id> --json`.
+4. Fix through the normal plan/TDD/verify workflow.
+5. For accepted legacy debt, run `scale hunt ignore <finding-id> --reason "..."`
+
+Do not promote Background Hunter to automatic repair until the project has enough evidence that its findings are stable and low-noise.

package/docs/CODE_INTELLIGENCE.md

@@ -1,138 +1,138 @@
-# Code Intelligence
-
-SCALE uses an adapter-first code intelligence layer. It can consume external code graph tools when they exist, read graph artifacts such as Graphify outputs, and fall back to a scoped internal source scan when no provider is available.
-
-The goal is not to replace IDE indexing. The goal is to make exploration measurable:
-
-- which provider answered the query
-- whether fallback was used
-- which files are likely relevant
-- how many file reads were avoided
-- what confidence the result has
-
-## Quick Start
-
-Create the optional provider configuration:
-
-```bash
-scale codegraph init
-```
-
-Inspect provider availability:
-
-```bash
-scale codegraph status
-scale codegraph status --json
-```
-
-Query code intelligence:
-
-```bash
-scale codegraph query "UserService.create"
-scale codegraph impact --symbol UserService.create
-scale codegraph context --symbol UserService.create --budget 2000
-scale codegraph roi --symbol UserService.create
-```
-
-## Configuration
-
-The configuration file lives at:
-
-```text
-.scale/code-intelligence.json
-```
-
-Default shape:
-
-```json
-{
-  "version": "1.0",
-  "providers": [
-    {
-      "id": "codegraph",
-      "type": "external-cli",
-      "enabled": true,
-      "command": "codegraph",
-      "capabilities": ["symbols", "callers", "callees", "impact", "context"]
-    },
-    {
-      "id": "graphify",
-      "type": "artifact",
-      "enabled": true,
-      "manifest": "graphify-out/GRAPH_REPORT.md",
-      "capabilities": ["summary", "module-map", "context"]
-    }
-  ],
-  "fallback": {
-    "enabled": true,
-    "tools": ["internal-scan", "rg", "read"]
-  }
-}
-```
-
-## Provider Types
-
-| Type | Use |
-| --- | --- |
-| `external-cli` | Detects an installed external code graph command. SCALE does not auto-install it. The first version treats this as availability evidence until a stable command contract is configured. |
-| `artifact` | Reads a local graph manifest or report file. JSON manifests can provide symbol impact data. |
-| fallback | Uses a bounded internal source scan when providers are unavailable or return no hits. |
-
-## JSON Artifact Provider
-
-Artifact providers can point at a JSON manifest:
-
-```json
-{
-  "symbols": [
-    {
-      "name": "UserService.create",
-      "file": "src/user.ts",
-      "callers": ["src/api.ts"],
-      "callees": ["src/db.ts"]
-    }
-  ],
-  "files": [
-    {
-      "path": "src/user.ts",
-      "symbols": ["UserService.create"]
-    }
-  ]
-}
-```
-
-This allows SCALE to answer impact queries without reading the whole repository.
-
-## ROI Metrics
-
-Code intelligence reports include:
-
-| Metric | Meaning |
-| --- | --- |
-| `graphHits` | Number of hits from graph providers. |
-| `fallbackCount` | Whether fallback was needed. |
-| `baselineFileReads` | Estimated broad exploration file reads. |
-| `recommendedFileReads` | Scoped file reads recommended by the query result. |
-| `fileReadsSaved` | Estimated avoided reads. |
-| `toolCallsSaved` | Estimated avoided exploration tool calls. |
-
-These numbers are deliberately conservative. They are a local signal for whether graph-assisted exploration is worth keeping default for a task class.
-
-## Governance ROI
-
-`scale governance roi` can include code intelligence:
-
-```bash
-scale governance roi --symbol UserService.create
-scale governance roi --code-query createUser
-```
-
-When a graph provider answers, the module is reported as measured evidence. When fallback is used, the module is reported as estimated and needs more evidence before becoming a stronger default.
-
-## Policy
-
-- SCALE must run when no code graph provider is installed.
-- Missing providers must produce explicit fallback, not silent success.
-- External tools are detected but not installed automatically.
-- Source files are read only through a bounded fallback scan.
-- Large generated graph outputs should stay outside default prompt context; use summaries and file paths.
+# Code Intelligence
+
+SCALE uses an adapter-first code intelligence layer. It can consume external code graph tools when they exist, read graph artifacts such as Graphify outputs, and fall back to a scoped internal source scan when no provider is available.
+
+The goal is not to replace IDE indexing. The goal is to make exploration measurable:
+
+- which provider answered the query
+- whether fallback was used
+- which files are likely relevant
+- how many file reads were avoided
+- what confidence the result has
+
+## Quick Start
+
+Create the optional provider configuration:
+
+```bash
+scale codegraph init
+```
+
+Inspect provider availability:
+
+```bash
+scale codegraph status
+scale codegraph status --json
+```
+
+Query code intelligence:
+
+```bash
+scale codegraph query "UserService.create"
+scale codegraph impact --symbol UserService.create
+scale codegraph context --symbol UserService.create --budget 2000
+scale codegraph roi --symbol UserService.create
+```
+
+## Configuration
+
+The configuration file lives at:
+
+```text
+.scale/code-intelligence.json
+```
+
+Default shape:
+
+```json
+{
+  "version": "1.0",
+  "providers": [
+    {
+      "id": "codegraph",
+      "type": "external-cli",
+      "enabled": true,
+      "command": "codegraph",
+      "capabilities": ["symbols", "callers", "callees", "impact", "context"]
+    },
+    {
+      "id": "graphify",
+      "type": "artifact",
+      "enabled": true,
+      "manifest": "graphify-out/GRAPH_REPORT.md",
+      "capabilities": ["summary", "module-map", "context"]
+    }
+  ],
+  "fallback": {
+    "enabled": true,
+    "tools": ["internal-scan", "rg", "read"]
+  }
+}
+```
+
+## Provider Types
+
+| Type | Use |
+| --- | --- |
+| `external-cli` | Detects an installed external code graph command. SCALE does not auto-install it. The first version treats this as availability evidence until a stable command contract is configured. |
+| `artifact` | Reads a local graph manifest or report file. JSON manifests can provide symbol impact data. |
+| fallback | Uses a bounded internal source scan when providers are unavailable or return no hits. |
+
+## JSON Artifact Provider
+
+Artifact providers can point at a JSON manifest:
+
+```json
+{
+  "symbols": [
+    {
+      "name": "UserService.create",
+      "file": "src/user.ts",
+      "callers": ["src/api.ts"],
+      "callees": ["src/db.ts"]
+    }
+  ],
+  "files": [
+    {
+      "path": "src/user.ts",
+      "symbols": ["UserService.create"]
+    }
+  ]
+}
+```
+
+This allows SCALE to answer impact queries without reading the whole repository.
+
+## ROI Metrics
+
+Code intelligence reports include:
+
+| Metric | Meaning |
+| --- | --- |
+| `graphHits` | Number of hits from graph providers. |
+| `fallbackCount` | Whether fallback was needed. |
+| `baselineFileReads` | Estimated broad exploration file reads. |
+| `recommendedFileReads` | Scoped file reads recommended by the query result. |
+| `fileReadsSaved` | Estimated avoided reads. |
+| `toolCallsSaved` | Estimated avoided exploration tool calls. |
+
+These numbers are deliberately conservative. They are a local signal for whether graph-assisted exploration is worth keeping default for a task class.
+
+## Governance ROI
+
+`scale governance roi` can include code intelligence:
+
+```bash
+scale governance roi --symbol UserService.create
+scale governance roi --code-query createUser
+```
+
+When a graph provider answers, the module is reported as measured evidence. When fallback is used, the module is reported as estimated and needs more evidence before becoming a stronger default.
+
+## Policy
+
+- SCALE must run when no code graph provider is installed.
+- Missing providers must produce explicit fallback, not silent success.
+- External tools are detected but not installed automatically.
+- Source files are read only through a bounded fallback scan.
+- Large generated graph outputs should stay outside default prompt context; use summaries and file paths.