soturail 1.0.1 → 1.2.0

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.

package/docs/future-rails-index.md

@@ -19,16 +19,19 @@ SotuRail should remain:
 - independent from any single agent host;
 - small enough to use in normal developer projects.
 
-v1.0.0 freezes the first stable local Context OS surface. The post-v1 sequence remains staged:
+v1.0.0 froze the first stable local Context OS surface. v1.1.0 delivered Host Compatibility Rail 1.0. The remaining post-v1 sequence is now staged with the 2026 agent-harness synthesis:
 
 ```txt
-v1.1.0  Host Compatibility Rail
-v1.2.0  Spec, Design And Diagram Rail
-v1.3.0  Knowledge Graph Rail
-v1.4.0  Skill Rail 2.0
-v1.5.0  Governance And Cost Rail
+v1.1.1  Host Compatibility Polish, ecosystem docs and golden export checks
+v1.2.0  Spec, Design, Diagram and Harness Lifecycle Rail
+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
 ```
 
+v1.2.0 also delivers a focused Harness Lifecycle slice: safe scaffold initialization, lifecycle audit, feature state, sessions and handoffs. Spec/design/diagram expansion remains staged and must be documented honestly when not implemented.
+
 ## 2026 Agent Runtime Update
 
 The newest planning layer is tracked in [`docs/roadmap-agent-runtime-addendum.md`](roadmap-agent-runtime-addendum.md).
@@ -56,6 +59,7 @@ It tightens how the future rails connect around current agent-runtime patterns:
 | MCP Exposure Rail | Report exposed MCP tools/resources/prompts/roots and local risk notes | v0.5.0 seed | `docs/roadmap-agent-runtime-addendum.md`, `docs/mcp.md`, `docs/policy-rail.md` |
 | Skill Boundary Rail | Route skills by task, role, evidence and host capability instead of always loading them | v0.5.0 seed | `docs/roadmap-agent-runtime-addendum.md`, `docs/skill-rail.md` |
 | Harness Rail | setup/plan/work/review/release discipline, evidence packs and failure ledger | v0.5.0 seeds, v0.7.0 expansion | `docs/harness-rail.md`, `docs/workflow-rail.md` |
+| Harness Lifecycle Rail | Safe local instructions, state, sessions, features, audits and handoffs | v1.2.0 implemented | `docs/harness-lifecycle-rail.md`, `docs/security-boundaries.md` |
 | Acceptance Harness Contracts | Require build/typecheck/lint/test/coverage/docs/policy gates before accepting work | v0.5.0 seed, v0.7.0 expansion | `docs/roadmap-agent-runtime-addendum.md`, `docs/harness-rail.md` |
 | Policy Rail | Rules, approvals, risky action queue, auth checks and MCP exposure reports | v0.5.0+ | `docs/policy-rail.md`, `docs/security-model.md`, `docs/rules.md` |
 | Structured Payload Rail | Target-aware Markdown/JSON/tagged/TOON-table/Mermaid context formats | v0.5.1+ | `docs/structured-payload-rail.md`, `docs/context-packs.md` |
@@ -66,7 +70,14 @@ It tightens how the future rails connect around current agent-runtime patterns:
 | Evaluation Suite | Quality benchmarks for context, payload formats, diagrams, evidence and role packs | v0.6.1 | `docs/evaluation-suite.md`, `docs/benchmarking.md`, `ROADMAP.md` |
 | Reverse Specification Rail | Turn existing code/docs/config/logs into claims, rules, specs, gaps and validation tasks | v0.8.0 primary | `docs/reverse-specification-rail.md`, `docs/knowledge-to-rules.md` |
 | Project Brain | Verified claims, decisions, bugs, gaps, rules, stale events and agent-safe briefs | v0.8.0 | `docs/project-brain.md`, `ROADMAP.md` |
-| Host Compatibility Rail | Host-aware exports, capability matrix and conservative prompt-only fallback for OpenCode, Antigravity, Claude, Codex, Cursor, Deep Agents-style and generic hosts | v1.1.0 | `docs/host-compatibility-rail.md`, `docs/agents.md`, `docs/mcp.md` |
+| Host Compatibility Rail | Host-aware exports, capability matrix, host doctors and conservative prompt-only fallback for OpenCode, Antigravity, Claude, Codex, Cursor, Deep Agents-style and generic hosts | v1.1.0 implemented | `docs/host-compatibility-rail.md`, `docs/agents.md`, `docs/mcp.md`, `docs/agent-export-contract.md` |
+| Agent QA Rail | Offline datasets, golden exports, regression reports and optional LLM-as-judge policy | v1.1.1 docs, v1.3.0 planned | `docs/agent-qa-rail.md`, `docs/eval-datasets.md`, `docs/golden-agent-tests.md`, `docs/llm-as-judge-policy.md` |
+| Evidence And Provenance Rail | Provenance sidecars, verification statuses and evidence per run/report | v1.3.0 | `docs/evidence-provenance-rail.md`, `docs/report-rail.md`, `docs/filesystem-evidence-rail.md` |
+| Knowledge Rail | Compile docs/specs/notes into on-demand SKILL.md/topic/glossary/pattern packs | v1.3.0 docs, v1.4.0 skill integration | `docs/knowledge-rail.md`, `docs/skill-rail-2.md`, `docs/project-brain.md` |
+| Resilience Rail | Rate-limit, fallback and provider-risk documentation/reporting without proxying traffic | v1.5.0 | `docs/resilience-rail.md`, `docs/rate-limit-and-fallback-policy.md`, `docs/governance-cost-rail.md` |
+| Host Router Rail | Route one local context source into host-specific export formats with safe fallback | v1.5.0 | `docs/host-router-rail.md`, `docs/host-compatibility-rail.md`, `docs/context-packs.md` |
+| Tasklet Rail | Small local reusable task templates for agents | v1.4.0 exploration | `docs/tasklet-rail.md`, `docs/skill-rail-2.md`, `docs/workflow-rail.md` |
+| Agent Governance/Evolution Rail | Trace, ledger, experiments, approval gates and improve/eval/apply loop | v1.6.0 | `docs/agent-governance-rail.md`, `docs/evaluation-suite.md`, `docs/policy-rail.md` |
 | Spec Rail | PRD, requirements, design, tasks and acceptance criteria as workflow inputs | v1.2.0 | `docs/spec-driven-workflow.md`, `docs/design-rail.md`, `docs/diagram-rail.md` |
 | Design Rail | Local `DESIGN.md`, design token lint/diff/export and agent-readable visual guidance | v1.2.0 | `docs/design-rail.md`, `docs/dashboard-rail.md` |
 | Knowledge Graph Rail | Local graph of files, claims, decisions, tests, workflows, diagrams and releases | v1.3.0 | `docs/knowledge-graph-rail.md`, `docs/code-graph.md`, `docs/project-brain.md` |
@@ -74,6 +85,7 @@ It tightens how the future rails connect around current agent-runtime patterns:
 | Governance And Cost Rail | Context budget, dynamic workflow risk and MCP/skill exposure warnings | v1.5.0 | `docs/governance-cost-rail.md`, `docs/report-rail.md`, `docs/policy-rail.md` |
 | Redacted Evidence Sharing | Local redacted evidence bundles for reports/logs without hosting by default | v1.4+ exploration | `docs/report-redaction.md`, `docs/external-projects-audit.md` |
 | Local Dashboard | Local reports, trace viewer, Mermaid rendering and policy/evidence views | v0.10.0 | `ROADMAP.md` |
+| SotuRail Conductor | Optional future planner/verifier/reviewer/tasklet coordinator behind approval gates | Future proposed | `docs/conductor-mode.md`, `docs/security-boundaries.md` |
 
 ## Version Summary
 
@@ -214,15 +226,27 @@ Focus:
 
 Focus:
 
-- Host Compatibility Rail;
-- OpenCode, Antigravity, Deep Agents-style and generic host exports;
-- host capability matrix;
+- Host Compatibility Rail 1.0 delivered;
+- OpenCode, Antigravity, DeepAgents-style, Gemini legacy-compatible and generic host exports;
+- host capability matrix 2.0 fields with backward-compatible schema;
+- per-host doctor reports;
 - read-only MCP host manifests.
 
+### v1.1.1
+
+Focus:
+
+- 2026 agent-harness synthesis docs;
+- Agent QA, golden export and optional judge policy docs;
+- Evidence/Provenance, Knowledge, Resilience, Host Router, Tasklet and Agent Governance planning docs;
+- validate -> fix -> verify -> report workflow example;
+- multi-agent researcher/analyst/writer/verifier template example.
+
 ### v1.2.0
 
 Focus:
 
+- Harness Lifecycle Rail implemented with `harness init`, `harness audit`, sessions, handoffs and feature state;
 - Spec, Design And Diagram Rail;
 - PRD/requirements/design/tasks scaffolds;
 - local `DESIGN.md` lint/diff/export;
@@ -232,29 +256,47 @@ Focus:
 
 Focus:
 
-- Knowledge Graph Rail;
+- Knowledge, Evidence and Evaluation Rail;
 - graph build/explain/impact/tour;
-- local dashboard graph views;
-- stale-edge detection.
+- Knowledge Rail ingest/estimate/compile/update/verify;
+- evidence and provenance sidecars;
+- local eval datasets, golden checks and regression reports;
+- optional LLM-as-judge outside default release gates;
+- stale-edge and missing-evidence detection.
 
 ### v1.4.0
 
 Focus:
 
-- Skill Rail 2.0;
+- Skill Rail 2.0, Knowledge-to-Skill and Tasklet Packs;
 - domain skill templates;
 - skill lint/eval/report;
-- role-aware exports and safety gates.
+- role-aware exports and safety gates;
+- `skill build` and `skill fold-in` planning;
+- small reusable tasklet templates.
 
 ### v1.5.0
 
 Focus:
 
-- Governance And Cost Rail;
-- context budget reports;
+- Governance, Cost, Resilience and Host Router Rail;
+- context budget reports and compact context variants;
+- rate-limit/fallback policy reports;
+- host-format fallback without provider proxying;
 - dynamic workflow guardrails;
 - MCP/skill exposure risk summaries.
 
+### v1.6.0
+
+Focus:
+
+- Agent Governance / Evolution Rail;
+- trace and ledger artifacts;
+- agent boundary policy;
+- experiments/candidates/results;
+- propose -> eval -> approve -> apply loop;
+- approval gates before any patch application.
+
 
 ## What Should Not Happen
 
@@ -298,3 +340,19 @@ SotuRail should not become:
 - `docs/ecosystem-influences.md`
 - `docs/comparisons.md`
 - `docs/roadmap-harness-diagram-payload-addendum.md`
+- `docs/agent-harness-synthesis-2026.md`
+- `docs/agent-qa-rail.md`
+- `docs/eval-datasets.md`
+- `docs/golden-agent-tests.md`
+- `docs/llm-as-judge-policy.md`
+- `docs/evidence-provenance-rail.md`
+- `docs/agent-governance-rail.md`
+- `docs/harness-lifecycle-rail.md`
+- `docs/knowledge-rail.md`
+- `docs/resilience-rail.md`
+- `docs/rate-limit-and-fallback-policy.md`
+- `docs/multi-agent-workflow-templates.md`
+- `docs/host-router-rail.md`
+- `docs/tasklet-rail.md`
+- `docs/security-boundaries.md`
+- `docs/conductor-mode.md`

package/docs/golden-agent-tests.md

@@ -0,0 +1,44 @@
+# Golden Agent Tests
+
+Golden agent tests are snapshot-like checks for agent-facing outputs. They are not tests of a real LLM. They protect SotuRail exports, reports and context packs from accidental regressions.
+
+## Golden Targets
+
+Planned golden targets:
+
+- `AGENTS.md` guidance generated by `harness init`;
+- Claude, Codex, Cursor, OpenCode, Gemini and generic exports;
+- host matrix JSON;
+- MCP host manifest JSON;
+- report and dashboard summaries;
+- skill export bundles;
+- tasklet definitions;
+- evidence/provenance sidecars.
+
+## What A Golden Test Should Check
+
+Golden tests should favor semantic assertions over brittle full-file string matches:
+
+```txt
+must include: local-first boundary
+must include: safe next commands
+must include: read-only MCP warning
+must include: evidence paths when available
+must not include: secrets
+must not include: destructive tool promises
+must not include: unrelated project identity
+must parse: JSON artifacts
+must keep: schemaVersion
+```
+
+## Update Policy
+
+Golden outputs should be updated deliberately:
+
+```bash
+soturail eval golden --update
+soturail eval report
+soturail release check --strict --with-evals
+```
+
+A golden change should be explained in release evidence. If the change affects host behavior, update host docs too.

package/docs/governance-cost-rail.md

@@ -79,3 +79,13 @@ soturail brain stale --repair-plan
 | MCP Report Resources | exposure inventory |
 | Workflow Rail | phase depth and evidence completeness |
 | Benchmark Rail | performance evidence and stale report warnings |
+
+## Resilience And Host Router Expansion
+
+Future v1.5 planning now includes Resilience Rail and Host Router Rail:
+
+- [`resilience-rail.md`](resilience-rail.md) for retry/fallback/rate-limit documentation and risk reports;
+- [`rate-limit-and-fallback-policy.md`](rate-limit-and-fallback-policy.md) for local policy shape;
+- [`host-router-rail.md`](host-router-rail.md) for context-format routing across hosts.
+
+This does not turn SotuRail into a model proxy, account manager, MITM bridge or billing gateway.

package/docs/harness-lifecycle-rail.md

@@ -0,0 +1,95 @@
+# Harness Lifecycle Rail
+
+Harness Lifecycle Rail is the implemented v1.2.0 local state layer for carrying agent-assisted work across sessions and hosts without turning SotuRail into an autonomous agent runtime.
+
+It organizes five subsystems:
+
+```txt
+Instructions
+State
+Verification
+Scope
+Session Lifecycle
+```
+
+The purpose is to keep coding agents in scope across sessions and prevent premature "done" states.
+
+## Implemented Commands
+
+```bash
+soturail harness init
+soturail harness audit
+soturail harness audit --json
+soturail session start "objective"
+soturail session end --summary "completed work"
+soturail handoff generate
+soturail feature add "feature"
+soturail feature start <id>
+soturail feature done <id> --evidence tests/example.test.ts
+soturail feature list
+```
+
+`harness init` creates local files without overwriting existing content:
+
+```txt
+.soturail/harness/AGENTS.md
+.soturail/harness/instructions.md
+.soturail/harness/verification.md
+.soturail/harness/scope.md
+.soturail/harness/lifecycle.md
+.soturail/state/feature_list.json
+.soturail/state/progress.md
+.soturail/state/session-handoff.md
+```
+
+Use `--force` only after reviewing the scaffold files that will be replaced.
+
+## Audit Model
+
+`harness audit` checks Instructions, State, Verification, Scope, Session Lifecycle, Host Compatibility, Evidence/Reports and Security Boundaries. It writes:
+
+```txt
+.soturail/harness/audit.json
+.soturail/harness/audit.md
+```
+
+The audit is deterministic and read-only. It does not run commands from `verification.md`.
+
+## Feature And Session State
+
+Feature lists prevent agents from doing many tasks and finishing none. `feature_list.json` has the stable local shape:
+
+```json
+{
+  "schemaVersion": "soturail.feature-list.v1",
+  "active": null,
+  "features": []
+}
+```
+
+Only one feature can be active. Completion evidence is recorded as paths or local references supplied by the user.
+
+`handoff generate` writes a bounded handoff with the current objective, completed work, changed-file names, verification status, blockers and next steps. It does not read private shell history or run verification automatically.
+
+## Progressive Disclosure
+
+Root agent docs should stay short and point to specialized docs.
+
+```txt
+Read first: .soturail/harness/AGENTS.md
+If editing tests: .soturail/harness/verification.md
+If continuing work: .soturail/state/session-handoff.md
+If preparing release: docs/release-workflow.md
+```
+
+## Planned Extensions
+
+Commands such as `harness benchmark`, `session verify` and a dedicated `session handoff` alias remain proposed. They are not implemented in v1.2.0.
+
+## Boundaries
+
+- SotuRail prepares lifecycle state and evidence; the agent host still reasons and edits.
+- No cloud telemetry, mandatory server or LLM API key is required.
+- No destructive MCP tool or arbitrary MCP shell execution is added.
+- No Claude-only harness, giant root instruction file or acceptance without evidence.
+- See [Security Boundaries](security-boundaries.md), [Harness Rail](harness-rail.md), [Conductor Mode](conductor-mode.md) and [Agent Harness Synthesis](agent-harness-synthesis-2026.md).

package/docs/harness-rail.md

@@ -15,6 +15,11 @@ Harness Rail focuses on workflow discipline, policy decisions, review evidence,
 
 ```bash
 soturail harness note "agent said done before tests passed"
+soturail harness init
+soturail harness audit
+soturail session start "objective"
+soturail handoff generate
+soturail feature list
 soturail harness list
 soturail harness explain <id>
 soturail harness doctor
@@ -25,6 +30,12 @@ soturail workflow evidence <id>
 
 `harness contract check` validates the local contract. It does not run build, typecheck or test commands by default.
 
+## v1.2.0 Harness Lifecycle
+
+Harness Lifecycle Rail adds safe project-local state for instructions, scope, verification, sessions, handoffs and features. `harness init` preserves existing files by default, and `harness audit` scores lifecycle readiness without executing verification commands.
+
+See [Harness Lifecycle Rail](harness-lifecycle-rail.md) and [Security Boundaries](security-boundaries.md).
+
 ## v0.7.0 Workflow Connection
 
 Harness Rail now connects to Workflow Rail 2.0:
@@ -139,3 +150,19 @@ Harness Rail is successful only if it makes SotuRail more predictable without ma
 - tests cover clean workflow fixtures;
 - reports distinguish token savings from quality preservation;
 - no arbitrary shell execution is exposed through MCP by default.
+
+## Harness Lifecycle Expansion
+
+Future harness lifecycle work is tracked in [`harness-lifecycle-rail.md`](harness-lifecycle-rail.md).
+
+The expansion adds five explicit subsystems:
+
+```txt
+Instructions
+State
+Verification
+Scope
+Session Lifecycle
+```
+
+The goal is to make `harness init`, `harness audit`, `session start/end`, feature lists and handoff files first-class local artifacts without becoming a Claude-only plugin or autonomous runtime.