soturail 1.2.0 → 1.4.0

package/docs/{roadmap-docs-audit.md → roadmap/roadmap-docs-audit.md}

@@ -22,20 +22,20 @@ v1.5.0  Governance And Cost Rail
 | `ROADMAP.md` | Replaced the loose post-v0.10 direction with staged v1.0-v1.5 milestones and expanded the docs coverage matrix. |
 | `README.md` | Updated near-term roadmap and future docs links. |
 | `CHANGELOG.md` | Added unreleased documentation-change notes. |
-| `docs/future-rails-index.md` | Added the new planned rails and post-v1 version summaries. |
-| `docs/ecosystem-influences.md` | Added the external project audit summary and product-rule implications. |
-| `docs/comparisons.md` | Added a 2026 repository audit comparison table and roadmap mapping. |
-| `docs/external-projects-audit.md` | New detailed audit of referenced repositories and what SotuRail should absorb. |
-| `docs/host-compatibility-rail.md` | New v1.1 rail plan for OpenCode, Antigravity, Deep Agents-style, Claude, Codex, Cursor and generic hosts. |
-| `docs/design-rail.md` | New v1.2 design guidance plan based on local `DESIGN.md`, lint, diff and export ideas. |
-| `docs/knowledge-graph-rail.md` | New v1.3 graph plan connecting Project Brain, reverse specs, workflows, diagrams and releases. |
-| `docs/skill-rail-2.md` | New v1.4 domain skill plan with safety boundaries. |
-| `docs/governance-cost-rail.md` | New v1.5 governance/cost guardrail plan. |
-| `docs/stable-command-surface.md` | Added post-v1 candidate rail clarification. |
-| `docs/migration-v1.md` | Added post-v1 sequence notes. |
-| `docs/skill-rail.md` | Added pointer to Skill Rail 2.0. |
-| `docs/code-graph.md` | Added pointer to Knowledge Graph Rail. |
-| `docs/diagram-rail.md` | Added connection to Spec and Design Rail. |
+| `docs/roadmap/future-rails-index.md` | Added the new planned rails and post-v1 version summaries. |
+| `docs/ecosystem/ecosystem-influences.md` | Added the external project audit summary and product-rule implications. |
+| `docs/ecosystem/comparisons.md` | Added a 2026 repository audit comparison table and roadmap mapping. |
+| `docs/ecosystem/external-projects-audit.md` | New detailed audit of referenced repositories and what SotuRail should absorb. |
+| `docs/rails/hosts/host-compatibility-rail.md` | New v1.1 rail plan for OpenCode, Antigravity, Deep Agents-style, Claude, Codex, Cursor and generic hosts. |
+| `docs/rails/design/design-rail.md` | New v1.2 design guidance plan based on local `DESIGN.md`, lint, diff and export ideas. |
+| `docs/rails/knowledge/knowledge-graph-rail.md` | New v1.3 graph plan connecting Project Brain, reverse specs, workflows, diagrams and releases. |
+| `docs/rails/skills/skill-rail-2.md` | New v1.4 domain skill plan with safety boundaries. |
+| `docs/rails/governance/governance-cost-rail.md` | New v1.5 governance/cost guardrail plan. |
+| `docs/reference/commands/stable-command-surface.md` | Added post-v1 candidate rail clarification. |
+| `docs/getting-started/migration-v1.md` | Added post-v1 sequence notes. |
+| `docs/rails/skills/skill-rail.md` | Added pointer to Skill Rail 2.0. |
+| `docs/rails/knowledge/code-graph.md` | Added pointer to Knowledge Graph Rail. |
+| `docs/rails/design/diagram-rail.md` | Added connection to Spec and Design Rail. |
 
 ## Audit Result
 

package/docs/{roadmap-harness-diagram-payload-addendum.md → roadmap/roadmap-harness-diagram-payload-addendum.md}

@@ -140,7 +140,7 @@ soturail context pack --target codex --format markdown
 soturail context pack --target mcp --format json
 soturail format file.json --to tagged
 soturail format file.json --to toon
-soturail format compare docs/usage.md --formats markdown,tagged,json,toon
+soturail format compare docs/getting-started/usage.md --formats markdown,tagged,json,toon
 soturail validate json config.json --strict
 ```
 
@@ -289,12 +289,12 @@ Connect reports and visual output:
 
 ## Related Docs
 
-- [Harness Rail](harness-rail.md)
-- [Policy Rail](policy-rail.md)
-- [Diagram Rail](diagram-rail.md)
-- [Structured Payload Rail](structured-payload-rail.md)
-- [Workflow Rail](workflow-rail.md)
-- [Context Packs](context-packs.md)
-- [Security Model](security-model.md)
-- [Ecosystem Influences](ecosystem-influences.md)
-- [Comparisons](comparisons.md)
+- [Harness Rail](../rails/harness/harness-rail.md)
+- [Policy Rail](../rails/governance/policy-rail.md)
+- [Diagram Rail](../rails/design/diagram-rail.md)
+- [Structured Payload Rail](../rails/context/structured-payload-rail.md)
+- [Workflow Rail](../rails/harness/workflow-rail.md)
+- [Context Packs](../rails/context/context-packs.md)
+- [Security Model](../security/security-model.md)
+- [Ecosystem Influences](../ecosystem/ecosystem-influences.md)
+- [Comparisons](../ecosystem/comparisons.md)

package/docs/{security-boundaries.md → security/security-boundaries.md}

@@ -9,6 +9,9 @@ SotuRail is a local-first Context OS and harness layer. Its default role is to p
 - Harness audits validate files without executing verification commands.
 - Handoffs include changed-file names and summaries, not private shell history.
 - Reports and exports use secret redaction helpers.
+- Knowledge compilation accepts only local project sources and makes no model or embedding calls.
+- Evidence verification does not silently execute commands or invent proof.
+- Tasklet runs are simulations and never execute shell commands.
 - Publishing, release creation, destructive actions and external writes remain explicit user actions.
 
 ## Out Of Scope
@@ -23,12 +26,12 @@ SotuRail is not:
 
 ## Future Conductor Boundary
 
-The proposed [SotuRail Conductor](conductor-mode.md) may plan, audit, propose and verify local work only behind explicit approval gates. It must not introduce an unreviewed edit loop, central shell agent, cloud agent or hidden external service.
+The proposed [SotuRail Conductor](../ecosystem/conductor-mode.md) may plan, audit, propose and verify local work only behind explicit approval gates. It must not introduce an unreviewed edit loop, central shell agent, cloud agent or hidden external service.
 
 ## Related Docs
 
 - [Security Model](security-model.md)
-- [MCP](mcp.md)
-- [Harness Lifecycle Rail](harness-lifecycle-rail.md)
-- [Host Compatibility Rail](host-compatibility-rail.md)
-- [Observability Rail](observability-rail.md)
+- [MCP](../rails/hosts/mcp.md)
+- [Harness Lifecycle Rail](../rails/harness/harness-lifecycle-rail.md)
+- [Host Compatibility Rail](../rails/hosts/host-compatibility-rail.md)
+- [Observability Rail](../architecture/observability-rail.md)

package/docs/{security-model.md → security/security-model.md}

@@ -86,7 +86,7 @@ R13 warn when JSON payloads have duplicate keys or unsafe ambiguity
 
 Policy decisions should eventually be attached to workflow evidence, release evidence and MCP exposure reports.
 
-See [policy-rail.md](policy-rail.md).
+See [policy-rail.md](../rails/governance/policy-rail.md).
 
 ## Planned MCP Exposure Report
 

package/docs/{tutorial-codex.md → tutorials/tutorial-codex.md}

@@ -19,4 +19,4 @@ Keep `AGENTS.md` short and point to:
 - `.soturail/context/` for selected context;
 - `.soturail/context/role-packs/` for task role context;
 - `.soturail/reports/` and `.soturail/eval/` for evidence;
-- `docs/policy-rail.md` for risky actions.
+- `docs/rails/governance/policy-rail.md` for risky actions.

package/examples/workflows/agent-pipeline-workflow.md

@@ -0,0 +1,11 @@
+# Agent Pipeline Workflow
+
+This local-first workflow demonstrates a safe validate, fix, verify and report loop.
+
+1. Collect source-backed evidence with `soturail evidence collect`.
+2. Review the report before making changes.
+3. Apply an explicitly approved change outside SotuRail.
+4. Verify evidence with `soturail evidence verify`.
+5. Export a concise report for humans or agents.
+
+SotuRail prepares context and evidence. It does not autonomously edit the project or execute arbitrary shell commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "1.2.0",
+  "version": "1.4.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": {
@@ -22,6 +22,7 @@
     "prepack": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "docs:check": "node scripts/check-doc-links.mjs",
     "build:native": "cargo build --manifest-path native/soturail-native/Cargo.toml --release",
     "test:native": "cargo test --manifest-path native/soturail-native/Cargo.toml",
     "build:all": "npm run build && npm run build:native",

package/docs/agent-qa-rail.md

@@ -1,92 +0,0 @@
-# Agent QA Rail
-
-Agent QA Rail is a proposed future rail for testing SotuRail-generated agent artifacts like software outputs, not magic prompts.
-
-It is inspired by small QA-agent repos that combine automated tests, fixed datasets, scoring, observability and CI. SotuRail should keep the useful discipline while staying local-first, host-independent and deterministic by default.
-
-## Goals
-
-- Test host exports, context packs, skills, rules, workflows, evidence packs and reports.
-- Catch regressions in agent-facing files before release.
-- Keep default evals offline and cheap.
-- Allow optional provider-backed judging only when explicitly requested.
-- Generate JSON and Markdown reports that can be attached to release evidence.
-
-## Proposed Commands
-
-```bash
-soturail eval dataset init
-soturail eval dataset run
-soturail eval golden
-soturail eval regression
-soturail eval report
-soturail eval doctor
-soturail eval judge --optional
-```
-
-These commands can begin as report-only or fixture-only surfaces before becoming full command implementations.
-
-## Local Artifact Layout
-
-```txt
-.soturail/evals/
-  datasets/
-    host-compatibility.json
-    context-quality.json
-    skill-routing.json
-  golden/
-    claude-export.md
-    codex-export.md
-    cursor-rules.md
-  runs/
-    latest.json
-  reports/
-    latest.md
-```
-
-## Deterministic Checks First
-
-Default checks should not call real LLMs or external services.
-
-Examples:
-
-- export is not empty;
-- export contains safe next commands;
-- export includes required policy warnings;
-- export does not contain secrets;
-- export does not contain unrelated project names such as SoturAI when the target is SotuRail;
-- JSON artifacts parse successfully;
-- duplicate JSON keys are detected where relevant;
-- host matrix fields are present;
-- MCP exports keep read-only mutation boundaries;
-- reports include evidence paths and verification status;
-- generated docs keep local-first and no-cloud-by-default claims honest.
-
-## Optional LLM-As-Judge
-
-Provider-backed judges can be useful for hallucination or answer-quality review, but they must not be the default release gate.
-
-Policy:
-
-```txt
-Offline fixtures are release-blocking.
-LLM-as-judge is optional, explicit and non-blocking unless a project opts in.
-Provider outputs must be stored as separate integration evidence.
-```
-
-## CI Split
-
-Recommended tiers:
-
-| Tier | Network | Release blocking | Purpose |
-| --- | --- | --- | --- |
-| unit/offline | no | yes | deterministic docs, schemas, exports and fixtures |
-| integration | optional | no by default | provider/API behavior, external host smoke |
-| nightly | optional | no by default | long-running or flaky judge/eval experiments |
-
-## Non-Goals
-
-- no required Groq, OpenAI, Anthropic, LangFuse or other provider;
-- no real model calls in default tests;
-- no scoring metric based only on marketing-friendly numbers;
-- no claim that passing evals proves a real agent will always behave well.

package/docs/evidence-provenance-rail.md

@@ -1,70 +0,0 @@
-# Evidence And Provenance Rail
-
-Evidence And Provenance Rail is a planned expansion that makes SotuRail reports more auditable.
-
-The core idea:
-
-```txt
-Every important output should say what it used, what it changed, what was verified and what is still uncertain.
-```
-
-## Provenance Sidecars
-
-Reports can have sidecar files:
-
-```txt
-.soturail/reports/<slug>.md
-.soturail/reports/<slug>.provenance.md
-```
-
-Per-run evidence can be grouped as:
-
-```txt
-.soturail/evidence/<run-id>/
-  report.md
-  provenance.md
-  tests.log
-  files-read.json
-  files-changed.json
-  verification.json
-```
-
-## Verification Status Values
-
-Use explicit status labels:
-
-| Status | Meaning |
-| --- | --- |
-| `verified` | backed by local file, command, test, schema or report evidence |
-| `unverified` | plausible but not proven by available evidence |
-| `blocked` | cannot be verified due to missing file, command failure or unavailable dependency |
-| `inferred` | derived from available evidence but not directly stated |
-
-## Proposed Commands
-
-```bash
-soturail evidence collect
-soturail evidence verify
-soturail evidence report
-soturail sources compare
-soturail review report
-```
-
-## Report Requirements
-
-Agent-readable reports should include:
-
-- source paths;
-- command/eval/report ids;
-- changed files;
-- verification status;
-- missing evidence;
-- safe next commands;
-- redaction status.
-
-## Non-Goals
-
-- no fake citations;
-- no unsupported certainty;
-- no cloud evidence store by default;
-- no raw secret exposure in provenance files.

package/docs/knowledge-rail.md

@@ -1,76 +0,0 @@
-# Knowledge Rail
-
-Knowledge Rail is a planned future surface for compiling project documentation into small, on-demand knowledge packs for coding agents.
-
-It is inspired by document-to-skill workflows: extract structure, not a giant summary.
-
-## Goal
-
-Turn docs, specs, READMEs, ADRs, notes and technical references into local agent-usable knowledge:
-
-```txt
-source docs -> topic index -> SKILL.md -> topics -> glossary -> patterns -> cheatsheet -> provenance
-```
-
-## Proposed Commands
-
-```bash
-soturail knowledge ingest ./docs ./README.md ./architecture.md
-soturail knowledge estimate ./docs
-soturail knowledge compile --mode on-demand
-soturail knowledge update project-brain ./new-docs
-soturail knowledge verify
-soturail skill build ./docs --name project-architecture
-soturail skill fold-in project-architecture ./ADR-004.md
-soturail skill export --target claude
-```
-
-## Local Layout
-
-```txt
-.soturail/knowledge/<name>/
-  SKILL.md
-  topics/
-    architecture.md
-    testing.md
-    release.md
-  glossary.md
-  patterns.md
-  cheatsheet.md
-  source-map.json
-  metadata.json
-```
-
-## On-Demand Context
-
-Instead of loading all docs into every prompt, an export can say:
-
-```txt
-Read .soturail/knowledge/project/SKILL.md first.
-For release tasks, read topics/release.md.
-For testing tasks, read topics/testing.md.
-Do not load unrelated topics unless needed.
-```
-
-## Metadata
-
-A knowledge pack should record:
-
-- source paths;
-- extraction date;
-- token estimate;
-- topic list;
-- source map;
-- verification status;
-- update/fold-in history.
-
-## Copyright And Sharing Boundary
-
-Knowledge packs generated from private or copyrighted material should stay local unless the user has rights to redistribute them. SotuRail should prefer synthesized structure and references over copying large source text.
-
-## Non-Goals
-
-- no vector database required;
-- no cloud embeddings required;
-- no publishing third-party book content by default;
-- no replacing Project Brain or Knowledge Graph Rail. Knowledge Rail feeds them with organized source material.

package/docs/skill-rail-2.md

@@ -1,110 +0,0 @@
-# Skill Rail 2.0 And Domain Skill Packs
-
-Skill Rail 2.0 is the planned v1.4.x direction for safer, smaller, domain-aware skills that can be exported to different agent hosts.
-
-Hermes Agent's skill self-improvement model is useful inspiration, but SotuRail skills remain reviewed local operating procedures rather than self-modifying agent behavior. Any future improvement proposal must preserve evidence, safety checks and human approval.
-
-## Goal
-
-Move from generic skills to reviewed domain skill packs with metadata, fixtures, reports, role-aware exports and explicit safety boundaries.
-
-## Planned Commands
-
-```bash
-soturail skills template typescript-cli
-soturail skills template java-review
-soturail skills template php-review
-soturail skills template docs-review
-soturail skills template release-manager
-soturail skills template accessibility-review
-soturail skills template security-review
-soturail skills lint
-soturail skills eval
-soturail skills report
-soturail skills export --agent opencode
-soturail skills export --agent codex
-soturail skills export --agent claude
-soturail skills export --agent generic
-```
-
-## Domain Skill Structure
-
-```txt
-.soturail/skills/<skill-id>/
-  skill.yml
-  SKILL.md
-  examples/
-  fixtures/
-  report-template.md
-  safety.md
-  validators/
-```
-
-## Required Metadata
-
-- skill id;
-- name;
-- domain;
-- supported hosts;
-- risk level;
-- required evidence;
-- allowed commands;
-- blocked commands;
-- human approval requirements;
-- verification checklist;
-- output schema or report format.
-
-## Domain Skill Report Format
-
-A skill report should separate:
-
-- finding;
-- severity;
-- confidence;
-- evidence path;
-- affected files;
-- safe next command;
-- human review requirement;
-- false-positive note where relevant.
-
-## Security Boundary
-
-Security-related skills must stay defensive and authorization-aware.
-
-They must not provide:
-
-- exploit or bypass instructions;
-- credential theft;
-- malware or evasion logic;
-- unauthorized access steps;
-- instructions to hide activity;
-- destructive actions without explicit human approval.
-
-They may provide:
-
-- scope checklist;
-- safe evidence collection guidance;
-- non-operational vulnerability summaries;
-- remediation steps;
-- redaction and reporting guidance;
-- policy gates before risky tools.
-
-## Relationship To Existing Rails
-
-| Existing rail | Skill Rail 2.0 connection |
-| --- | --- |
-| Policy Rail | risk and approval checks |
-| Report Rail | skill findings and evidence summaries |
-| Host Compatibility Rail | host-aware skill exports |
-| Workflow Rail | phase-specific skills |
-| Evaluation Suite | fixture-based skill quality checks |
-| Project Brain | repeated findings can become rules or stale evidence |
-
-## Knowledge-To-Skill And Tasklet Expansion
-
-Future Skill Rail 2.0 work now includes:
-
-- [`knowledge-rail.md`](knowledge-rail.md) for compiling docs/specs/notes into on-demand skill knowledge packs;
-- [`tasklet-rail.md`](tasklet-rail.md) for small reusable local task templates.
-
-The key principle is progressive disclosure: export a small `SKILL.md`/tasklet entry point first and load topic files only when needed.

package/docs/tasklet-rail.md

@@ -1,62 +0,0 @@
-# Tasklet Rail
-
-Tasklet Rail is a proposed small-task template layer. The Tasklet.ai public site did not expose enough technical detail during review, so SotuRail only absorbs the generic idea of reusable tiny tasks.
-
-## Definition
-
-A tasklet is a small local operating procedure for one common agent task.
-
-Examples:
-
-```txt
-review-code
-update-docs
-generate-tests
-prepare-release
-fix-typescript-error
-generate-handoff
-```
-
-## Proposed Commands
-
-```bash
-soturail tasklet create "review-pr"
-soturail tasklet run "generate-handoff"
-soturail tasklet list
-soturail tasklet export --target claude
-```
-
-## Tasklet Shape
-
-```yaml
-id: review-pr
-purpose: Review changed files and produce evidence-backed feedback.
-inputs:
-  - git diff
-  - tests report
-allowedRead:
-  - src/**
-  - tests/**
-allowedWrite:
-  - .soturail/reports/**
-verification:
-  - npm test
-handoff:
-  - report.md
-  - provenance.md
-```
-
-## Relationship To Skills
-
-```txt
-Skill = reusable domain operating procedure.
-Tasklet = small runnable task template that may use skills, rules and context packs.
-Workflow = multi-step lifecycle with evidence and verification.
-```
-
-## Non-Goals
-
-- no cloud task runner by default;
-- no external queue required;
-- no hidden execution;
-- no destructive action without policy approval.