soturail 0.6.1 → 0.7.0

package/docs/diagram-rail.md

@@ -1,15 +1,11 @@
 # Diagram Rail
 
-Diagram Rail is a planned SotuRail area for using Mermaid diagrams and `.spec.md` files as compact, versioned visual context for agents.
+Diagram Rail uses Mermaid diagrams and `.spec.md` files as compact, versioned visual context for agents.
 
-It is inspired by Mermaid Diagram Driven Development patterns: diagram first, human approval, implementation second, tests and evidence after that. SotuRail should absorb the pattern without becoming a Mermaid-only tool.
+It is inspired by Mermaid Diagram Driven Development patterns: diagram first, human approval, implementation second, tests and evidence after that. SotuRail absorbs the pattern without becoming a Mermaid-only tool.
 
 ## Product Boundary
 
-Diagram Rail should help SotuRail express workflows, architecture, policies and context routes visually.
-
-It should not replace normal Markdown docs, tests, code review or human approval.
-
 ```txt
 Text explains.
 Tests verify.
@@ -17,29 +13,11 @@ Diagrams constrain and clarify.
 SotuRail connects all three as local evidence.
 ```
 
-## Core Idea
-
-```txt
-diagram first -> visual approval -> implementation -> tests -> evidence
-```
-
-A diagram should be treated as a visual contract for an agent workflow, not as decoration.
-
-Useful diagram targets:
-
-- workflow state machine;
-- release pipeline;
-- MCP resource/tool flow;
-- agent context handoff;
-- policy approval flow;
-- memory/context selection flow;
-- feature `.spec.md` business rules;
-- architecture module map;
-- failure recovery path.
+Diagram Rail should not replace normal Markdown docs, tests, code review or human approval.
 
-## Planned Commands
+## Commands
 
-Possible future commands:
+v0.7.0 implements:
 
 ```bash
 soturail diagram init
@@ -50,144 +28,89 @@ soturail diagram from-workflow <id>
 soturail workflow diagram <id>
 ```
 
-These commands should generate or validate local files only. They should not auto-edit production code.
+These commands generate or validate local files only. They do not auto-edit production code.
 
-## Planned Files
-
-Possible future structure:
+## Storage
 
 ```txt
 .soturail/diagrams/
+  index.json
+  validation.json
 docs/diagrams/
-docs/diagrams/release-flow.mmd
-docs/diagrams/agent-context-flow.mmd
-docs/diagrams/workflow-rail.mmd
-docs/diagrams/policy-flow.mmd
+  <feature>.md
+  <feature>.spec.md
 ```
 
-Feature-level specs can use co-located files:
+`diagram init` creates both the local rail folder and the docs folder.
 
-```txt
-src/feature-name/feature-name.spec.md
-src/feature-name/feature-name.mmd
-```
-
-## `.spec.md` As Visual Contract
+`diagram new <feature>` creates a Mermaid diagram plus matching visual contract.
 
-A `.spec.md` file can combine:
+`diagram from-workflow <id>` creates a workflow state diagram from local Workflow Rail metadata.
 
-- purpose;
-- requirements;
-- constraints;
-- Mermaid diagram;
-- decision matrix;
-- acceptance criteria;
-- test plan;
-- version/change notes.
+`diagram validate` validates all `docs/diagrams/*.md` diagrams except `.spec.md` contracts and writes `.soturail/diagrams/validation.json`.
 
-The agent should implement against the approved spec, not against a vague chat memory.
+## `.spec.md` Visual Contracts
 
-## Workflow Rail Integration
+Generated `.spec.md` files include:
 
-Diagram Rail should connect with Workflow Rail 2.0:
+```md
+# Visual Contract: Feature X
 
-```txt
-Idea -> PRD -> Diagram -> Tasks -> TDD -> Work -> Review -> Release -> Evidence
-```
-
-Future workflow evidence can include:
-
-- diagram path;
-- diagram version;
-- validation result;
-- related spec path;
-- tasks generated from diagram;
-- tests linked to diagram edges or states.
+## Required nodes
 
-## Validation Ideas
+## Required transitions
 
-The v0.6.1 evaluation suite includes a lightweight Diagram Rail validator seed for local quality checks. It catches practical issues:
+## Evidence links
 
-- invalid Mermaid syntax;
-- missing start/end states;
-- unreachable states;
-- unlabeled risky transitions;
-- workflow phase missing verification;
-- release path without tests/audit/pack evidence;
-- context route without recovery pointer;
-- policy path without approve/reject state.
+## Validation checklist
 
-Basic validation plan:
-
-1. Check that Mermaid fenced blocks exist where expected.
-2. Check that state diagrams include start or initial states when the diagram models a workflow.
-3. Check that release diagrams include build/test/package verification before publish.
-4. Check that policy diagrams include approve and reject paths.
-5. Check that context-router diagrams include recovery/offload pointers for omitted context.
-6. Report warnings only; never rewrite diagrams without explicit user action.
-
-Run it through the evaluation suite:
-
-```bash
-soturail eval run
-soturail eval report
+## Known gaps
 ```
 
-The v0.6.1 validator is deliberately small. Full `soturail diagram ...` commands remain future v0.7 work.
+The contract is intentionally human-readable. Agents should implement against the approved spec, not against vague chat memory.
 
-## Example Diagram Targets
+## Audit Rules
 
-Workflow:
+`diagram audit <file>` checks:
 
-```mermaid
-stateDiagram-v2
-    Draft --> Planned
-    Planned --> Active
-    Active --> Verifying
-    Verifying --> ReadyForReview
-    ReadyForReview --> Closed
-    Verifying --> Blocked
-```
+- file exists;
+- Mermaid block exists;
+- code fences are balanced;
+- matching `.spec.md` exists;
+- known workflow states are referenced when applicable;
+- the lightweight Mermaid validator accepts the diagram or reports findings.
 
-Policy:
+The validator is deterministic and intentionally light. It catches practical issues like missing Mermaid content, unsupported diagram declarations, state diagrams without initial transitions and workflow diagrams missing verification transitions.
 
-```mermaid
-flowchart TD
-    RiskyAction --> Queue
-    Queue --> Approve
-    Queue --> Reject
-    Approve --> Evidence
-    Reject --> SaferAlternative
-```
+## Workflow Rail Integration
 
-Release:
+Diagram Rail connects to Workflow Rail 2.0:
 
-```mermaid
-flowchart LR
-    Build --> Test
-    Test --> PackVerify
-    PackVerify --> NpmPublish
-    NpmPublish --> GitHubRelease
+```txt
+setup -> plan -> work -> review -> verify -> evidence
 ```
 
-## Agent Prompt Usage
+Workflow evidence can include:
 
-Diagram Rail should give agents compact visual context:
+- diagram path;
+- matching `.spec.md` path;
+- validation result;
+- generated workflow state diagram;
+- release or policy diagram when present.
+
+## Example Diagram
 
-```markdown
 ```mermaid
 stateDiagram-v2
-    Draft --> Planned
-    Planned --> Active
-    Active --> Verifying
-    Verifying --> ReadyForReview
-    ReadyForReview --> Closed
-    Verifying --> Blocked
-```
+    [*] --> draft
+    draft --> planned
+    planned --> active
+    active --> verifying
+    verifying --> ready_for_review
+    ready_for_review --> closed
+    verifying --> blocked
 ```
 
-The point is not that diagrams are magic. The point is that diagrams make state, sequence and constraints explicit in fewer tokens than long prose.
-
 ## Acceptance Criteria
 
 Diagram Rail is successful only if:
@@ -198,3 +121,5 @@ Diagram Rail is successful only if:
 - diagrams do not replace tests;
 - implementation remains tied to evidence;
 - no agent host is required to support Mermaid natively for the files to be useful.
+
+Future versions can add `diagram sync`, `diagram from-repo` and richer local rendering after the workflow and evidence model is stable.

package/docs/harness-rail.md

@@ -1,71 +1,17 @@
 # Harness Rail
 
-Harness Rail is the SotuRail area for making agent-assisted development more disciplined, auditable and repeatable.
-
-It is inspired by Claude Code harness patterns such as `setup -> plan -> work -> review -> release`, runtime guardrails, review perspectives and evidence packs. SotuRail should absorb those patterns without becoming a Claude-only plugin or a full autonomous agent runtime.
+Harness Rail makes agent-assisted development more disciplined, auditable and repeatable. It absorbs setup/plan/work/review/release patterns without becoming a Claude-only plugin or autonomous runtime.
 
 ## Product Boundary
 
-Harness Rail should keep SotuRail as the local Context OS layer:
-
 ```txt
 SotuRail prepares context, policy, evidence and reports.
 The agent still plans, edits, reasons and executes through its own host.
 ```
 
-This means Harness Rail should focus on:
-
-- workflow discipline;
-- policy decisions;
-- review evidence;
-- release evidence;
-- failure learning;
-- local reports;
-- safe handoffs between agents or roles.
-
-## Planned Workflow Shape
-
-The long-term workflow should support a clearer delivery loop:
-
-```txt
-setup -> plan -> work -> review -> release
-```
-
-Possible future commands:
-
-```bash
-soturail workflow setup
-soturail workflow plan
-soturail workflow work
-soturail workflow review
-soturail workflow release
-```
-
-These commands may be implemented as direct commands, workflow templates, or aliases over existing `workflow` subcommands. They should not hide what is happening. Each phase should write evidence into `.soturail/workflows/<id>/`.
-
-## Review Perspectives
-
-Harness Rail should support review perspectives as structured sections rather than vague feedback.
-
-Possible future commands:
-
-```bash
-soturail workflow review --perspective security
-soturail workflow review --perspective quality
-soturail workflow review --perspective performance
-soturail workflow review --perspective accessibility
-soturail workflow review --all
-```
-
-Suggested default perspectives:
+Harness Rail focuses on workflow discipline, policy decisions, review evidence, release evidence, failure learning and local handoffs.
 
-- **security**: secrets, injection, unsafe permissions, dangerous commands;
-- **quality**: naming, duplication, maintainability, architecture drift;
-- **performance**: slow paths, memory, repeated work, large payloads;
-- **accessibility**: UI semantics, keyboard flow, contrast, screen-reader concerns where applicable;
-- **release**: build, tests, audit, package verification, release notes.
-
-## v0.5.0 Seed Commands
+## Commands
 
 ```bash
 soturail harness note "agent said done before tests passed"
@@ -77,66 +23,74 @@ soturail harness contract check
 soturail workflow evidence <id>
 ```
 
-`harness contract check` validates the local contract in v0.5.0. It does not run build, typecheck or test commands by default.
+`harness contract check` validates the local contract. It does not run build, typecheck or test commands by default.
 
-## Evidence Pack
+## v0.7.0 Workflow Connection
 
-Every serious workflow or release should be able to produce an evidence pack.
+Harness Rail now connects to Workflow Rail 2.0:
 
-The v0.5.0 seed supports:
+- `harness doctor` reports the active workflow when one exists.
+- It reports whether the default harness contract is present.
+- It reports the failure count and latest workflow verification status.
+- It suggests a prevention action from the latest failure.
+- `workflow verify` reads harness contract status.
+- `workflow evidence <id>` includes harness failures and contract references.
 
-```bash
-soturail workflow evidence <id>
-```
+## Harness Failure Ledger
 
-Evidence should include:
-
-- workflow id and state;
-- plan path;
-- tasks path;
-- verification path;
-- build result;
-- test result;
-- audit result;
-- npm pack/package verification result;
-- changed files;
-- raw command ids;
-- offload ids;
-- selected context pack;
-- selected role pack;
-- policy approvals/rejections;
-- release notes path;
-- benchmark report path when relevant.
+Repeated agent mistakes should become useful local knowledge instead of disappearing into chat history.
 
-## Harness Failure Ledger
+A failure record tracks:
 
-Repeated agent mistakes should become useful local knowledge instead of chat history that disappears.
+- workflow id when available;
+- what failed;
+- suspected root cause when supplied;
+- evidence path or raw id when supplied;
+- prevention candidate.
 
-Possible future commands:
+Prevention candidates include:
 
-```bash
-soturail harness note "agent missed Windows npm cache issue"
-soturail harness list
-soturail harness explain <id>
-soturail harness report
-soturail harness doctor
+```txt
+rule
+doc
+memory
+workflow check
+diagram/spec update
 ```
 
-A failure record should track:
+Use `diagram/spec update` when a repeated failure points to a missing visual contract, unclear state transition or stale `.spec.md` file.
 
-- task or workflow id;
-- command or agent action;
-- what failed;
-- root cause if known;
-- fix applied;
-- files changed;
-- whether it repeated;
-- evidence path;
-- prevention candidate: rule, doc, hook, memory or workflow check.
+## Review Perspectives
+
+Workflow review reports are deterministic sections rather than vague feedback. v0.7.0 uses:
+
+- **security**: secrets, unsafe permissions, dangerous commands, raw-log risk;
+- **docs**: README, focused docs and release notes;
+- **tests**: build/typecheck/test evidence and missing checks;
+- **release**: version, changelog, release notes and publish gates;
+- **context**: selected context, offload recovery and role packs;
+- **agent-readiness**: short root docs, policy notes, MCP exposure and handoff readiness.
+
+## Release Evidence
+
+Release evidence should include:
+
+- package version;
+- CLI version;
+- changelog entry;
+- release notes path under `docs/releases/`;
+- npm tarball check guidance;
+- GitHub tag recommendation;
+- npm publish checklist;
+- CI status note;
+- evaluation report path;
+- workflow verification result.
+
+Harness Rail does not publish automatically. Publishing stays an explicit release action.
 
 ## Guardrail Relationship
 
-Harness Rail should connect to Policy Rail. Risky actions should be explainable and reviewable before they happen.
+Harness Rail connects to Policy Rail. Risky actions should be explainable and reviewable before they happen.
 
 Examples:
 
@@ -153,14 +107,11 @@ R08 require evidence before release
 
 ## Acceptance Criteria
 
-Harness Rail is successful only if it makes SotuRail more predictable without making it heavy.
-
-Minimum acceptance criteria before promotion:
+Harness Rail is successful only if it makes SotuRail more predictable without making it heavy:
 
-- docs explain the workflow clearly;
 - commands remain local-first;
-- dry-run or preview exists for risky actions;
+- risky actions remain dry-run or approval-first;
 - evidence is stored locally and recoverable;
-- tests cover at least one clean workflow fixture;
-- benchmarks/reporting distinguish token savings from quality preservation;
+- tests cover clean workflow fixtures;
+- reports distinguish token savings from quality preservation;
 - no arbitrary shell execution is exposed through MCP by default.

package/docs/release-checklist.md

@@ -15,6 +15,8 @@ Before publishing:
 - [ ] `npm pack --dry-run`
 - [ ] `npm run release:check`
 - [ ] `node dist/cli.js release verify-package`
+- [ ] Release notes exist at `docs/releases/RELEASE_NOTES_vX.Y.Z.md`.
+- [ ] Workflow evidence includes release notes, eval report and verification status when this release uses Workflow Rail.
 - [ ] `node dist/cli.js --version` matches `package.json`.
 - [ ] Confirm docs mention limitations honestly.
 - [ ] Confirm no telemetry exists.
@@ -78,6 +80,18 @@ npx --yes soturail@X.Y.Z --version
 
 Create or update the GitHub release only after those npm checks pass.
 
+## Release Notes Location
+
+Repository release notes live in `docs/releases/`. GitHub Releases copy that content at publish time.
+
+Do not leave new root-level `RELEASE_NOTES_vX.Y.Z.md` files in the repository.
+
+For v0.7.0 and later, release preflight looks for:
+
+```txt
+docs/releases/RELEASE_NOTES_vX.Y.Z.md
+```
+
 ## Windows Paste Safety
 
 Do not paste Markdown prose or code-fence labels directly into `cmd.exe` as commands. For example, do not paste ```` ```bat ````. Copy only the command lines themselves.

package/docs/release-workflow.md

@@ -17,10 +17,37 @@ The check also verifies:
 - npm pack dry-run emits the matching tarball name;
 - the packed tarball installs into a clean temp project and its installed CLI prints the package version;
 - expected package files are present and forbidden generated files are absent;
-- `CHANGELOG.md` and `RELEASE_NOTES_vX.Y.Z.md` exist for the local version;
+- `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/`.
 
+Release notes now live under `docs/releases/`. Root-level `RELEASE_NOTES_vX.Y.Z.md` files should not be created for new releases.
+
+## Release Evidence
+
+v0.7.0 workflow evidence includes release evidence when package metadata is present:
+
+- package version;
+- CLI version;
+- `CHANGELOG.md` entry;
+- release notes path under `docs/releases/`;
+- npm tarball check guidance;
+- GitHub tag recommendation;
+- npm publish checklist;
+- CI status note;
+- evaluation report path;
+- workflow verification result.
+
+Generate or inspect local release evidence with:
+
+```bash
+soturail workflow verify
+soturail workflow evidence <id>
+soturail release check
+```
+
+These commands do not publish to npm or create GitHub releases.
+
 You can run only the package verification gate with:
 
 ```bash
@@ -90,3 +117,9 @@ Safety rules:
 - Never publish if the requested package version already exists on npm.
 - Never create a GitHub release before npm publish succeeds.
 - Never hide errors.
+
+## Historical npm Backfill Policy
+
+If a GitHub tag/release exists for an older version that was not published to npm, backfill only when the historical checkout builds, tests and publishes safely with a non-latest tag such as `backfill`.
+
+Do not force-publish historical packages if their historical tests fail or npm requires unavailable 2FA. Record the blocker and continue the current release.

package/docs/releases/README.md

@@ -0,0 +1,27 @@
+# Release Notes
+
+This folder is the repository source of truth for SotuRail release notes.
+
+GitHub Releases copy the relevant file contents at release time. Keep edited release notes here so package checks, release scripts and docs all use the same path:
+
+```txt
+docs/releases/RELEASE_NOTES_vX.Y.Z.md
+```
+
+## Index
+
+- [v0.2.1](RELEASE_NOTES_v0.2.1.md)
+- [v0.2.2](RELEASE_NOTES_v0.2.2.md)
+- [v0.2.3](RELEASE_NOTES_v0.2.3.md)
+- [v0.3.0](RELEASE_NOTES_v0.3.0.md)
+- [v0.3.1](RELEASE_NOTES_v0.3.1.md)
+- [v0.3.2](RELEASE_NOTES_v0.3.2.md)
+- [v0.3.3](RELEASE_NOTES_v0.3.3.md)
+- [v0.4.0](RELEASE_NOTES_v0.4.0.md)
+- [v0.4.1](RELEASE_NOTES_v0.4.1.md)
+- [v0.5.0](RELEASE_NOTES_v0.5.0.md)
+- [v0.5.1](RELEASE_NOTES_v0.5.1.md)
+- [v0.5.2](RELEASE_NOTES_v0.5.2.md)
+- [v0.6.0](RELEASE_NOTES_v0.6.0.md)
+- [v0.6.1](RELEASE_NOTES_v0.6.1.md)
+- [v0.7.0](RELEASE_NOTES_v0.7.0.md)

package/docs/releases/RELEASE_NOTES_v0.2.1.md

@@ -0,0 +1,19 @@
+SotuRail v0.2.1 is the first public npm release.
+
+## Install
+
+- npx soturail --help
+- npm install -g soturail
+- soturail --help
+
+## Highlights
+
+- Published on npm.
+- Local-first Context OS for AI coding agents.
+- Reversible terminal compression and raw log recovery.
+- Progressive repo reading.
+- Spec-Driven Development workflow.
+- Agent response compression.
+- Knowledge-to-Rules ingestion.
+- Prompt-cache-friendly payload organization.
+- Local benchmarks and metrics.

package/docs/releases/RELEASE_NOTES_v0.2.2.md

@@ -0,0 +1,48 @@
+# SotuRail v0.2.2 - Self-Dogfooding & Reliability
+
+SotuRail v0.2.2 adds the first self-dogfooding workflow: the project can now validate itself using SotuRail commands before release.
+
+## Install
+
+- `npx soturail@0.2.2 --help`
+- `npm install -g soturail`
+- `soturail --help`
+
+## Highlights
+
+- `soturail self doctor`
+- `soturail self index`
+- `soturail self build`
+- `soturail self test`
+- `soturail self bench`
+- `soturail self report`
+- `soturail self all`
+- Cache-friendly self-dogfood report.
+- Honest tiny-output stats accounting.
+- Expanded benchmark categories.
+- Windows documentation.
+
+## Validation
+
+- `npm run build`: passed (`tsc -p tsconfig.json`)
+- `npm test`: passed (1 passed)
+- `npm audit --omit=dev`: passed (`found 0 vulnerabilities`)
+- `node dist/cli.js self all`: passed (report: .soturail\reports\self-dogfood.md)
+- `npm pack --dry-run`: passed (soturail-0.2.2.tgz)
+
+## Audit Notes
+
+Runtime audit is clean with `npm audit --omit=dev`. Remaining audit findings, if any, are development dependency findings and should be upgraded safely without `--force`.
+
+- Runtime audit findings: 0
+- Full audit findings: 5
+- Development-only findings: @vitest/mocker, esbuild, vite, vite-node, vitest
+
+## Notes
+
+SotuRail does not claim provider cache hits unless real provider metadata is imported.
+
+## Links
+
+- npm: https://www.npmjs.com/package/soturail
+- GitHub: https://github.com/Soturine/soturail

package/docs/releases/RELEASE_NOTES_v0.2.3.md

@@ -0,0 +1,36 @@
+# SotuRail v0.2.3 - Release Reliability & CLI Version Sync
+
+SotuRail v0.2.3 fixes CLI version metadata and adds release preflight checks to prevent stale npm/CLI releases.
+
+## Install
+
+    npx soturail@0.2.3 --help
+    npm install -g soturail
+    soturail --help
+
+## Fixes
+
+- Fixed CLI `--version` output so it matches the npm package version.
+- Removed stale hardcoded version metadata from CLI command logic.
+- Added release preflight checks before npm publish.
+
+## Release Reliability
+
+- Added version sync validation.
+- Added package-lock validation.
+- Added npm pack metadata validation.
+- Added changelog/release-notes validation.
+- Added runtime audit validation.
+
+## Validation
+
+- `npm run build`
+- `npm test`
+- `npm audit --omit=dev`
+- `npm pack --dry-run`
+- `node dist/cli.js --version`
+
+## Links
+
+- npm: https://www.npmjs.com/package/soturail
+- GitHub: https://github.com/Soturine/soturail