@hongmaple0820/scale-engine 0.40.2 → 0.44.0

package/docs/CODE_INTELLIGENCE.md

@@ -1,180 +0,0 @@
-# Code Intelligence
-
-SCALE uses an adapter-first code intelligence layer. It can consume the upstream [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) CLI when it is installed and the project has a local `.codegraph/` index, 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
-
-Optional upstream install:
-
-```bash
-npx @colbymchenry/codegraph
-# or
-npm i -g @colbymchenry/codegraph
-codegraph init -i
-```
-
-Governed SCALE setup:
-
-```bash
-scale setup --pack knowledge
-scale codegraph status --json
-```
-
-For Graphify, prefer isolated tool installation:
-
-```bash
-uv tool install graphify
-graphify install --platform codex
-graphify query "auth service" --graph graphify-out/graph.json
-```
-
-Run a real large-project rehearsal before treating Graphify as an operational knowledge provider:
-
-```bash
-npm run smoke:graphify -- --large-project /path/to/large-project
-node scripts/workflow/provider-rehearsal.mjs --skip-gbrain --require-graphify --large-project /path/to/large-project
-```
-
-The rehearsal executes `graphify update <project> --no-cluster` by default so graph generation stays AST/Python based and does not call a model. It locates the generated `graph.json`, parses graph stats, and runs `graphify query`. Use `--semantic-extract` only when semantic LLM extraction is explicitly allowed. Do not commit generated `graphify-out/` artifacts by default; commit only reviewed knowledge summaries, docs, or rules derived from the graph.
-
-Create the optional provider configuration:
-
-```bash
-scale codegraph init
-```
-
-Inspect provider availability:
-
-```bash
-scale codegraph status
-scale codegraph status --json
-scale tool doctor --tools codegraph,graphify --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", "summary", "module-map"],
-      "source": "https://github.com/colbymchenry/codegraph",
-      "installHint": "npx @colbymchenry/codegraph or npm i -g @colbymchenry/codegraph",
-      "projectInitHint": "codegraph init -i",
-      "serveCommand": "codegraph serve --mcp"
-    },
-    {
-      "id": "graphify",
-      "type": "artifact",
-      "enabled": true,
-      "manifest": "graphify-out/graph.json",
-      "capabilities": ["symbols", "callers", "callees", "impact", "context", "summary", "module-map"],
-      "source": "https://github.com/safishamsi/graphify",
-      "installHint": "uv tool install graphify && graphify install --platform codex"
-    }
-  ],
-  "fallback": {
-    "enabled": true,
-    "tools": ["internal-scan", "rg", "read"]
-  }
-}
-```
-
-## Provider Types
-
-| Type | Use |
-| --- | --- |
-| `external-cli` | Detects an installed external code graph command. For `codegraph`, SCALE consumes the official JSON output from `codegraph query --json` and `codegraph context --format json` when `.codegraph/` exists. |
-| `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 installed only through explicit user intent such as `scale setup --pack knowledge --yes` or `scale bootstrap deps --pack knowledge --apply`.
-- When CodeGraph is installed and the project is initialized, SCALE should prefer the upstream JSON query/context surfaces before falling back to raw file scans.
-- Graphify is treated as an artifact provider. CLI installation is not enough; `graphify-out/graph.json` must exist before graph-backed knowledge recall can use it.
-- 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.

package/docs/CONTEXT_BUDGET.md

@@ -1,165 +0,0 @@
-# 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 1500 --max-task 4000
-```
-
-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
-```
-
-Build the unified AI OS runtime plan that embeds the context pack with memory, skill routing, evaluator intelligence, tool strategy, adaptive workflow, and ROI:
-
-```bash
-scale ai-os plan \
-  --task-id TASK-123 \
-  --task "Review frontend route with browser evidence" \
-  --level L \
-  --files src/routes/upload.tsx \
-  --budget 4000 \
-  --json
-```
-
-The context pack now uses the baseline Context Compiler. Each candidate section is scored by category, task/file relevance, risk level, and budget fit. The JSON output includes compiler metadata so callers can explain why a section was loaded or omitted:
-
-```json
-{
-  "compiler": {
-    "strategy": "relevance-budget-v1",
-    "budget": 4000,
-    "totalCandidateTokens": 6200,
-    "estimatedTokenSavings": 2200,
-    "ranking": [
-      {
-        "id": "runtime-evidence",
-        "included": true,
-        "score": 292,
-        "matchedSignals": ["evidence", "high-risk-evidence"],
-        "reason": "Evidence is needed for completion and verification claims."
-      }
-    ]
-  }
-}
-```
-
-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.
-
-To replace estimates with real usage evidence, write provider usage into the ledger and audit it directly:
-
-```bash
-scale token record \
-  --provider anthropic \
-  --usage-json '{"usage":{"input_tokens":1000,"output_tokens":200,"cache_read_input_tokens":500}}'
-
-scale token report --day 2026-05-23 --json
-```
-
-## 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. In v0.27.0, `scale ai-os plan` also attaches ROI modules for:
-
-- `context-budget`
-- `context-compiler`
-- `memory-provider-runtime`
-- `skill-routing-engine`
-- `progressive-governance`
-
-Early ROI is still estimated from context budget, compiler savings, recall count, skill evidence steps, 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,118 +0,0 @@
-# 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.
-
-## Verification Command Safety
-
-SCALE verification commands are security-sensitive because they are often run in CI.
-The core verification paths (`verify-task`, phase verification, workflow eval attempts, and gate commands) execute configured commands without shell expansion by default.
-
-Allowed by default:
-
-```bash
-npm run build
-npm test -- --runInBand
-node scripts/check.js --changed
-```
-
-Blocked by default:
-
-```bash
-npm test && curl https://example.com
-node scripts/check.js | tee out.txt
-```
-
-Shell metacharacters such as `&&`, `|`, `;`, `<`, `>`, backticks, and unquoted `$` are rejected before execution. Use package scripts or checked-in helper scripts for composed commands. `SCALE_ALLOW_SHELL_COMMANDS=1` re-enables shell execution only for trusted local runs and must not be enabled for untrusted PR or user-controlled CI inputs.
-
-## 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
-- built-in ownership/provenance watchlist matches
-- dynamic code execution: `eval`, `new Function`
-- shell execution patterns
-- suspicious network access patterns
-
-The built-in ownership/provenance watchlist currently blocks exact versions that were flagged by external package behavior analysis:
-
-- `content-type@2.0.0`
-- `type-is@2.1.0`
-- `type-js@2.1.0` (kept as a defensive alias for reports that use this package name)
-
-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 +0,0 @@
-# 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/GITLAB_FLOW.md

@@ -1,125 +0,0 @@
-# GitLab Flow Branch and Worktree Policy
-
-SCALE Engine uses a GitLab Flow variant for this repository:
-
-```text
-feat/* / fix/* / chore/* / docs/* / codex/*
-        -> dev
-        -> master
-        -> vX.Y.Z tag
-        -> npm publish
-
-hotfix:
-        fix forward on dev first when possible
-        -> cherry-pick to hotfix/*
-        -> master
-        -> vX.Y.Z tag
-        -> sync master back to dev
-
-selective release, only when dev contains work that must not ship:
-        master
-        -> release/vX.Y.Z
-        -> cherry-pick selected commits
-        -> master
-        -> vX.Y.Z tag
-        -> sync master back to dev
-```
-
-## Branch Roles
-
-| Branch | Role | Rule |
-| --- | --- | --- |
-| `dev` | Integration and test branch | Merge reviewed short branches here. Do not create direct governed commits on `dev`. |
-| `master` | Production branch | Only verified release/hotfix results land here. Publish from user-created `vX.Y.Z` tags on `master`. |
-| `feat/*`, `feature/*` | Feature branches | Start from current `dev`, merge back to `dev`, then delete. |
-| `fix/*` | Normal bug fix branches | Start from current `dev`, merge back to `dev`, then delete. |
-| `chore/*`, `docs/*`, `codex/*` | Maintenance branches | Short-lived work branches that merge back to `dev`. |
-| `hotfix/*` | Production patch branches | Use only for production fixes. Fix forward to `dev` first when possible, then cherry-pick to hotfix/master. |
-| `release/*` | Selective release branch | Use only when `dev` contains work that must not ship. Start from `master` and cherry-pick the release list. |
-
-## Required Checks
-
-Run the release-grade verification set before merging to `master` or tagging:
-
-```bash
-npm run build
-npx vitest run
-git diff --check
-npm pack --dry-run
-```
-
-Every merge request should run the relevant build/lint/test checks before review is accepted. Do not wait until `master` to discover broken tests.
-
-## Merge and Conflict Rules
-
-- Public branches are not rebased: `dev`, `master`, `release/*`, and `hotfix/*` keep realistic history.
-- Personal short branches may be rebased before merge, but only with `--force-with-lease` and only before review is accepted.
-- Prefer squash merge from short branches into `dev` when one logical change should be easy to revert.
-- Resolve conflicts on the source branch, rerun verification, then merge. Do not resolve release conflicts directly on `master`.
-- Fix bugs forward first: land the fix on `dev` when possible, then cherry-pick the same commit to `hotfix/*` or the selected patch release branch.
-- Commit messages should explain intent and why the chosen path was selected when the decision is not obvious.
-
-## Ship Gate Rules
-
-`scale ship <task-id>` now enforces the branch lifecycle:
-
-- blocked on `dev`, `master`, `main`, and detached HEAD
-- allowed on configured short branches such as `feat/*`, `fix/*`, `chore/*`, `docs/*`, `codex/*`, `release/*`, and `hotfix/*`
-- still requires verification evidence, passing review evidence, and reviewed-file-only staging
-- still blocks dirty or unsafe child repositories in MOE/submodule workspaces
-
-Use:
-
-```bash
-scale workspace status --summary
-scale workspace finish --summary
-scale workspace finish --json
-```
-
-The report includes branch role, whether governed shipping is allowed, and cleanup blockers.
-
-## Worktree Lifecycle
-
-Temporary agent worktrees are safe to remove only when all of these are true:
-
-- root worktree is clean
-- child repositories are clean and pushed when required
-- the temporary branch has no unpushed commits
-- a branch with no upstream is already merged into `dev`/`master`, or it contains no unique work
-
-Cleanup remains dry-run by default:
-
-```bash
-scale workspace cleanup --dir <temporary-worktree> --dry-run --json
-scale workspace cleanup --dir <temporary-worktree> --apply --confirm <branch-or-head> --json
-```
-
-If cleanup is blocked, push the branch, merge it, cherry-pick it into the selected release, or explicitly discard it before removing the worktree.
-
-## Repository Bootstrap
-
-This repository currently treats `dev` as the integration branch and `master` as production. If `dev` falls behind `master` and has no unique commits, fast-forward `dev` to `master` before starting new feature work:
-
-```bash
-git fetch --all --prune
-git switch dev
-git merge --ff-only master
-git push origin dev
-git push github dev
-```
-
-After that, normal work should start from `dev`:
-
-```bash
-git switch dev
-git pull --ff-only origin dev
-git switch -c feat/<short-name>
-```
-
-Before creating a normal release from `dev`, inspect the release delta:
-
-```bash
-git log --oneline master..dev
-```
-
-If every listed commit is intended for the next production release, merge `dev` through the normal release path. If any commit must be excluded, create `release/vX.Y.Z` from `master` and cherry-pick only the approved release list.