soturail 1.1.0 → 1.2.0

package/docs/agent-governance-rail.md

@@ -0,0 +1,89 @@
+# Agent Governance And Evolution Rail
+
+Agent Governance And Evolution Rail is a later-stage direction for controlled improvement loops around SotuRail artifacts and agent-facing harnesses.
+
+It absorbs ideas from self-improving harness systems while keeping SotuRail conservative:
+
+```txt
+propose -> eval -> approve -> apply
+```
+
+No future loop should silently edit projects or bypass human approval.
+
+## Planned Concepts
+
+### Agent Boundary
+
+A future policy can define what an agent may change, read or append:
+
+```yaml
+mutable:
+  - src/**
+  - tests/**
+  - docs/**
+read_only:
+  - package.json
+  - package-lock.json
+  - .github/**
+  - .env*
+append_only:
+  - .soturail/logs/**
+  - .soturail/ledger/**
+  - .soturail/reports/**
+rules:
+  require_tests_before_apply: true
+  require_no_context_regression: true
+  one_patch_per_run: true
+```
+
+### Ledger
+
+Append-only records can explain decisions:
+
+```json
+{
+  "run_id": "run_2026_06_05_001",
+  "agent": "claude-code",
+  "action": "proposed_patch",
+  "files_touched": ["src/context.ts"],
+  "approved": false,
+  "tests_passed": true
+}
+```
+
+### Experiments
+
+```txt
+.soturail/experiments/
+  candidates/
+  results/
+  accepted/
+  rejected/
+```
+
+Candidate changes should be compared through deterministic evals before approval.
+
+## Proposed Commands
+
+```bash
+soturail trace start
+soturail trace stop
+soturail trace list
+soturail trace show <id>
+soturail ledger list
+soturail experiment create "improve context ranking"
+soturail experiment run
+soturail experiment compare
+soturail improve propose
+soturail improve eval
+soturail improve approve
+soturail improve apply
+```
+
+## Non-Goals
+
+- no autonomous self-modifying runtime by default;
+- no hosted multi-tenant control plane;
+- no required Anthropic/OpenAI/Groq provider;
+- no destructive MCP tools;
+- no applying patches without reviewable diff and approval.

package/docs/agent-harness-synthesis-2026.md

@@ -0,0 +1,101 @@
+# Agent And Harness Synthesis 2026
+
+This document merges the latest external-repository review into one SotuRail planning note. It distinguishes agent runtimes from harness/context infrastructure so SotuRail can absorb useful ecosystem patterns without losing its product boundary. It is not a dependency list and it is not a claim that SotuRail vendors, wraps or outperforms those projects.
+
+SotuRail remains:
+
+```txt
+Local-first Context OS for AI coding agents.
+It prepares context, memory, policies, skills, workflows, evidence, reports and host exports.
+It is not the model, not the coding agent, not a proxy, not a cloud gateway and not a trading/finance agent.
+```
+
+## Classification
+
+```txt
+Agent = objective + model + tools + state/memory + decision/execution loop.
+Non-agent = skill, toolkit, toolset, compressor, router, runtime helper, context, prompt, rule or adapter.
+```
+
+Hermes Agent is a self-improving agent runtime with a model, tools, memory, execution loop, skills, routines, subagents and multiple interfaces.
+
+Odysseus is broader: a self-hosted AI workspace combining an agent runtime, chat UI, local services, model management, memory, skills, research and personal workspace features.
+
+SotuRail is different:
+
+```txt
+Hermes = self-improving personal agent runtime
+Odysseus = workspace + runtime + agent + UI + local services
+SotuRail = local-first context/harness OS for preparing and governing agents
+```
+
+Toolkits, compressors and routers should not be described as agents unless they own a model-plus-tool execution loop.
+
+## Projects Reviewed In This Wave
+
+| Project or product | Useful pattern | SotuRail direction |
+| --- | --- | --- |
+| Hermes Agent | self-improving runtime, trajectory compression, routines and role packs | context optimization, bounded sessions and safe tool profiles |
+| Odysseus | workspace, runtime, UI and local-service integration | local workspace organization without a required server |
+| `ijmf/qa-ai-agent` | agent QA with tests, datasets, observability and CI | Agent QA Rail, golden checks, deterministic evals |
+| `duckdogersxd/Orquestrando-Agents-CrewAI` | multi-agent roles, fallback, retry and throttling lessons | role-pack templates and Resilience Rail docs |
+| `CaioTakedaIA/agentesdeIA` | validate -> fix -> revalidate -> analyze pipeline with visible events | pipeline recorder, evidence per stage and dashboard timeline |
+| `OpenTracy/OpenTracy` | propose -> eval -> approve -> apply loop, traces, ledger, candidates | Agent Governance / Evolution Rail |
+| `walkinglabs/learn-harness-engineering` | instructions, state, verification, scope and session lifecycle | Harness Lifecycle Rail and feature/session handoff commands |
+| `affaan-m/ECC` | install profiles, doctor/repair/uninstall, skills/rules/hooks, multi-host packaging | install state, harness audit, skills/rules profiles and host exports |
+| `companion-inc/feynman` | provenance sidecars, verified/unverified/blocked/inferred status, file-based handoff | Evidence and Provenance Rail |
+| `virgiliojr94/book-to-skill` | document/book -> skill, on-demand chapters, glossary, patterns and cheatsheet | Knowledge Rail and skill build/fold-in |
+| Tasklet.ai | limited public information; reusable small tasks as a concept | Tasklet Rail as local task templates only |
+| 9Router | multi-host routing metaphor, token/context optimization, local dashboard | Host Router Rail for context exports; no proxy/MITM |
+
+## Patterns To Absorb
+
+- Context and trajectory compression with recoverable evidence.
+- Session search and bounded handoffs.
+- Toolset profiles and role packs.
+- Tasklet/workflow templates.
+- Host Fit Doctor and compatibility notes.
+- Dashboard cards for Context Packs, Memory, Reports, Evidence, Workflows, Skills, Tasklets and Handoffs.
+- Local-first privacy and explicit security boundaries.
+- Doctor/audit/repair/uninstall paths for generated artifacts.
+- Provenance, evidence and verification status for reports.
+
+## Patterns To Avoid
+
+- Mandatory web servers or hosted workspaces.
+- Model serving and GPU management.
+- Central shell execution or destructive MCP tools.
+- Provider-specific dependencies and hidden external services.
+- Unreviewed autonomous edit loops.
+- Proxy, MITM, billing, unlimited-free or cloud telemetry claims.
+- Interception of IDE traffic, browser sessions, cookies or provider credentials.
+
+## Rail Map
+
+| New or expanded rail | Main purpose | Inspired by |
+| --- | --- | --- |
+| Agent QA Rail | datasets, golden checks, regression reports and optional judges | `qa-ai-agent` |
+| Resilience Rail | rate-limit, retry, fallback and provider-risk policy docs | CrewAI/LiteLLM-style repo, 9Router concept |
+| Pipeline Recorder | record agent-stage events and evidence packs | `agentesdeIA` |
+| Agent Governance Rail | trace, ledger, candidates, approval gate and improve loop | OpenTracy |
+| Harness Lifecycle Rail | init, audit, feature list, session start/end and handoff | learn-harness-engineering, Hermes, Odysseus |
+| Install/Profile Rail | profile-based install state, doctor, repair and uninstall | ECC |
+| Evidence/Provenance Rail | provenance sidecars and verification status | Feynman |
+| Knowledge Rail | document ingestion into on-demand skills | book-to-skill |
+| Host Router Rail | one context source exported to many hosts with fallback formats | 9Router metaphor |
+| Tasklet Rail | small reusable local task templates | Tasklet concept |
+
+## SotuRail Direction
+
+v1.2.0 implements Harness Lifecycle Rail for local state, audits, feature tracking, sessions and handoffs. The optional [Conductor Mode](conductor-mode.md) remains proposed future work behind approval gates.
+
+```txt
+v1.1.1  Host Compatibility Polish, docs synthesis, golden export checks
+v1.2.0  Harness Lifecycle Rail plus staged Spec, Design and Diagram work
+v1.3.0  Knowledge, Evidence and Evaluation Rail
+v1.4.0  Skill Rail 2.0, Knowledge-to-Skill and Tasklet Packs
+v1.5.0  Governance, Cost, Resilience and Host Router Rail
+v1.6.0  Agent Governance / Evolution Rail
+```
+
+The exact future command names are not frozen. Related: [Ecosystem Influences](ecosystem-influences.md), [External Projects Audit](external-projects-audit.md), [Harness Lifecycle Rail](harness-lifecycle-rail.md), [Security Boundaries](security-boundaries.md).

package/docs/agent-hosts.md

@@ -36,3 +36,15 @@ soturail mcp resources host-manifest --host codex
 No host row enables destructive MCP tools or arbitrary shell execution. Config writes remain dry-run or review-first. Use `soturail report agent --agent <host>`, `soturail agents doctor --host <host>` and review the output before agent handoff.
 
 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).
+
+## Related Host Router And Resilience Docs
+
+Host docs are connected to several planned rails:
+
+- [`host-router-rail.md`](host-router-rail.md): one local context source exported into host-specific formats with safe fallback.
+- [`host-compatibility-rail.md`](host-compatibility-rail.md): current host matrix, schema and export contracts.
+- [`rate-limit-and-fallback-policy.md`](rate-limit-and-fallback-policy.md): local documentation shape for retry/fallback/rate-limit expectations.
+- [`resilience-rail.md`](resilience-rail.md): provider and workflow-risk warnings without proxying model traffic.
+- [`agent-qa-rail.md`](agent-qa-rail.md): golden checks for host exports.
+
+SotuRail host support means context, instruction, report, skill and MCP-resource packaging. It does not mean intercepting IDE traffic, reusing browser tokens, routing model requests or bypassing provider quotas.

package/docs/agent-qa-rail.md

@@ -0,0 +1,92 @@
+# 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/agents.md

@@ -263,11 +263,19 @@ Those exports should explain:
 - which payload format was chosen;
 - whether any long context was offloaded.
 
-## Future Harness And Handoff Support
+## Harness And Handoff Support
 
-SotuRail can support disciplined handoffs without becoming the agent runtime.
+SotuRail supports disciplined local handoffs without becoming the agent runtime:
 
-Possible future commands:
+```bash
+soturail harness init
+soturail harness audit
+soturail session start "objective"
+soturail handoff generate
+soturail feature list
+```
+
+Additional role-to-role host handoff aliases remain future possibilities:
 
 ```bash
 soturail agents handoff --from planner --to executor
@@ -285,3 +293,5 @@ A handoff should include:
 - evidence pack pointers;
 - raw/offload recovery IDs;
 - next safe command suggestions.
+
+Current handoffs are written to `.soturail/state/session-handoff.md`. They include bounded local state and changed-file names, do not read private shell history and do not run verification commands.

package/docs/conductor-mode.md

@@ -0,0 +1,44 @@
+# SotuRail Conductor Mode
+
+Status: **Proposed future optional mode. Not implemented in v1.2.0.**
+
+SotuRail Core remains the CLI-first, npm-first, local-first Context OS and harness layer. A future optional mode called **SotuRail Conductor** may coordinate planning, verification and documentation workflows without replacing agent hosts.
+
+```txt
+SotuRail
+|-- Core
+|   |-- context
+|   |-- memory
+|   |-- reports
+|   |-- workflows
+|   |-- evidence
+|   |-- host exports
+|   `-- dashboard
+`-- Future optional Conductor mode
+    |-- planner
+    |-- verifier
+    |-- reviewer
+    |-- tasklet runner
+    |-- evidence collector
+    `-- approval gate
+```
+
+## Proposed Commands
+
+These commands are documentation-only and do not currently exist:
+
+```bash
+soturail conductor plan
+soturail conductor audit
+soturail conductor propose
+soturail conductor verify
+soturail conductor apply --approved
+```
+
+## Safe Capability Boundary
+
+A future Conductor may read a repository, create plans and tasklets, generate reports, validate links, compare host exports and propose patches. Applying a patch must require explicit approval.
+
+It must not become a chat product, unbounded fix-everything loop, central shell agent, browser agent, cloud agent or provider-specific runtime.
+
+See [Security Boundaries](security-boundaries.md), [Harness Lifecycle Rail](harness-lifecycle-rail.md) and [Future Rails Index](future-rails-index.md).

package/docs/context-packs.md

@@ -266,6 +266,12 @@ Possible future diagram context:
 
 See [diagram-rail.md](diagram-rail.md).
 
+## Lifecycle And Context Budget
+
+Harness Lifecycle handoffs should stay bounded. Prefer the active objective, feature state, changed-file names, verification status, blockers and next commands over copying full session history.
+
+Hermes-style trajectory compression is useful inspiration only when raw evidence remains recoverable. Odysseus-style workspace breadth should not cause every local artifact to enter every context pack. Use `context budget`, role packs, offload pointers and host-specific exports to keep handoffs focused.
+
 ## Quality Rules
 
 Context selection, formatting and role packs should preserve:
@@ -280,3 +286,15 @@ Context selection, formatting and role packs should preserve:
 - raw recovery hints.
 
 If pruning or formatting would remove required evidence, SotuRail should report that pruning was not effective rather than pretending the context is sufficient.
+
+## Related Context Routing And Knowledge Docs
+
+Context Packs connect directly to the newer knowledge and host-routing plans:
+
+- [`knowledge-rail.md`](knowledge-rail.md): compile docs/specs/notes into on-demand topic packs instead of loading everything into one prompt.
+- [`host-router-rail.md`](host-router-rail.md): translate one local context source into host-specific exports for Claude, Codex, Cursor, OpenCode, Gemini and generic Markdown.
+- [`tasklet-rail.md`](tasklet-rail.md): attach a small task template to a minimal context pack.
+- [`resilience-rail.md`](resilience-rail.md): warn when a context pack implies expensive, provider-dependent or long-running workflows.
+- [`agent-qa-rail.md`](agent-qa-rail.md): test whether compact/role-specific context packs preserve required facts.
+
+The key rule is progressive disclosure: SotuRail should send the smallest useful context first and keep large raw evidence recoverable by path, id or offload pointer.

package/docs/dashboard-rail.md

@@ -4,6 +4,12 @@ v1.0.0 keeps the dashboard static and local. There is no server requirement, no
 
 Dashboard Rail builds a static local HTML dashboard from report and status artifacts.
 
+## Lifecycle Cards
+
+Odysseus-style local workspace organization is useful dashboard inspiration, but SotuRail remains static and server-free by default. Future dashboard polish may surface bounded cards for Context Packs, Memory, Reports, Evidence, Workflows, Host Compatibility, Skills, Tasklets and Handoffs from existing local artifacts.
+
+Harness Lifecycle state is currently available under `.soturail/state/`; dedicated dashboard cards remain planned.
+
 ```bash
 soturail dashboard build
 soturail dashboard open

package/docs/ecosystem-influences.md

@@ -46,6 +46,8 @@ SotuRail should remain the local rail layer that prepares those artifacts for an
 | `murillo-romeu/sonar-totvs` | domain-specific skill/report | Skill Rail 2.0 |
 | `Acauhi99/opencode-agent-system` | OpenCode agent system packaging | OpenCode export and role/skill packaging |
 | `ComposioHQ/composio` | tool/provider integration ecosystem | compatibility manifests, not marketplace cloning |
+| Hermes Agent | self-improving agent runtime, skills, routines, subagents and trajectory compression | context optimization, role packs and tasklet inspiration without becoming the runtime |
+| Odysseus | self-hosted AI workspace, runtime, UI and local services | local dashboard, host-fit and evidence-report inspiration without adding a required server |
 
 ### Product Rule
 
@@ -57,6 +59,19 @@ SotuRail should absorb the durable patterns and avoid cloning products:
 - Skill Rail 2.0 should package safe domain skills but not hide risky commands.
 - Governance And Cost Rail should warn about context/workflow risk but not claim provider billing accuracy without evidence.
 
+### Hermes Agent And Odysseus Boundary
+
+Hermes and Odysseus reinforce why SotuRail must distinguish agents from harness components:
+
+```txt
+Agent = model + tools + state/memory + decision/execution loop.
+SotuRail = local context, harness, evidence, policy and host handoff layer.
+```
+
+Hermes contributes useful inspiration for trajectory compression, session search, toolset profiles, skills and subagent role packs. Odysseus contributes useful inspiration for local dashboard cards, host fit checks, visual evidence reports and privacy/security documentation.
+
+SotuRail does not copy their runtime, chat UI, model serving, local-service stack or central shell behavior. See [`agent-harness-synthesis-2026.md`](agent-harness-synthesis-2026.md), [`security-boundaries.md`](security-boundaries.md) and [`conductor-mode.md`](conductor-mode.md).
+
 ## 2026 Agent Runtime Update
 
 Newer agent hosts are converging around the same architecture: a coding agent surface, local or cloud workspaces, MCP or tool adapters, reusable skills/instructions, hooks/approvals, context budgeting and evidence that proves the task is actually complete.
@@ -472,3 +487,53 @@ These ideas are intentionally staged after the core rails are stable:
 15. **Auth Rail**: optional agent-readable auth docs and redaction checks.
 16. **UI/Report Rail**: local HTML dashboard and optional MCP Apps/AG-UI-style event outputs.
 17. **Gateway Lite**: local event routing only after memory, context selection, policy and reports are mature.
+
+## 2026 Agent Harness Synthesis Update
+
+A later review wave added QA-agent, multi-agent orchestration, pipeline-agent, self-improving harness, harness-engineering, cross-host ECC, Feynman-style provenance, book-to-skill, Tasklet and 9Router-style context-routing ideas.
+
+See [`agent-harness-synthesis-2026.md`](agent-harness-synthesis-2026.md) for the consolidated table.
+
+The main product update is:
+
+```txt
+SotuRail should evolve from context manager into a local harness manager:
+context + state + verification + scope + lifecycle + evidence + host export.
+```
+
+New patterns to absorb:
+
+- Agent QA with offline datasets and golden export checks.
+- Validate -> fix -> verify -> report pipelines with evidence per stage.
+- File-based handoff and provenance sidecars.
+- Knowledge packs generated from docs, loaded on demand.
+- Host router behavior for context formats, not model traffic.
+- Rate-limit/fallback policy docs, not provider proxying.
+- Human approval gates for improve/eval/apply loops.
+
+Hard boundaries:
+
+- no SoturAI/trading scope in SotuRail docs or exports;
+- no mandatory provider APIs;
+- no MITM/proxy/account/quota bypass features;
+- no autonomous patching without approval;
+- no hidden cloud telemetry.
+
+## Coverage Checklist For The 2026 Harness Review
+
+The reviewed materials are now mapped into SotuRail planning as follows:
+
+| Source idea | SotuRail docs now covering it |
+| --- | --- |
+| QA agent with tests, datasets, CI and traces | [`agent-qa-rail.md`](agent-qa-rail.md), [`eval-datasets.md`](eval-datasets.md), [`golden-agent-tests.md`](golden-agent-tests.md), [`llm-as-judge-policy.md`](llm-as-judge-policy.md) |
+| CrewAI/LiteLLM-style roles, fallback and rate limits | [`multi-agent-workflow-templates.md`](multi-agent-workflow-templates.md), [`resilience-rail.md`](resilience-rail.md), [`rate-limit-and-fallback-policy.md`](rate-limit-and-fallback-policy.md) |
+| Validate -> fix -> verify -> report agent pipeline | [`observability-rail.md`](observability-rail.md), [`workflow-rail.md`](workflow-rail.md), [`examples/workflows/agent-pipeline-workflow.md`](../examples/workflows/agent-pipeline-workflow.md) |
+| OpenTracy-style trace, ledger, approval and experiments | [`agent-governance-rail.md`](agent-governance-rail.md), [`evidence-provenance-rail.md`](evidence-provenance-rail.md) |
+| Harness engineering lifecycle | [`harness-lifecycle-rail.md`](harness-lifecycle-rail.md), [`harness-rail.md`](harness-rail.md), [`workflow-rail.md`](workflow-rail.md) |
+| ECC-style cross-host harness, doctor, audit and skills | [`host-compatibility-rail.md`](host-compatibility-rail.md), [`agent-hosts.md`](agent-hosts.md), [`skill-rail-2.md`](skill-rail-2.md), [`future-rails-index.md`](future-rails-index.md) |
+| Feynman-style provenance and verifier status | [`evidence-provenance-rail.md`](evidence-provenance-rail.md), [`report-rail.md`](report-rail.md) |
+| book-to-skill-style document-to-skill packs | [`knowledge-rail.md`](knowledge-rail.md), [`skill-rail-2.md`](skill-rail-2.md), [`context-packs.md`](context-packs.md) |
+| Tasklet-style small reusable task blocks | [`tasklet-rail.md`](tasklet-rail.md), [`workflow-rail.md`](workflow-rail.md) |
+| 9Router-style router metaphor and token/context savings | [`host-router-rail.md`](host-router-rail.md), [`context-packs.md`](context-packs.md), [`governance-cost-rail.md`](governance-cost-rail.md) |
+
+This checklist is intentionally documentation-only. Runtime implementation should happen gradually through roadmap milestones and tests.

package/docs/eval-datasets.md

@@ -0,0 +1,40 @@
+# Eval Datasets
+
+Eval datasets are planned local fixtures for checking whether SotuRail outputs preserve the facts, paths, warnings and contracts that agents need.
+
+## Dataset Shape
+
+A minimal dataset case can include:
+
+```json
+{
+  "id": "host-export-readonly-mcp",
+  "input": {
+    "command": "soturail agents export --agent claude",
+    "fixture": "basic-typescript-project"
+  },
+  "expected": {
+    "mustContain": ["read-only", "MCP", "safe next commands"],
+    "mustNotContain": ["destructive MCP", "cloud telemetry required"],
+    "jsonPaths": ["host", "capabilities", "limitations"]
+  }
+}
+```
+
+## Dataset Families
+
+| Family | What it protects |
+| --- | --- |
+| host compatibility | exports for Claude, Codex, Cursor, OpenCode, Gemini and generic hosts |
+| context quality | selected files, commands, errors and policy notes survive compaction |
+| skill routing | only task-relevant skills are selected |
+| evidence/provenance | reports include source paths, verification status and missing-proof notes |
+| governance/cost | huge docs, broad MCP exposure and always-loaded skills warn correctly |
+| release checks | version, changelog, pack, docs and evidence are connected |
+
+## Rules
+
+- Datasets must be small enough to run during normal development.
+- Datasets must be deterministic by default.
+- Dataset results should be written as JSON and Markdown.
+- A dataset failure should say what evidence was missing, not only that text did not match.

package/docs/evaluation-suite.md

@@ -247,3 +247,9 @@ Evaluation Suite changes should not be promoted until:
 - token savings and quality are separated;
 - benchmark reports are refreshed only when intentionally requested;
 - public claims match reproducible local results.
+
+## Agent QA Rail Expansion
+
+Future Agent QA work is tracked in [`agent-qa-rail.md`](agent-qa-rail.md), [`eval-datasets.md`](eval-datasets.md), [`golden-agent-tests.md`](golden-agent-tests.md) and [`llm-as-judge-policy.md`](llm-as-judge-policy.md).
+
+The important rule remains: default evals must stay offline, deterministic and provider-agnostic. Provider-backed judges can exist only as explicit optional integration evidence.

package/docs/evidence-provenance-rail.md

@@ -0,0 +1,70 @@
+# 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/external-projects-audit.md

@@ -27,9 +27,19 @@ It is not the model, not the agent brain, not a heavy gateway and not a clone of
 | `murillo-romeu/sonar-totvs` | High | Domain-specific AI skill/report | Add Skill Rail 2.0 domain skill templates and safety gates |
 | `Acauhi99/opencode-agent-system` | Medium | OpenCode agent system patterns | Add OpenCode host export and role/skill packaging |
 | `ComposioHQ/composio` | High | Tool/provider integration layer | Stay compatible through manifests and reports, do not become a tool marketplace |
+| Hermes Agent | High | Self-improving personal agent runtime with tools, skills, routines, subagents and trajectory compression | Absorb context optimization and role-pack patterns while keeping SotuRail a harness |
+| Odysseus | High | Self-hosted AI workspace combining runtime, UI, local services, memory and tools | Absorb dashboard/host-fit/report patterns without adding a required server or model manager |
 
 ## What SotuRail Should Absorb
 
+### Hermes And Odysseus Classification
+
+Hermes is an agent runtime. Odysseus is a workspace plus runtime and local-service stack. SotuRail remains the local-first harness/context OS that prepares and governs artifacts for those kinds of hosts.
+
+Useful patterns include trajectory compression, session search, toolset profiles, role packs, local dashboard cards, visual evidence and explicit privacy boundaries. Model serving, mandatory web UI, central shell access and bundled personal productivity services remain outside SotuRail scope.
+
+See [Agent And Harness Synthesis 2026](agent-harness-synthesis-2026.md) and [Security Boundaries](security-boundaries.md).
+
 ### 1. Host compatibility without becoming a host
 
 OpenCode, Claude-compatible hosts, Antigravity-style hosts, Codex, Cursor and Deep Agents-style harnesses all need different context formats, rules, reports and safety guidance.
@@ -113,3 +123,22 @@ For security-oriented workflows, SotuRail should emphasize:
 | v1.3.0 Knowledge Graph Rail | Understand-Anything and Project Brain evolution |
 | v1.4.0 Skill Rail 2.0 | Sonar/TOTVS-style domain skill, Deep Agents skills, host exports |
 | v1.5.0 Governance And Cost Rail | dynamic workflows, long-horizon agents, context/token budget risks |
+
+## 2026 Harness/Eval/Provenance Review Addendum
+
+This addendum records the later review wave that directly affects post-v1 docs and roadmap planning.
+
+| Project/Product | Confidence | Primary pattern | SotuRail action |
+| --- | --- | --- | --- |
+| `ijmf/qa-ai-agent` | High | Agent QA through tests, datasets, traces and CI | Add Agent QA Rail, eval datasets, golden exports and optional judge policy |
+| `duckdogersxd/Orquestrando-Agents-CrewAI` | Medium | Multi-agent role workflow plus fallback/rate-limit lessons | Add multi-agent workflow templates and Resilience Rail notes |
+| `CaioTakedaIA/agentesdeIA` | Medium | Validate/fix/revalidate/analyze pipeline with visible logs | Add pipeline recorder concept and dashboard timeline ideas |
+| `OpenTracy/OpenTracy` | High | Propose/eval/approve/apply loop, trace, ledger and candidates | Add Agent Governance/Evolution Rail after governance foundations |
+| `walkinglabs/learn-harness-engineering` | High | Instructions, state, verification, scope, lifecycle | Add Harness Lifecycle Rail docs and feature/session handoff planning |
+| `affaan-m/ECC` | High | Cross-host harness system with skills/rules/doctor/repair/install state | Add install profiles, audit score, skills/rules profiles and host export polish |
+| `companion-inc/feynman` | High | Provenance sidecars and verification statuses | Add Evidence/Provenance Rail |
+| `virgiliojr94/book-to-skill` | High | Document-to-skill with on-demand chapters/glossary/patterns | Add Knowledge Rail and skill build/fold-in planning |
+| Tasklet.ai | Low | Public information was limited; small reusable task concept only | Add Tasklet Rail as local templates, not a vendor integration |
+| 9Router | Medium | Router metaphor, multi-host compatibility, token/context savings | Add Host Router Rail for context exports; explicitly avoid proxy/MITM behavior |
+
+The safe SotuRail interpretation is to generate local artifacts for external agents, not to become a model router, hosted agent platform, provider gateway or automation system that edits without approval.