soturail 0.8.0 → 0.9.0

package/docs/knowledge-to-rules.md

@@ -21,10 +21,33 @@ soturail rules doctor
 ```txt
 .soturail/brain/rules.jsonl
 .soturail/rules/from-brain.md
+.soturail/rules/from-brain.json
 ```
 
 Each brain-derived rule links back to claim IDs or decision IDs.
 
+## v0.8.1 Safety Model
+
+Rule derivation is conservative:
+
+- verified claims with validation references can become `test-backed` rules;
+- verified release, policy or security claims can become `policy-gate` candidates;
+- verified claims without tests usually become `manual-review`;
+- unverified claims stay advisory/draft;
+- suspect or stale claims do not create active rules by default;
+- superseded or rejected decisions do not create active rules.
+
+Use this repair-first flow when rules look weak or stale:
+
+```bash
+soturail brain stale --repair-plan
+soturail brain consolidate --dry-run
+soturail rules from-brain
+soturail rules doctor
+```
+
+`rules doctor` reports brain-derived rule counts, active/advisory rules, missing source links and stale-source warnings.
+
 ## Example Rules
 
 - Release notes must live under `docs/releases/`.

package/docs/memory-rail.md

@@ -176,6 +176,8 @@ Rules:
 - recurring memory should link to a claim, decision, bug or gap when possible;
 - brain exports should prefer source references and concise summaries over long copied notes.
 
+v0.8.1 keeps memory-to-brain conservative: use `soturail brain consolidate --dry-run` before deriving rules from repeated memories, and use `soturail brain stale --repair-plan` when a memory points at evidence that moved or changed.
+
 ## Privacy And Redaction
 
 Memory Rail must not make secrets easier to leak.

package/docs/native-performance-policy.md

@@ -0,0 +1,62 @@
+# Native Performance Policy
+
+SotuRail native acceleration is benchmark-gated.
+
+```txt
+No benchmark, no native rewrite.
+```
+
+TypeScript remains the portable baseline and the default safe fallback. Normal npm installs must not require Rust, Cargo, native build tools, prebuilt platform packages or a working native binary.
+
+## Decision Policy
+
+Native acceleration is allowed only when:
+
+1. A benchmark exists for the operation.
+2. A TypeScript baseline is recorded.
+3. The native path is optional.
+4. The fallback path is tested.
+5. The speedup justifies the maintenance risk.
+6. npm install stays safe for normal users.
+
+Decision statuses:
+
+```txt
+not-measured
+measured
+candidate
+approved-for-native
+native-implemented
+rejected
+```
+
+## Current Candidate Flow
+
+```bash
+soturail bench list
+soturail bench run --suite brain
+soturail native candidates
+soturail native status
+soturail native doctor
+soturail native compare
+```
+
+`native candidates` classifies operations as:
+
+- `good-candidate`
+- `maybe-candidate`
+- `not-worth-it-yet`
+- `blocked`
+
+Candidate reports are written to:
+
+```txt
+.soturail/native/candidates.json
+.soturail/native/candidates.md
+```
+
+## Required Boundary
+
+SotuRail does not claim native speedups unless a local benchmark report proves them.
+
+Native acceleration is optional. TypeScript remains the portable baseline.

package/docs/native-runner.md

@@ -43,10 +43,34 @@ npm run build:all      # TypeScript + Rust
 npm run build:native
 soturail bench run --engine native
 soturail bench compare-engines
+soturail bench run --suite brain
+soturail native candidates
+soturail native status
+soturail native compare
 ```
 
+## v0.9.0 Benchmark Gate
+
+Native acceleration is not promoted just because a native path exists. v0.9.0 requires:
+
+- a local benchmark case;
+- a TypeScript baseline;
+- optional native execution only;
+- tested fallback behavior;
+- a maintenance-risk decision.
+
+Candidate reports are written to:
+
+```txt
+.soturail/native/candidates.json
+.soturail/native/candidates.md
+```
+
+SotuRail does not claim native speedups unless a local benchmark report proves them. Normal npm install does not require Rust or native binaries.
+
 ## Current Limitations
 
 - Native binaries are not prebuilt for npm yet.
 - Interactive TTY behavior is best-effort.
 - TypeScript remains the source of truth for workspace manifests and safety prompts.
+- Parser/graph acceleration remains deferred until benchmark evidence justifies it.

package/docs/project-brain.md

@@ -50,21 +50,58 @@ Stale events record evidence drift when a source file, source range or validatio
 ```bash
 soturail brain init
 soturail brain scan
+soturail brain consolidate --dry-run
 soturail brain profile
 soturail brain recall "release notes"
-soturail brain stale
-soturail brain doctor
-soturail brain export --agent codex
+soturail brain stale --repair-plan
+soturail brain doctor --repair-plan
+soturail brain doctor --json
+soturail brain export --agent codex --limit 10
 ```
 
 `brain scan` detects package metadata, CLI version, docs folders, release note paths, rails, commands, tests, workflow/harness/diagram/eval status and supported agent hosts.
 
 `brain recall` uses deterministic scoring: exact phrases, keyword overlap, tags, record type, status, confidence and recency.
 
-`brain stale` recomputes `fileHash` and `rangeHash`. If the file changed but the range did not, it warns. If the range changed, it records a suspect event. If the source file is missing, it records a stale event.
+`brain consolidate --dry-run` reads `claims.jsonl`, groups duplicate or near-duplicate claims, chooses canonical claims conservatively and writes:
+
+```txt
+.soturail/brain/consolidated-claims.jsonl
+.soturail/brain/consolidation-report.json
+.soturail/brain/consolidation-report.md
+```
+
+It preserves append-only history. It does not delete or rewrite original claim records.
+
+`brain stale` recomputes `fileHash` and `rangeHash`. If the file changed but the range did not, it warns. If the source range changed, v0.8.1 tries to relocate similar evidence in the same file using normalized whitespace and token overlap. A high-confidence match records a `relocated` stale event; a medium-confidence match records a suspect relocation candidate. If the source file is missing, it records a stale event.
+
+`brain stale --repair-plan` writes safe guidance to:
+
+```txt
+.soturail/brain/stale-repair-plan.json
+.soturail/brain/stale-repair-plan.md
+```
+
+Repair plans never edit code, docs or claims. They name the record, source path, affected range, candidate new range, related validations and suggested commands for a human review.
+
+`brain doctor --repair-plan` checks JSONL validity, profile/index/freshness files, duplicate groups, stale/suspect records, open gaps, rules without sources, agent exports and integration status. It prints next commands for scan, consolidate, stale repair, export, rules and brain evaluation.
 
 `brain export` writes agent-safe briefs to `.soturail/brain/exports/<agent>.md`. Generic exports also write `.soturail/brain/exports/agent-brief.md`.
 
+v0.8.1 briefs are bounded by default and separate:
+
+- verified rules and claims;
+- active decisions;
+- known gaps;
+- recurring bugs and harness patterns;
+- suspect claims;
+- stale claims;
+- safe commands and critical commands;
+- recovery pointers;
+- source references.
+
+Stale claims are not placed in the verified section.
+
 ## Agent-Safe Export
 
 Brain exports include:
@@ -82,6 +119,65 @@ Brain exports include:
 
 Exports do not include private memory unless it is explicitly approved. Generated briefs must be reviewed before agent handoff.
 
+## Troubleshooting
+
+### Problem: brain stale reports many suspect claims
+
+Run:
+
+```bash
+soturail brain stale --repair-plan
+soturail reverse claims ./src
+soturail brain consolidate --dry-run
+```
+
+Then inspect `.soturail/brain/stale-repair-plan.md`. A suspect claim means the evidence changed enough to require review; it does not mean SotuRail fixed or rejected the claim.
+
+### Problem: agent brief is too long
+
+Run:
+
+```bash
+soturail brain export --agent codex --limit 10
+```
+
+Use `--include-suspect` only when the agent explicitly needs warning context.
+
+### Problem: rules from brain are too weak
+
+Check:
+
+- claims must be verified before they can become active rules;
+- stale or suspect sources are excluded from active rules by default;
+- rules must link to `sourceClaimIds` or `sourceDecisionIds`;
+- test-backed claims produce stronger enforcement than unvalidated facts.
+
+## v0.9.0 Benchmark Seeds
+
+v0.9.0 adds lightweight timing/reporting around Project Brain-related operations through Benchmark Rail 2.0:
+
+```bash
+soturail bench run --suite brain
+soturail native candidates
+```
+
+Candidate categories include:
+
+```txt
+brain-scan
+brain-stale
+brain-consolidate
+reverse-claims
+format-compare
+json-validate
+reducer-large-log
+workflow-evidence
+```
+
+TypeScript fallback must always work. Rust/native acceleration remains optional and should not be required for npm install.
+
+Project Brain performance evidence lives under `.soturail/bench/` and can be referenced by release and workflow evidence. Timing values are not public speed claims by themselves.
+
 ## Limitations
 
 - No LLM extraction.
@@ -89,4 +185,5 @@ Exports do not include private memory unless it is explicitly approved. Generate
 - No network calls.
 - No cloud sync.
 - No full static analyzer.
+- No automatic repair of code, docs or claims.
 - No claim should be treated as true without source evidence and freshness checks.

package/docs/release-workflow.md

@@ -20,6 +20,8 @@ The check also verifies:
 - `CHANGELOG.md` and `docs/releases/RELEASE_NOTES_vX.Y.Z.md` exist for the local version;
 - README install instructions and `LICENSE` exist.
 - required GitHub CI and community files exist under `.github/`.
+- optional performance evidence paths for benchmark, native candidate and baseline reports when present.
+- TypeScript fallback status and native-optional install policy.
 
 Release notes now live under `docs/releases/`. Root-level `RELEASE_NOTES_vX.Y.Z.md` files should not be created for new releases.
 
@@ -48,6 +50,17 @@ soturail release check
 
 These commands do not publish to npm or create GitHub releases.
 
+v0.9.0 adds performance evidence for release readiness:
+
+```bash
+soturail bench run --suite brain
+soturail native candidates
+soturail self baseline --check
+soturail release check
+```
+
+Release preflight warns when benchmark/native/baseline reports are missing, but native unavailability is not a release failure. A broken TypeScript fallback is a release blocker.
+
 You can run only the package verification gate with:
 
 ```bash

package/docs/releases/README.md

@@ -26,3 +26,5 @@ docs/releases/RELEASE_NOTES_vX.Y.Z.md
 - [v0.6.1](RELEASE_NOTES_v0.6.1.md)
 - [v0.7.0](RELEASE_NOTES_v0.7.0.md)
 - [v0.8.0](RELEASE_NOTES_v0.8.0.md)
+- [v0.8.1](RELEASE_NOTES_v0.8.1.md)
+- [v0.9.0](RELEASE_NOTES_v0.9.0.md)

package/docs/releases/RELEASE_NOTES_v0.8.1.md

@@ -0,0 +1,42 @@
+# SotuRail v0.8.1 - Release Notes
+
+## Install
+
+```bash
+npm install -g soturail@0.8.1
+soturail --version
+```
+
+## Highlights
+
+- Polished Project Brain stale detection with source-range relocation events.
+- Added `soturail brain consolidate --dry-run` for duplicate claim grouping.
+- Added `soturail brain stale --repair-plan` and `soturail brain doctor --repair-plan`.
+- Improved agent briefs with verified/suspect/stale separation, section limits, source references and recovery pointers.
+- Made `soturail rules from-brain` safer by excluding stale/suspect claims from active rules.
+- Expanded the brain evaluation suite with v0.8.1 quality cases.
+
+## Safety
+
+- Repair plans are guidance only. SotuRail does not auto-edit code, docs or claims.
+- Project Brain remains local and deterministic: no LLM calls, embeddings, cloud service or network-required tests.
+- Native/performance work remains benchmark-gated and TypeScript fallback remains mandatory.
+
+## Validation
+
+- `npx vitest run tests/v081.test.ts`
+- `npx vitest run tests/v080.test.ts`
+- `npm run typecheck`
+- `npm run build`
+- `npm test`
+- `npm run release:check`
+- `git diff --check`
+- `node dist/cli.js brain consolidate --dry-run`
+- `node dist/cli.js brain stale --repair-plan`
+- `node dist/cli.js brain doctor --repair-plan`
+- `node dist/cli.js eval run --suite brain`
+
+## Links
+
+- npm: https://www.npmjs.com/package/soturail
+- GitHub: https://github.com/Soturine/soturail

package/docs/releases/RELEASE_NOTES_v0.9.0.md

@@ -0,0 +1,35 @@
+# SotuRail v0.9.0 - Release Notes
+
+## Install
+
+```bash
+npm install -g soturail@0.9.0
+soturail --version
+```
+
+## Highlights
+
+- Added Benchmark Rail 2.0 reports with `soturail bench list`, `bench run --suite <suite>`, `bench compare` and stable `.soturail/bench/latest.*` output.
+- Added benchmark categories for Project Brain, reducers, JSONL, range hashing, file scanning, workflow evidence and release preflight.
+- Added `soturail native candidates`, `native status`, improved `native doctor` and `native compare` so native work is classified before any acceleration claim.
+- Added `soturail self baseline --check|--zip|--bundle|--pack` for clean source, history and package snapshots.
+- Release and workflow evidence now reference benchmark, native candidate and baseline reports when present.
+- Added docs for benchmark-gated native policy, baseline snapshots and the deferred parser/graph seed.
+
+## Safety
+
+- TypeScript fallback remains mandatory and default.
+- Rust/native remains optional.
+- Normal npm install does not require Rust, Cargo or native build tools.
+- SotuRail does not claim native speedups unless a local benchmark report proves them.
+- Parser/graph work is documented as a future seed, not promoted as a mandatory runtime.
+
+## Validation
+
+- `npm run typecheck`
+- `npm run build`
+- `npm test`
+- `npm run release:check`
+- `node dist/cli.js bench run --suite brain`
+- `node dist/cli.js native candidates`
+- `node dist/cli.js self baseline --check`

package/docs/reverse-specification-rail.md

@@ -38,6 +38,14 @@ The report summarizes scanned files, detected commands/modules, likely rails, li
 
 Claims are appended to `.soturail/brain/claims.jsonl` only when their stable ID is not already present.
 
+After a large reverse-claims run, use:
+
+```bash
+soturail brain consolidate --dry-run
+```
+
+This groups duplicate and near-duplicate claims into a report while preserving the append-only claim history.
+
 ## Draft Specs
 
 `reverse specs` writes draft specs under `.soturail/brain/specs/`:
@@ -71,3 +79,14 @@ Outputs:
 ```
 
 Use it as compact context for an agent, then verify against the cited source paths before changing code.
+
+## v0.9.0 Performance Evidence
+
+Reverse claim extraction is now tracked as a Benchmark Rail 2.0 category:
+
+```bash
+soturail bench run --suite brain
+soturail native candidates
+```
+
+`reverse-claims` is classified as a possible native/parser candidate only after local TypeScript benchmark evidence exists. The current rail remains heuristic, local and TypeScript-first.

package/docs/rules.md

@@ -36,10 +36,13 @@ soturail rules doctor
 ```txt
 .soturail/brain/rules.jsonl
 .soturail/rules/from-brain.md
+.soturail/rules/from-brain.json
 ```
 
 Each rule links back to claim IDs or decision IDs. Treat the output as advisory until a human promotes it to a policy gate or deterministic validator.
 
+v0.8.1 avoids active rules from stale or suspect claims by default. Run `soturail brain stale --repair-plan` and `soturail brain consolidate --dry-run` before deriving rules when the brain has drifted.
+
 ## Planned Policy Rule IDs
 
 Policy Rail should eventually expose stable, readable rule IDs for risky agent-assisted actions.

package/docs/workflow-rail.md

@@ -113,9 +113,24 @@ Evidence packs include:
 - evaluation report result;
 - release notes path under `docs/releases/`;
 - release gates and publish checklist notes.
+- latest benchmark report path when available;
+- native candidate report path when available;
+- baseline snapshot report path when available;
+- engine status and TypeScript fallback note.
 
 SotuRail does not claim build, test, audit, npm pack, publish or GitHub release success unless those results exist as local evidence.
 
+v0.9.0 also lets workflow evidence point to performance readiness:
+
+```bash
+soturail bench run --suite brain
+soturail native candidates
+soturail self baseline --check
+soturail workflow evidence <id>
+```
+
+Native speedups are not claimed from workflow evidence alone. The evidence pack only records where the local benchmark and candidate reports live.
+
 ## Worktrees
 
 `soturail workflow start <id> --worktree --dry-run` prints a local worktree plan. If run without `--dry-run` inside a Git repository, SotuRail may create a local worktree under `.soturail/worktrees/<id>/`.
@@ -147,10 +162,18 @@ Future Workflow Rail work can add richer trace/report commands, deeper task gene
 
 v0.8.0 lets Workflow Rail evidence reference Project Brain status. A workflow evidence pack can show the local brain profile path, claim count, gap count and stale-event count.
 
+v0.8.1 adds stronger workflow evidence hints:
+
+- brain suspect/stale count;
+- latest brain doctor path when available;
+- repair-plan flow for stale claims that affect release or workflow evidence.
+
 Useful flow:
 
 ```bash
 soturail brain scan
+soturail brain stale --repair-plan
+soturail brain doctor --repair-plan
 soturail workflow verify
 soturail workflow evidence <id>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Local-first context rails for AI coding agents: reversible terminal compression, progressive repo reading, SDD workflows, hooks, benchmarks, memory and cache-friendly payloads.",
   "type": "module",
   "bin": {