soturail 1.1.0 → 1.2.0

package/docs/rate-limit-and-fallback-policy.md

@@ -0,0 +1,45 @@
+# Rate Limit And Fallback Policy
+
+This document describes the future SotuRail policy model for rate-limit and fallback guidance. It is documentation-first and local-first.
+
+## Policy Fields
+
+A future policy file could live at:
+
+```txt
+.soturail/policies/rate-limit-and-fallback.yaml
+```
+
+Example:
+
+```yaml
+hosts:
+  claude:
+    fallback: codex
+    contextFallback: markdown
+  cursor:
+    fallback: generic
+    contextFallback: cursor-rules-lite
+workflows:
+  default:
+    maxAgentTurns: 20
+    requireHandoffAfterMinutes: 30
+    requireApprovalForExternalCalls: true
+```
+
+## Fallback Types
+
+| Fallback | Meaning |
+| --- | --- |
+| host fallback | export the same SotuRail context to a different agent host |
+| format fallback | use Markdown/static files when MCP or skills are unsupported |
+| role fallback | reduce full workflow context to planner/executor/reviewer packs |
+| offline fallback | keep local docs/reports usable when no provider is available |
+
+## Non-Goals
+
+- no live billing control;
+- no provider account automation;
+- no quota bypass;
+- no traffic interception;
+- no promise that fallback preserves model behavior.

package/docs/releases/README.md

@@ -33,3 +33,4 @@ docs/releases/RELEASE_NOTES_vX.Y.Z.md
 - [v1.0.0](RELEASE_NOTES_v1.0.0.md)
 - [v1.0.1](RELEASE_NOTES_v1.0.1.md)
 - [v1.1.0](RELEASE_NOTES_v1.1.0.md)
+- [v1.2.0](RELEASE_NOTES_v1.2.0.md)

package/docs/releases/RELEASE_NOTES_v1.2.0.md

@@ -0,0 +1,43 @@
+# SotuRail v1.2.0
+
+SotuRail v1.2.0 adds Harness Lifecycle Rail and incorporates the v1.1.1 host-compatibility/ecosystem documentation polish. It keeps SotuRail CLI-first, npm-first, local-first, provider-agnostic and safe by default.
+
+## Added
+
+- `soturail harness init` for safe local lifecycle scaffolding that preserves existing files by default.
+- `soturail harness audit [--json]` for deterministic lifecycle readiness reports.
+- `soturail session start|end` for bounded local session state.
+- `soturail handoff generate` for local agent/host handoffs.
+- `soturail feature add|start|done|list` backed by `.soturail/state/feature_list.json`.
+- Hermes Agent and Odysseus ecosystem classifications.
+- Agent And Harness Synthesis, Security Boundaries, Harness Lifecycle Rail and proposed Conductor docs.
+- Deterministic host-export golden safety checks.
+
+## Boundaries
+
+- Hermes is documented as an agent runtime.
+- Odysseus is documented as a workspace/runtime/local-services stack.
+- SotuRail remains the local context/harness/governance layer.
+- SotuRail Conductor is proposed future work and is not implemented.
+- No cloud telemetry, required server, provider API key, destructive MCP tool or autonomous edit loop was added.
+
+## Verification
+
+```bash
+npm run typecheck
+npm run build
+npx vitest run tests/v120.test.ts
+npx vitest run tests/v110.test.ts
+npm test
+npm run release:check
+node dist/cli.js harness init
+node dist/cli.js harness audit --json
+node dist/cli.js feature list
+node dist/cli.js handoff generate
+```
+
+## Known Limitations
+
+- Spec/Design/Diagram expansion remains planned after the delivered lifecycle slice.
+- Dashboard lifecycle cards and a dedicated Host Fit Doctor alias remain planned; current host fit uses `agents matrix` and `agents doctor`.
+- Conductor commands are documentation-only and require a future approval-gated design.

package/docs/repo-docs-audit-2026-06-05.md

@@ -0,0 +1,55 @@
+# Repository Documentation Audit - 2026-06-05
+
+This audit records the documentation consistency check after the 2026 agent-harness synthesis update.
+
+## Scope
+
+Checked areas:
+
+- main docs entry points: `README.md`, `ROADMAP.md`, `CHANGELOG.md`;
+- planning parents: `docs/future-rails-index.md`, `docs/ecosystem-influences.md`, `docs/external-projects-audit.md`;
+- old related docs: workflow, context packs, report, observability, host docs, evaluation, harness, skills and governance;
+- new future rails: Agent QA, Evidence/Provenance, Agent Governance, Harness Lifecycle, Knowledge, Resilience, Host Router and Tasklet;
+- examples under `examples/workflows/`.
+
+## Result
+
+The 2026 ideas are now represented as documentation and roadmap items, not as implemented runtime features.
+
+Confirmed coverage:
+
+- QA/eval/golden checks are covered by `docs/agent-qa-rail.md`, `docs/eval-datasets.md`, `docs/golden-agent-tests.md` and `docs/llm-as-judge-policy.md`.
+- Validate/fix/verify/report pipeline ideas are covered by `docs/observability-rail.md`, `docs/workflow-rail.md` and `examples/workflows/agent-pipeline-workflow.md`.
+- OpenTracy-style trace, ledger, boundary, experiments and approval ideas are covered by `docs/agent-governance-rail.md`.
+- Harness engineering lifecycle is covered by `docs/harness-lifecycle-rail.md` and linked from `docs/harness-rail.md` and `docs/workflow-rail.md`.
+- ECC-style host/profile/doctor/audit/skills ideas are covered across `docs/future-rails-index.md`, `docs/host-compatibility-rail.md`, `docs/agent-hosts.md` and `docs/skill-rail-2.md`.
+- Feynman-style provenance is covered by `docs/evidence-provenance-rail.md` and linked from Report and Workflow docs.
+- book-to-skill-style document-to-skill packs are covered by `docs/knowledge-rail.md`, `docs/context-packs.md` and `docs/skill-rail-2.md`.
+- Tasklet ideas are covered by `docs/tasklet-rail.md` and linked from Context/Workflow/Skill planning docs.
+- 9Router ideas are safely mapped to `docs/host-router-rail.md`, without proxy, MITM, quota bypass or credential-routing scope.
+
+## Link Check
+
+Local Markdown links were checked after this update. No broken local Markdown links were found.
+
+## Boundaries Confirmed
+
+The documentation keeps the following boundaries explicit:
+
+- SotuRail is not SoturAI and does not contain trading/backtest/market-agent scope.
+- SotuRail is not a model provider, model router, proxy, MITM bridge or quota-bypass tool.
+- SotuRail remains local-first and provider-agnostic by default.
+- Optional LLM-as-judge and provider-backed checks are not default release gates.
+- Future self-improvement/governance loops require deterministic evals and human approval.
+- Security-oriented skills must stay defensive, scoped, evidence/report-focused and non-operational.
+
+## Remaining Work
+
+This audit does not claim the planned rails are implemented. The next work is code, fixtures and tests for the staged roadmap:
+
+- v1.1.1: docs polish, golden export checks and examples;
+- v1.2.0: harness lifecycle/session/feature commands;
+- v1.3.0: knowledge, evidence and local evaluation artifacts;
+- v1.4.0: Skill Rail 2.0 and tasklets;
+- v1.5.0: governance, cost, resilience and host-router reports;
+- v1.6.0: trace, ledger, approval gates and experiment workflow.

package/docs/report-rail.md

@@ -54,3 +54,15 @@ soturail brain stale --repair-plan
 soturail reverse claims ./src
 soturail brain consolidate --dry-run
 ```
+
+## Related Evidence, Eval And Governance Docs
+
+Report Rail is the parent surface where several future rails should become visible:
+
+- [`evidence-provenance-rail.md`](evidence-provenance-rail.md): report sidecars, source paths and `verified` / `unverified` / `blocked` / `inferred` statuses.
+- [`agent-qa-rail.md`](agent-qa-rail.md): dataset runs, golden export checks and regression summaries.
+- [`golden-agent-tests.md`](golden-agent-tests.md): deterministic host-export checks that can be summarized in reports.
+- [`agent-governance-rail.md`](agent-governance-rail.md): trace, ledger, approval and experiment status.
+- [`host-router-rail.md`](host-router-rail.md): context-format fallback decisions per host.
+
+A future report should not simply say an agent task is complete. It should say what evidence exists, what was checked, what is still inferred or blocked and which safe next command can improve confidence.

package/docs/resilience-rail.md

@@ -0,0 +1,48 @@
+# Resilience Rail
+
+Resilience Rail is a planned documentation/reporting surface for rate limits, retries, fallback policies and long-running agent workflow risk.
+
+It is inspired by multi-agent demos that break when APIs rate-limit, provider-specific parameters differ or workflows call tools repeatedly. SotuRail should not become a proxy or router. It should help users see and document the risk before handing work to an agent.
+
+## Goals
+
+- Identify missing retry/fallback documentation in agent workflows.
+- Warn when workflows rely on a single provider or host feature.
+- Record safe fallback formats for host exports.
+- Estimate context and workflow depth risk locally.
+- Keep all provider/cost notes assumption-based unless user supplies evidence.
+
+## Proposed Commands
+
+```bash
+soturail agents resilience doctor
+soturail agents provider matrix
+soturail governance fallback-policy
+soturail governance rate-limit
+soturail cost context
+```
+
+Names are not frozen; the first implementation can be report sections inside `status`, `report` or `agents doctor`.
+
+## Checks
+
+A resilience report can check:
+
+- workflow has no fallback path;
+- root docs mention a provider but no rate-limit policy;
+- provider-specific parameters are not documented;
+- long-running workflows lack pause/resume handoff;
+- context packs are too large for a target host;
+- MCP exposure is broad but no approval policy exists;
+- generated host export lacks a prompt-only fallback.
+
+## Safe Boundary
+
+SotuRail should not:
+
+- proxy model requests;
+- intercept IDE or browser traffic;
+- manage provider accounts;
+- bypass quotas;
+- claim unlimited free access;
+- patch provider requests automatically.

package/docs/schema-contracts.md

@@ -21,6 +21,9 @@ Stable v1 JSON artifacts are local files designed for humans, CI and coding agen
 - `soturail.agent-host-doctor.v1`
 - `soturail.agent-host-doctor-summary.v1`
 - `soturail.mcp.host-manifest.v1`
+- `soturail.harness.audit.v1`
+- `soturail.feature-list.v1`
+- `soturail.session.v1`
 
 ## Required Principles
 
@@ -51,3 +54,5 @@ soturail mcp resources host-manifest --host codex --json
 ```
 
 They must not grant mutation resources, shell execution through MCP, cloud telemetry or raw evidence exposure. See [host-matrix-schema.md](host-matrix-schema.md), [agent-export-contract.md](agent-export-contract.md) and [mcp-host-manifest.md](mcp-host-manifest.md).
+
+Harness Lifecycle JSON artifacts are optional until `soturail harness init` or `soturail session start` is run. Once present, schema checks validate their shape. See [Harness Lifecycle Rail](harness-lifecycle-rail.md).

package/docs/security-boundaries.md

@@ -0,0 +1,34 @@
+# Security Boundaries
+
+SotuRail is a local-first Context OS and harness layer. Its default role is to prepare, audit and export context, state, evidence, workflows and reports.
+
+## Safe Defaults
+
+- Local artifacts stay local unless the user explicitly moves or publishes them.
+- MCP report and host resources are read-only.
+- 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.
+- Publishing, release creation, destructive actions and external writes remain explicit user actions.
+
+## Out Of Scope
+
+SotuRail is not:
+
+- a model or cloud gateway;
+- a mandatory web server or hosted workspace;
+- a heavy autonomous agent runtime;
+- a destructive MCP tool provider;
+- a model-serving, GPU-management or personal productivity platform.
+
+## 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.
+
+## 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)

package/docs/skill-rail-2.md

@@ -2,6 +2,8 @@
 
 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.
@@ -97,3 +99,12 @@ They may provide:
 | 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/stable-command-surface.md

@@ -1,6 +1,6 @@
 # Stable Command Surface
 
-SotuRail v1.0.0 froze the first stable local Context OS surface. SotuRail v1.1.0 keeps that surface stable and adds Host Compatibility Rail commands for local exports, host doctors and read-only host manifests.
+SotuRail v1.0.0 froze the first stable local Context OS surface. SotuRail v1.1.0 kept that surface stable and added Host Compatibility Rail commands. SotuRail v1.2.0 adds the compatible local Harness Lifecycle command family.
 
 ## Stable Surface For v1.0
 
@@ -20,6 +20,11 @@ SotuRail v1.0.0 froze the first stable local Context OS surface. SotuRail v1.1.0
 - `soturail release check`
 - `soturail workflow`
 - `soturail harness`
+- `soturail harness init`
+- `soturail harness audit`
+- `soturail session start|end`
+- `soturail handoff generate`
+- `soturail feature add|start|done|list`
 - `soturail diagram`
 - `soturail agents`
 - `soturail agents matrix`
@@ -42,6 +47,7 @@ Stable means the command should remain local, documented, covered by smoke or co
 - Full Design Rail runtime.
 - Skill Rail 2.0 runtime.
 - Governance and cost runtime.
+- SotuRail Conductor commands and autonomous/runtime behavior.
 
 Experimental surfaces may change before promotion. They must stay local, optional and honest about limitations.
 
@@ -70,3 +76,6 @@ Future deprecations must name a replacement command, state the release that intr
 - [host matrix schema](host-matrix-schema.md)
 - [agent export contract](agent-export-contract.md)
 - [MCP host manifest](mcp-host-manifest.md)
+- [Harness Lifecycle Rail](harness-lifecycle-rail.md)
+- [Security Boundaries](security-boundaries.md)
+- [Conductor Mode](conductor-mode.md)

package/docs/tasklet-rail.md

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

package/docs/v1-contract.md

@@ -1,6 +1,6 @@
 # v1 Contract
 
-SotuRail v1.0.0 froze the first stable local Context OS surface. SotuRail v1.1.0 extends that surface with host-compatible exports and read-only host manifests while keeping experimental host runtimes outside the stable contract.
+SotuRail v1.0.0 froze the first stable local Context OS surface. SotuRail v1.1.0 extends that surface with host-compatible exports and read-only host manifests. SotuRail v1.2.0 adds compatible local harness lifecycle state while keeping experimental host runtimes and Conductor outside the stable contract.
 
 ## Stable Promise
 
@@ -11,11 +11,12 @@ SotuRail v1.0.0 froze the first stable local Context OS surface. SotuRail v1.1.0
 - Reports, dashboards and MCP report resources are local artifacts.
 - Read-only MCP report resources do not mutate files and do not expose shell execution.
 - Host manifests and agent exports are local artifacts. They do not grant mutation access by default.
+- Harness lifecycle initialization preserves existing files by default, and lifecycle audits do not execute verification commands.
 - TypeScript fallback remains mandatory. Native acceleration remains optional and benchmark-gated.
 
 ## Stable Commands
 
-The stable command surface is listed in [stable-command-surface.md](stable-command-surface.md). It includes status, reports, dashboard, observability, Project Brain, evaluation, benchmarks, native candidate reporting, baseline snapshots, release checks, workflow, harness, diagrams, agent exports, host doctors and read-only MCP report/host resources.
+The stable command surface is listed in [stable-command-surface.md](stable-command-surface.md). It includes status, reports, dashboard, observability, Project Brain, evaluation, benchmarks, native candidate reporting, baseline snapshots, release checks, workflow, harness lifecycle, diagrams, agent exports, host doctors and read-only MCP report/host resources.
 
 ## Non-Goals
 

package/docs/workflow-rail.md

@@ -195,3 +195,15 @@ Workflow evidence can now point to:
 ```
 
 These are still local artifacts. Workflow evidence does not upload telemetry and does not require a dashboard server.
+
+## Related Harness And Multi-Agent Workflow Docs
+
+Workflow Rail is the natural parent for the newer harness/session/task planning docs:
+
+- [`harness-lifecycle-rail.md`](harness-lifecycle-rail.md): instructions, state, verification, scope and session handoff.
+- [`multi-agent-workflow-templates.md`](multi-agent-workflow-templates.md): researcher, analyst, writer, verifier and reviewer role-pack templates.
+- [`evidence-provenance-rail.md`](evidence-provenance-rail.md): workflow evidence sidecars and verification status.
+- [`agent-governance-rail.md`](agent-governance-rail.md): trace, ledger and approval records for long-running workflows.
+- [`resilience-rail.md`](resilience-rail.md): retry/fallback/rate-limit policy notes for workflows that depend on external agent/model providers.
+
+These docs should keep SotuRail as the workflow/handoff/evidence layer. They should not turn it into a CrewAI, LangGraph or autonomous agent runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "1.1.0",
+  "version": "1.2.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": {