soturail 0.6.1 → 0.7.0

package/docs/releases/RELEASE_NOTES_v0.3.0.md

@@ -0,0 +1,42 @@
+# SotuRail v0.3.0 - Skill Rail, MCP & Context Packs
+
+SotuRail v0.3.0 adds Skill Rail, a local MCP-compatible stdio server, and cache-friendly context packs for AI coding agents.
+
+## Install
+
+```bash
+npx --yes soturail@0.3.0 --help
+npm install -g soturail@0.3.0
+soturail --version
+```
+
+## Highlights
+
+- `soturail skills` creates, validates, exports and packs safe local agent skills.
+- `soturail mcp` exposes read-only resources and safe tools over JSON-RPC style stdio.
+- `soturail context pack` builds target-aware context packs with stable content before dynamic session data.
+- Hooks now support reviewed exports and the `--agent` / `--mode` command shape.
+- Benchmarks include Skill Rail, MCP, context packs, hook export and memory workflow cases.
+- Release automation validates package/CLI version sync, changelog, release notes, runtime audit and npm pack contents before publication.
+- Release commands now accept a positional version such as `soturail release publish 0.3.0`, while preserving `--target-version` and backward-compatible `--version` usage.
+
+## Safety
+
+SotuRail remains local-first. The MCP server does not expose arbitrary shell execution in v0.3.0. Raw logs may contain secrets, and MCP raw-log expansion redacts probable secrets unless explicitly requested with `allow_raw=true`.
+
+## Validation
+
+- `npm run build`
+- `node dist/cli.js --version`
+- `npm test`
+- `npm audit --omit=dev`
+- `npm audit`
+- `node dist/cli.js self all`
+- `node dist/cli.js bench`
+- `node dist/cli.js release check`
+- `npm pack --dry-run`
+
+## Links
+
+- npm: https://www.npmjs.com/package/soturail
+- GitHub: https://github.com/Soturine/soturail

package/docs/releases/RELEASE_NOTES_v0.3.1.md

@@ -0,0 +1,37 @@
+# SotuRail v0.3.1 - Real Usage & Integration Polish
+
+SotuRail v0.3.1 improves the installed user experience after the v0.3.0 Skill Rail, MCP and Context Pack release.
+
+## Highlights
+
+- `soturail init` now scaffolds v0.3 docs and examples.
+- `soturail skills list` now prints richer skill details.
+- `soturail skills init` now creates a more useful starter skill.
+- MCP stdio behavior has stronger smoke coverage.
+- Hooks doctor now shows next safe commands.
+- Added first real workflow documentation.
+- Added examples for skills, MCP, hooks and context packs.
+- Added clean-folder smoke test coverage.
+
+## Install
+
+```bash
+npm install -g soturail@0.3.1
+soturail --version
+```
+
+## Validate
+
+```bash
+soturail init
+soturail index
+soturail context pack --target generic
+soturail skills init demo-skill
+soturail skills validate
+soturail mcp doctor
+soturail hooks doctor
+```
+
+## Notes
+
+This is a polish release. It does not expose arbitrary shell execution through MCP.

package/docs/releases/RELEASE_NOTES_v0.3.2.md

@@ -0,0 +1,33 @@
+# SotuRail v0.3.2 - Strong Reducers, Deduplication & Package Verification
+
+SotuRail v0.3.2 strengthens the core reducer/deduplication layer and adds package verification gates to prevent stale CLI metadata from being published.
+
+## Highlights
+
+- Stronger reducers for common developer outputs.
+- Block-level dedupe.
+- Improved `soturail dedupe` stats.
+- Improved `soturail stats` accounting.
+- Safer `soturail expand` with default secret redaction.
+- Expanded benchmark cases.
+- Release verification now installs the packed tarball in a clean temporary folder before publish.
+
+## Install
+
+```bash
+npm install -g soturail@0.3.2
+soturail --version
+```
+
+## Validate
+
+```bash
+soturail run npm test
+soturail dedupe stats
+soturail stats
+soturail bench
+```
+
+## Security
+
+Raw logs may contain secrets. `soturail expand` redacts probable secrets by default.

package/docs/releases/RELEASE_NOTES_v0.3.3.md

@@ -0,0 +1,31 @@
+# SotuRail v0.3.3 - Package Verification Hotfix
+
+SotuRail v0.3.3 fixes the packed package CLI verification path used before npm releases.
+
+## Highlights
+
+- Fixes packed package CLI version verification.
+- Avoids npm cache, `npx`, `npm exec` and global CLI false positives.
+- Strengthens cross-platform release gates on Windows, Linux and macOS.
+- Keeps runtime audit clean.
+- Does not add new product features.
+
+## Install
+
+```bash
+npm install -g soturail@0.3.3
+soturail --version
+```
+
+## Validate
+
+```bash
+npm run build
+npm test
+npm audit --omit=dev
+npm run release:check
+```
+
+## Notes
+
+Release verification now installs the packed `.tgz` into a clean temporary project and executes `node_modules/soturail/dist/cli.js` directly.

package/docs/releases/RELEASE_NOTES_v0.4.0.md

@@ -0,0 +1,35 @@
+# SotuRail v0.4.0 - Real Agent Integrations & Workflow Rail
+
+SotuRail v0.4.0 adds real agent integration exports, MCP config helpers and a safe Workflow Rail for local task planning and optional Git worktree isolation.
+
+## Highlights
+
+- Agent registry for Claude, Codex, Gemini, Cursor, Antigravity and generic agents.
+- Agent-specific context and prompt exports.
+- MCP config helper and MCP smoke test.
+- Improved hooks exports and dry-run safety.
+- Workflow Rail with local task state.
+- Optional Git worktree isolation.
+- Strong release package verification.
+
+## Install
+
+```bash
+npm install -g soturail@0.4.0
+soturail --version
+```
+
+## Try It
+
+```bash
+soturail init
+soturail agents doctor
+soturail agents export --agent all
+soturail mcp smoke
+soturail workflow new "Try SotuRail Workflow Rail"
+soturail workflow list
+```
+
+## Security
+
+SotuRail does not expose arbitrary shell execution through MCP by default. Agent installs are dry-run-first and backup-first.

package/docs/releases/RELEASE_NOTES_v0.4.1.md

@@ -0,0 +1,37 @@
+# SotuRail v0.4.1 - Agent Scaffold, Docs & UX Polish
+
+SotuRail v0.4.1 polishes the v0.4 agent integration experience and fixes incomplete scaffold output from `soturail init`.
+
+## Highlights
+
+- `soturail init` now includes v0.4 agent docs.
+- `soturail init` now includes agent examples.
+- `soturail init` now includes workflow examples.
+- `soturail agents doctor` now gives better next-step guidance.
+- Workflow Rail list/show/close UX is clearer.
+- Generated docs no longer include stale v0.1/v0.3 wording.
+- `.gitattributes` reduces Windows line-ending noise.
+- Release checks protect required GitHub workflow files.
+
+## Install
+
+```bash
+npm install -g soturail@0.4.1
+soturail --version
+```
+
+## Try it
+
+```bash
+soturail init
+soturail context pack --target all
+soturail agents doctor
+soturail agents export --agent all
+soturail mcp smoke
+soturail workflow new "Try SotuRail"
+soturail workflow list
+```
+
+## Security
+
+SotuRail remains safe-by-default. MCP does not expose arbitrary shell execution.

package/docs/releases/RELEASE_NOTES_v0.5.0.md

@@ -0,0 +1,21 @@
+# SotuRail v0.5.0 - Local Rail MVP
+
+SotuRail v0.5.0 introduced the first local rail MVP for memory, context intelligence, role packs, harness evidence, policy queues, filesystem evidence, run workspaces and optional native diagnostics.
+
+## Highlights
+
+- Memory Rail commands for remember, recall, capture, consolidate and doctor.
+- Context Intelligence commands for select, prune, route, budget, offload and restore.
+- Role-based context packs for planner, executor, reviewer, release-manager and researcher.
+- Harness Failure Ledger and acceptance contract seed commands.
+- Policy Approval Queue and policy doctor/validate commands.
+- Filesystem Evidence Rail snapshot, touched, diff and plan-edit commands.
+- Agent docs hygiene lint, split-context and explain commands.
+- Skill Boundary Rail suggest and route commands.
+- MCP exposure report with JSON output.
+- Run Workspace Rail seed commands under `soturail run workspace`.
+- Workflow Evidence Pack seed and native doctor fallback diagnostics.
+
+## Security
+
+SotuRail remains local-first and safe-by-default. MCP does not expose arbitrary shell execution by default, raw/offloaded context is redacted for probable secrets before reports, and native acceleration remains optional.

package/docs/releases/RELEASE_NOTES_v0.5.1.md

@@ -0,0 +1,19 @@
+# SotuRail v0.5.1 - Agent UX And Payload Polish
+
+SotuRail v0.5.1 polished the v0.5 rail outputs and added lightweight structured payload helpers for safer local agent handoffs.
+
+## Highlights
+
+- Light `soturail validate json <file> --strict` seed for JSON parse, duplicate-key, probable-secret and huge-array checks.
+- Light `soturail format compare <file>` seed for Markdown, JSON, tagged-block and compact-format handoff hints.
+- Migration notes for moving from v0.4.x to v0.5.x rails.
+- Structured Payload Rail and Diagram Rail examples.
+- Improved Memory Rail recall output with score, reason, source, tags, confidence and privacy details.
+- Improved Memory Rail doctor output with storage, consolidated count, secret hints and approved-memory export guidance.
+- Improved Context Intelligence output with recovery pointers, clearer prune sections and richer budget drivers.
+- Improved Run Workspace show/clean output with summary, handoff, evidence and linked artifact status.
+- Expanded docs for role packs, agent docs hygiene, approved-memory export and clean-folder onboarding.
+
+## Security
+
+JSON validation warns about probable secrets before agent handoff. Format comparison and structured payload docs recommend redaction, offload and review for large or sensitive payloads.

package/docs/releases/RELEASE_NOTES_v0.5.2.md

@@ -0,0 +1,27 @@
+# SotuRail v0.5.2 - CI Stabilization And Lightweight Quality Fixtures
+
+SotuRail v0.5.2 is a small stabilization release for the v0.5 rail line.
+
+## Highlights
+
+- Fixes stale CI test expectations from v0.4.x/v0.5.x version drift.
+- Makes release metadata tests version-aware.
+- Makes agent doctor tests validate stable behavior without depending on old exact wording.
+- Adds lightweight local quality fixtures for JSON validation, format comparison, context routing, budget output, run workspaces, workflow evidence and agent docs hygiene.
+- Realigns the roadmap so the full evaluation suite moves to v0.6.1.
+
+## Not Included
+
+- No npm publish automation.
+- No GitHub release automation.
+- No heavy benchmark or evaluation harness.
+- No network, provider or native-binary requirement.
+
+## Try From Source
+
+```bash
+npm install
+npm run build
+node dist/cli.js --version
+npm test
+```

package/docs/releases/RELEASE_NOTES_v0.6.0.md

@@ -0,0 +1,33 @@
+# SotuRail v0.6.0 - Real Agent Runtime Integration
+
+SotuRail v0.6.0 adds a conservative host-aware Agent Runtime Adapter. SotuRail still prepares local context, rules, skills, MCP notes, role packs, policy guidance and evidence. The actual agent host still owns the model, planning loop, editing UI and runtime.
+
+## Highlights
+
+- `soturail agents capabilities` shows a host capability matrix.
+- `soturail agents status` inspects local agent files, exports, context packs, role packs, skills, MCP exports, policy state and run workspaces.
+- `soturail agents doctor --verbose` adds host-aware payload, policy and dry-run install guidance.
+- `soturail agents install --agent claude --dry-run`, `cursor --dry-run` and `gemini --dry-run` preview project-local writes, backups and policy warnings.
+- Experimental `deepagents` and `deepagents-js` exports create context/config artifacts only.
+- Host-aware docs cover prompt-only fallback, payload formats, policy notes and generated-file review.
+
+## Try It
+
+```bash
+soturail agents capabilities
+soturail agents status
+soturail agents doctor --verbose
+soturail agents install --agent claude --dry-run
+soturail agents install --agent cursor --dry-run
+soturail agents install --agent gemini --dry-run
+soturail agents export --agent deepagents
+soturail agents export --agent deepagents-js
+```
+
+## Security
+
+SotuRail remains safe-by-default. It does not write global config by default, does not expose arbitrary shell execution through MCP and creates backups before modifying existing project-local agent files.
+
+## Not Included
+
+v0.6.0 does not publish to npm, create a GitHub release, install Deep Agents packages, create an autonomous editing runtime or run the v0.6.1 heavy evaluation suite.

package/docs/releases/RELEASE_NOTES_v0.6.1.md

@@ -0,0 +1,37 @@
+# SotuRail v0.6.1 - Agent UX Polish And Full Evaluation Suite
+
+v0.6.1 adds the local evaluation suite and improves agent setup guidance on top of the v0.6.0 Agent Runtime Adapter.
+
+## Highlights
+
+- Added `soturail eval list`, `soturail eval run` and `soturail eval report`.
+- Added deterministic local fixtures for memory recall, context selection, reducers, context routing, role packs, agent-doc hygiene, offload/restore, format quality, strict JSON, evidence packs, harness scenarios and Diagram Rail validation.
+- Improved `agents doctor`, `agents status`, `agents capabilities` and `agents explain` with clearer copy/paste setup guidance.
+- Added practical setup tutorials for Claude Code, Codex, Gemini CLI, Cursor, Antigravity prompt-only workflows and Deep Agents-style role packs.
+- Documented how to read evaluation reports and why token savings without quality preservation is not enough.
+
+## Safety
+
+- No npm publish was run as part of this release prep.
+- No provider APIs, paid services, real agent hosts or network calls are required for the evaluation suite.
+- Agent installs remain project-local, dry-run/backup-first and review-first.
+- SotuRail still does not expose arbitrary shell execution through MCP.
+
+## Verification
+
+Recommended local checks:
+
+```bash
+npm run typecheck
+npm run build
+npm test
+soturail eval run
+soturail eval report
+```
+
+Evaluation reports are written to:
+
+```txt
+.soturail/eval/latest.json
+.soturail/eval/latest.md
+```

package/docs/releases/RELEASE_NOTES_v0.7.0.md

@@ -0,0 +1,33 @@
+# SotuRail v0.7.0 - Workflow, Harness And Diagram Rails
+
+SotuRail v0.7.0 deepens the local workflow layer. It adds Workflow Rail 2.0 phases, Harness Rail integration, Diagram Rail commands, `.spec.md` visual contracts and release evidence that points to the new `docs/releases/` release-note source.
+
+## Added
+
+- Added `soturail workflow setup`.
+- Added title-based `soturail workflow plan "Task title"` for Workflow Rail 2.0 plans.
+- Added `soturail workflow work`, `soturail workflow review --all`, `soturail workflow verify` and `soturail workflow diagram <id>`.
+- Added deterministic review perspectives for security, docs, tests, release, context and agent readiness.
+- Added `soturail diagram init`, `soturail diagram new <feature>`, `soturail diagram audit <file>`, `soturail diagram validate` and `soturail diagram from-workflow <id>`.
+- Added generated `.spec.md` visual contracts with required nodes, transitions, evidence links, validation checklist and known gaps.
+- Added v0.7.0 tests for release-note paths, workflow phases, harness doctor integration, diagram commands and evidence contents.
+
+## Changed
+
+- Moved repository release notes from root-level `RELEASE_NOTES_vX.Y.Z.md` files into `docs/releases/`.
+- Updated release scripts, release preflight, tests and docs to use `docs/releases/RELEASE_NOTES_vX.Y.Z.md`.
+- Improved workflow evidence packs with review/verify artifacts, offload IDs, harness contracts, diagram validation, eval reports and release evidence.
+- Improved `harness doctor` so it reports active workflow, contract presence, failure count, latest verification status and suggested prevention action.
+- Updated Workflow Rail, Harness Rail, Diagram Rail, spec workflow and release docs for v0.7.0.
+
+## Security
+
+- Workflow verification and evidence remain local and do not publish packages, create GitHub releases or run destructive commands.
+- Diagram Rail validates local Markdown/Mermaid files only.
+- Harness contracts still validate by default without executing configured shell commands.
+
+## Notes
+
+- Historical npm backfill for v0.5.0, v0.5.1, v0.5.2 and v0.6.0 should use the `backfill` dist-tag only when the historical checkout builds, tests and publishes safely.
+- During v0.7.0 prep, v0.5.0 backfill was deferred because the historical checkout hit stale test failures and npm publish required a one-time password.
+- SotuRail still does not expose arbitrary shell execution through MCP.

package/docs/spec-driven-workflow.md

@@ -1,6 +1,6 @@
 # Spec-Driven Workflow
 
-SotuRail specs live under `.soturail/specs/`.
+SotuRail specs live under `.soturail/specs/`, and v0.7.0 connects them with Diagram Rail visual contracts.
 
 ```bash
 soturail spec new "feature idea"
@@ -11,63 +11,52 @@ soturail spec task list .soturail/specs/001-feature
 soturail spec task done .soturail/specs/001-feature 1
 ```
 
-v0.2.0 specs include:
+## Diagram-Driven Specs
 
-- `constitution.md`
-- `spec.md`
-- `plan.md`
-- `tasks.md`
-- `verification.md`
-- `context-budget.md`
-- `security-impact.md`
-
-## Planned Diagram-Driven Specs
-
-The v0.7+ roadmap can extend specs with Diagram Rail.
-
-The goal is to make visual contracts part of the spec workflow:
+The workflow is:
 
 ```txt
 Idea -> PRD -> .spec.md + Mermaid -> Tasks -> TDD -> Implementation -> Review -> Evidence
 ```
 
-A future `.spec.md` can include:
-
-- feature purpose;
-- requirements;
-- constraints;
-- Mermaid diagram;
-- decision matrix;
-- acceptance criteria;
-- test plan;
-- version/change notes.
-
-Possible future commands:
+v0.7.0 Diagram Rail commands:
 
 ```bash
+soturail diagram init
 soturail diagram new <feature>
 soturail diagram audit <file>
 soturail diagram validate
 soturail workflow diagram <id>
 ```
 
+## `.spec.md` Visual Contract
+
+Generated contracts include:
+
+- required nodes;
+- required transitions;
+- evidence links;
+- validation checklist;
+- known gaps.
+
+They are designed to be reviewed by humans and handed to agents as compact context. A `.spec.md` contract should make the intended behavior explicit before implementation.
+
 ## Why Diagrams Belong In Specs
 
 Mermaid diagrams are text-based, versionable and compact. They can show state transitions, workflows, sequence flows and policy decisions in a form that both humans and agents can inspect.
 
-A diagram should not replace tests or reviews. It should make the intended behavior explicit before implementation.
+A diagram should not replace tests or reviews. It should make the intended behavior explicit and then point to verification evidence.
+
+## Validation
 
-## Planned Validation
+`soturail diagram audit <file>` and `soturail diagram validate` catch basic local issues:
 
-A future diagram/spec validator should catch:
+- missing Mermaid blocks;
+- broken code fences;
+- unsupported Mermaid declarations;
+- missing `.spec.md` siblings;
+- workflow state diagrams without verification transitions.
 
-- invalid Mermaid syntax;
-- missing start or end states;
-- unreachable states;
-- unlabeled risky transitions;
-- missing acceptance criteria;
-- implementation without corresponding test plan;
-- release path without verification evidence;
-- policy flow without approve/reject state.
+The validator is intentionally lightweight. It is useful as a local rail, not as a full Mermaid parser.
 
 See [diagram-rail.md](diagram-rail.md) and [workflow-rail.md](workflow-rail.md).