@hongmaple0820/scale-engine 0.25.0 → 0.27.0

package/docs/GITLAB_FLOW.md

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

package/docs/GOVERNANCE_DASHBOARD.md

@@ -1,85 +1,85 @@
-# Governance Dashboard
-
-Status: implemented baseline
-Since: v0.25 development branch
-
-Governance Dashboard turns existing SCALE evidence into a single reviewable HTML page. It does not replace Markdown, JSON, runtime evidence, eval records, or memory. It is a human-facing view over those sources.
-
-## Command
-
-```bash
-scale artifact dashboard
-scale artifact dashboard --task-id <task-id>
-scale artifact dashboard --dir /path/to/project
-scale artifact dashboard --output docs/worklog/tasks/<task-id>/artifacts/governance-dashboard.html
-scale artifact dashboard --json
-```
-
-Default output:
-
-```text
-.scale/reports/governance-dashboard.html
-.scale/reports/governance-dashboard-manifest.json
-```
-
-The default lifecycle is `generated-report` and the default Git policy is `ignore`. Promote or commit only dashboards that are intentionally used as reviewed task evidence or release evidence.
-
-When `--dir` is used and `SCALE_DIR` is not set, the default `.scale` directory is resolved inside the target project directory, not inside the shell's current working directory. This matters for scaffold and multi-repo validation runs.
-
-## Inputs
-
-The dashboard reads existing local evidence:
-
-| Area | Source |
-| --- | --- |
-| 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
-
-- Runtime evidence failures are blocking.
-- Memory contradictions are blocking.
-- Resource Governance failures are blocking.
-- Open eval failure replays are warnings, because they may be intentional baseline failures or pending improvement work.
-- Missing task HTML artifacts are informational.
-
-This keeps the dashboard useful as a review surface without turning every observation into a hard gate.
-
-## Recommended Use
-
-For M/L/CRITICAL work:
-
-```bash
-scale verify <task-id>
-scale eval run --suite workflow-baseline
-scale memory dream --json
-scale artifact dashboard --task-id <task-id>
-```
-
-For release review:
-
-```bash
-scale artifact dashboard
-scale artifact open --artifact-dir .scale/reports --type governance-dashboard --print-only
-```
-
-The dashboard should be attached to a release or PR only when it is deliberately selected as a review artifact. Routine generated dashboards should stay local.
+# Governance Dashboard
+
+Status: implemented baseline
+Since: v0.25 development branch
+
+Governance Dashboard turns existing SCALE evidence into a single reviewable HTML page. It does not replace Markdown, JSON, runtime evidence, eval records, or memory. It is a human-facing view over those sources.
+
+## Command
+
+```bash
+scale artifact dashboard
+scale artifact dashboard --task-id <task-id>
+scale artifact dashboard --dir /path/to/project
+scale artifact dashboard --output docs/worklog/tasks/<task-id>/artifacts/governance-dashboard.html
+scale artifact dashboard --json
+```
+
+Default output:
+
+```text
+.scale/reports/governance-dashboard.html
+.scale/reports/governance-dashboard-manifest.json
+```
+
+The default lifecycle is `generated-report` and the default Git policy is `ignore`. Promote or commit only dashboards that are intentionally used as reviewed task evidence or release evidence.
+
+When `--dir` is used and `SCALE_DIR` is not set, the default `.scale` directory is resolved inside the target project directory, not inside the shell's current working directory. This matters for scaffold and multi-repo validation runs.
+
+## Inputs
+
+The dashboard reads existing local evidence:
+
+| Area | Source |
+| --- | --- |
+| 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
+
+- Runtime evidence failures are blocking.
+- Memory contradictions are blocking.
+- Resource Governance failures are blocking.
+- Open eval failure replays are warnings, because they may be intentional baseline failures or pending improvement work.
+- Missing task HTML artifacts are informational.
+
+This keeps the dashboard useful as a review surface without turning every observation into a hard gate.
+
+## Recommended Use
+
+For M/L/CRITICAL work:
+
+```bash
+scale verify <task-id>
+scale eval run --suite workflow-baseline
+scale memory dream --json
+scale artifact dashboard --task-id <task-id>
+```
+
+For release review:
+
+```bash
+scale artifact dashboard
+scale artifact open --artifact-dir .scale/reports --type governance-dashboard --print-only
+```
+
+The dashboard should be attached to a release or PR only when it is deliberately selected as a review artifact. Routine generated dashboards should stay local.

package/docs/MEMORY_BRAIN.md

@@ -1,104 +1,104 @@
-# Memory Brain
-
-Memory Brain is SCALE's project-scoped long-term memory layer. It is separate from Memory Fabric:
-
-- Memory Fabric builds a compact context pack for the current task.
-- Memory Brain stores reviewed project knowledge with evidence, confidence, scope, and contradiction checks.
-
-The first version is local-first and uses SQLite:
-
-```text
-.scale/memory/brain.sqlite
-.scale/memory/brain-manifest.json
-```
-
-## Commands
-
-```bash
-scale memory ingest --from evidence --task-id <task-id>
-scale memory ingest --from candidate --candidate-id <candidate-id>
-scale memory ingest --from failure --failure-id <failure-replay-id>
-scale memory query "OAuth callback state design"
-scale memory contradictions
-scale memory dream
-scale memory promote <memory-node-id-or-candidate-id>
-scale memory export --output .scale/memory/export.jsonl
-scale memory import .scale/memory/export.jsonl
-```
-
-## Node Contract
-
-```ts
-interface MemoryNode {
-  id: string
-  type: 'fact' | 'decision' | 'incident' | 'relation' | 'contradiction'
-  title: string
-  summary: string
-  entities: string[]
-  source: 'runtime-evidence' | 'task-artifact' | 'docs' | 'git' | 'manual'
-  evidencePaths: string[]
-  confidence: number
-  scope: 'project' | 'workspace' | 'global-candidate'
-  status: 'candidate' | 'active' | 'stale' | 'rejected'
-  createdAt: string
-  updatedAt: string
-  lastVerifiedAt?: string
-}
-```
-
-## Evidence Rule
-
-Active memory must have at least one evidence path. SCALE blocks promotion when this is not true.
-
-Runtime evidence and learning candidates are ingested as `candidate` records first. `scale memory promote` is the explicit boundary where reviewed memory becomes active.
-
-Failure replay records can also be ingested as `incident` candidates:
-
-```bash
-scale eval run --suite workflow-baseline
-scale eval failures --since 30d
-scale memory ingest --from failure --failure-id <failure-replay-id>
-scale memory promote <memory-node-id>
-```
-
-This connects Eval Harness failures to long-term memory without automatically rewriting project standards. A failure becomes active memory only after promotion and only if the replay artifact is present as evidence.
-
-## Scope Rule
-
-Project memory stays project-scoped by default. `global-candidate` is allowed for export and review, but it cannot be activated inside a project brain. This prevents one project's temporary truth from becoming a global rule.
-
-## Contradiction Rule
-
-`scale memory contradictions` reports conflicts instead of resolving them automatically. Examples:
-
-- one memory says a provider is enabled, another says it is disabled
-- one memory says a route exists, another says it is missing
-- one memory says an operation is allowed, another says it is blocked
-
-The command exits non-zero when active contradictions exist.
-
-## Dream Maintenance
-
-`scale memory dream` is a maintenance pass. It reports:
-
-- promotion candidates
-- stale active memories
-- duplicate groups
-- contradictions
-- suggested docs to update
-- active memories missing evidence
-
-It does not auto-promote standards, rewrite docs, or delete memories.
-
-## Resource Lifecycle
-
-Memory Brain files under `.scale/memory/` are local runtime state by default. Commit only curated exports, documented decisions, or task artifacts that were intentionally reviewed.
-
-Recommended flow:
-
-```text
-runtime evidence -> memory settle -> memory ingest -> memory promote -> docs/standards update when stable
-eval failure replay -> memory ingest --from failure -> memory promote -> workflow rule update when stable
-```
-
-This keeps memory useful without turning every session observation into permanent project truth.
+# Memory Brain
+
+Memory Brain is SCALE's project-scoped long-term memory layer. It is separate from Memory Fabric:
+
+- Memory Fabric builds a compact context pack for the current task.
+- Memory Brain stores reviewed project knowledge with evidence, confidence, scope, and contradiction checks.
+
+The first version is local-first and uses SQLite:
+
+```text
+.scale/memory/brain.sqlite
+.scale/memory/brain-manifest.json
+```
+
+## Commands
+
+```bash
+scale memory ingest --from evidence --task-id <task-id>
+scale memory ingest --from candidate --candidate-id <candidate-id>
+scale memory ingest --from failure --failure-id <failure-replay-id>
+scale memory query "OAuth callback state design"
+scale memory contradictions
+scale memory dream
+scale memory promote <memory-node-id-or-candidate-id>
+scale memory export --output .scale/memory/export.jsonl
+scale memory import .scale/memory/export.jsonl
+```
+
+## Node Contract
+
+```ts
+interface MemoryNode {
+  id: string
+  type: 'fact' | 'decision' | 'incident' | 'relation' | 'contradiction'
+  title: string
+  summary: string
+  entities: string[]
+  source: 'runtime-evidence' | 'task-artifact' | 'docs' | 'git' | 'manual'
+  evidencePaths: string[]
+  confidence: number
+  scope: 'project' | 'workspace' | 'global-candidate'
+  status: 'candidate' | 'active' | 'stale' | 'rejected'
+  createdAt: string
+  updatedAt: string
+  lastVerifiedAt?: string
+}
+```
+
+## Evidence Rule
+
+Active memory must have at least one evidence path. SCALE blocks promotion when this is not true.
+
+Runtime evidence and learning candidates are ingested as `candidate` records first. `scale memory promote` is the explicit boundary where reviewed memory becomes active.
+
+Failure replay records can also be ingested as `incident` candidates:
+
+```bash
+scale eval run --suite workflow-baseline
+scale eval failures --since 30d
+scale memory ingest --from failure --failure-id <failure-replay-id>
+scale memory promote <memory-node-id>
+```
+
+This connects Eval Harness failures to long-term memory without automatically rewriting project standards. A failure becomes active memory only after promotion and only if the replay artifact is present as evidence.
+
+## Scope Rule
+
+Project memory stays project-scoped by default. `global-candidate` is allowed for export and review, but it cannot be activated inside a project brain. This prevents one project's temporary truth from becoming a global rule.
+
+## Contradiction Rule
+
+`scale memory contradictions` reports conflicts instead of resolving them automatically. Examples:
+
+- one memory says a provider is enabled, another says it is disabled
+- one memory says a route exists, another says it is missing
+- one memory says an operation is allowed, another says it is blocked
+
+The command exits non-zero when active contradictions exist.
+
+## Dream Maintenance
+
+`scale memory dream` is a maintenance pass. It reports:
+
+- promotion candidates
+- stale active memories
+- duplicate groups
+- contradictions
+- suggested docs to update
+- active memories missing evidence
+
+It does not auto-promote standards, rewrite docs, or delete memories.
+
+## Resource Lifecycle
+
+Memory Brain files under `.scale/memory/` are local runtime state by default. Commit only curated exports, documented decisions, or task artifacts that were intentionally reviewed.
+
+Recommended flow:
+
+```text
+runtime evidence -> memory settle -> memory ingest -> memory promote -> docs/standards update when stable
+eval failure replay -> memory ingest --from failure -> memory promote -> workflow rule update when stable
+```
+
+This keeps memory useful without turning every session observation into permanent project truth.