@hongmaple0820/scale-engine 0.25.0 → 0.26.0

package/docs/CONTEXT_BUDGET.md

@@ -1,113 +1,113 @@
-# Context Budget And Progressive Governance
-
-Status: implemented baseline
-Since: v0.20 development branch
-
-This feature keeps SCALE from becoming its own context pollution source. It separates always-loaded rules from on-demand documents, runtime evidence, historical archives, and generated artifacts.
-
-## Commands
-
-Report token cost by context category:
-
-```bash
-scale context budget --json
-```
-
-Include provider-specific prompt cache policy:
-
-```bash
-scale context budget --provider anthropic --json
-scale context budget --provider openai --json
-```
-
-Write the report to `.scale/context-budget.json`:
-
-```bash
-scale context budget --write
-```
-
-Check thresholds:
-
-```bash
-scale context doctor --max-always 2500 --max-task 8000
-```
-
-Build a lazy-loaded task context pack:
-
-```bash
-scale context pack \
-  --task "Review frontend route with browser evidence" \
-  --level L \
-  --files src/routes/upload.tsx \
-  --budget 4000 \
-  --json
-```
-
-Evaluate progressive governance mode:
-
-```bash
-scale governance mode \
-  --task "Change auth permissions and database migration" \
-  --files src/auth/user.ts,migrations/001.sql \
-  --requested-mode minimal \
-  --json
-```
-
-Report governance benefit and overhead:
-
-```bash
-scale governance roi \
-  --task-id TASK-123 \
-  --task "Review frontend route with browser evidence" \
-  --files src/routes/upload.tsx \
-  --json
-```
-
-## Categories
-
-| Category | Meaning | Loading Policy |
-| --- | --- | --- |
-| `always` | Tiny entrypoint rules and source-of-truth governance config | Keep under strict token budget |
-| `on-demand` | Domain docs and governance guides | Load only when task trigger matches |
-| `evidence` | Runtime evidence and task artifacts | Summarize and reference by path |
-| `archive` | Historical plans and old roadmap context | Do not load unless explicitly requested |
-| `generated` | HTML reports, screenshots, graph outputs, generated artifacts | Keep manifest-only by default |
-
-## Prompt Cache Policy
-
-V2.0 adds a cache policy layer for stable context. The policy is intentionally conservative:
-
-- `always` is cache-eligible by default because it contains stable entrypoint rules and governance source-of-truth config.
-- `on-demand` is not cache-eligible by default because it changes with task intent and can break stable prefix reuse.
-- `evidence`, `archive`, and `generated` are never cache-eligible by default.
-- Unsupported providers still write usage evidence; they do not pretend to support prompt caching.
-
-Provider behavior:
-
-| Provider | Strategy | Usage fields |
-| --- | --- | --- |
-| Anthropic | `anthropic-ephemeral` | `cache_creation_input_tokens`, `cache_read_input_tokens` |
-| OpenAI | `openai-automatic` | `prompt_tokens_details.cached_tokens` |
-| Other | `usage-ledger-only` | normal input/output usage only |
-
-The cache policy does not live in `ModelRouter`. `ModelRouter` selects a model; provider request builders or adapters apply provider-specific cache controls.
-
-## Progressive Governance
-
-SCALE now has a baseline risk classifier. It keeps low-risk documentation work in `minimal` mode and escalates risky tasks to `standard`, `expanded`, or `critical`.
-
-Examples:
-
-| Signal | Mode |
-| --- | --- |
-| README typo | `minimal` |
-| normal implementation task | `standard` |
-| UI, browser, E2E, public interface, or cross-module work | `expanded` |
-| auth, permission, secret, database, migration, production config, release, or destructive operation | `critical` |
-
-This is not a replacement for verification. It only decides which governance behavior should activate.
-
-## Governance ROI
-
-`scale governance roi` reports both benefit and overhead. Early ROI is estimated from context budget and risk signals. Later versions should replace estimates with measured eval data such as file reads saved, tool calls saved, fix iterations reduced, and human corrections avoided.
-
+# Context Budget And Progressive Governance
+
+Status: implemented baseline
+Since: v0.20 development branch
+
+This feature keeps SCALE from becoming its own context pollution source. It separates always-loaded rules from on-demand documents, runtime evidence, historical archives, and generated artifacts.
+
+## Commands
+
+Report token cost by context category:
+
+```bash
+scale context budget --json
+```
+
+Include provider-specific prompt cache policy:
+
+```bash
+scale context budget --provider anthropic --json
+scale context budget --provider openai --json
+```
+
+Write the report to `.scale/context-budget.json`:
+
+```bash
+scale context budget --write
+```
+
+Check thresholds:
+
+```bash
+scale context doctor --max-always 2500 --max-task 8000
+```
+
+Build a lazy-loaded task context pack:
+
+```bash
+scale context pack \
+  --task "Review frontend route with browser evidence" \
+  --level L \
+  --files src/routes/upload.tsx \
+  --budget 4000 \
+  --json
+```
+
+Evaluate progressive governance mode:
+
+```bash
+scale governance mode \
+  --task "Change auth permissions and database migration" \
+  --files src/auth/user.ts,migrations/001.sql \
+  --requested-mode minimal \
+  --json
+```
+
+Report governance benefit and overhead:
+
+```bash
+scale governance roi \
+  --task-id TASK-123 \
+  --task "Review frontend route with browser evidence" \
+  --files src/routes/upload.tsx \
+  --json
+```
+
+## Categories
+
+| Category | Meaning | Loading Policy |
+| --- | --- | --- |
+| `always` | Tiny entrypoint rules and source-of-truth governance config | Keep under strict token budget |
+| `on-demand` | Domain docs and governance guides | Load only when task trigger matches |
+| `evidence` | Runtime evidence and task artifacts | Summarize and reference by path |
+| `archive` | Historical plans and old roadmap context | Do not load unless explicitly requested |
+| `generated` | HTML reports, screenshots, graph outputs, generated artifacts | Keep manifest-only by default |
+
+## Prompt Cache Policy
+
+V2.0 adds a cache policy layer for stable context. The policy is intentionally conservative:
+
+- `always` is cache-eligible by default because it contains stable entrypoint rules and governance source-of-truth config.
+- `on-demand` is not cache-eligible by default because it changes with task intent and can break stable prefix reuse.
+- `evidence`, `archive`, and `generated` are never cache-eligible by default.
+- Unsupported providers still write usage evidence; they do not pretend to support prompt caching.
+
+Provider behavior:
+
+| Provider | Strategy | Usage fields |
+| --- | --- | --- |
+| Anthropic | `anthropic-ephemeral` | `cache_creation_input_tokens`, `cache_read_input_tokens` |
+| OpenAI | `openai-automatic` | `prompt_tokens_details.cached_tokens` |
+| Other | `usage-ledger-only` | normal input/output usage only |
+
+The cache policy does not live in `ModelRouter`. `ModelRouter` selects a model; provider request builders or adapters apply provider-specific cache controls.
+
+## Progressive Governance
+
+SCALE now has a baseline risk classifier. It keeps low-risk documentation work in `minimal` mode and escalates risky tasks to `standard`, `expanded`, or `critical`.
+
+Examples:
+
+| Signal | Mode |
+| --- | --- |
+| README typo | `minimal` |
+| normal implementation task | `standard` |
+| UI, browser, E2E, public interface, or cross-module work | `expanded` |
+| auth, permission, secret, database, migration, production config, release, or destructive operation | `critical` |
+
+This is not a replacement for verification. It only decides which governance behavior should activate.
+
+## Governance ROI
+
+`scale governance roi` reports both benefit and overhead. Early ROI is estimated from context budget and risk signals. Later versions should replace estimates with measured eval data such as file reads saved, tool calls saved, fix iterations reduced, and human corrections avoided.
+

package/docs/DEPENDENCY_AUDIT.md

@@ -1,89 +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.
+# 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

@@ -1,63 +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.
+# 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.