soturail 1.1.0 → 1.2.0

package/docs/future-rails-index.md

@@ -19,15 +19,19 @@ SotuRail should remain:
 - independent from any single agent host;
 - small enough to use in normal developer projects.
 
-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 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.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).
@@ -55,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,6 +71,13 @@ It tightens how the future rails connect around current agent-runtime patterns:
 | 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, 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` |
@@ -73,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
 
@@ -219,10 +232,21 @@ Focus:
 - 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.

package/docs/host-compatibility-rail.md

@@ -2,6 +2,12 @@
 
 Host Compatibility Rail is the v1.1.0 direction for making SotuRail outputs useful across coding-agent hosts without becoming an agent host itself.
 
+## Host Fit
+
+`soturail agents matrix`, `agents doctor --host <host>` and `agents doctor --all` form the current Host Fit Doctor surface. They report compatibility, export support, limitations and safe next commands without model serving or runtime installation.
+
+Hermes and Odysseus are ecosystem influences, not direct stable host integrations. Hermes is an agent runtime and Odysseus is a broader workspace/runtime stack. Generic-compatible exports remain the safe fallback until a host-specific path is implemented and tested.
+
 ## Goal
 
 ```txt
@@ -76,3 +82,15 @@ Each host entry should eventually report:
 | Policy Rail | config write, hook and tool exposure checks |
 | Skill Rail | host-aware skill export without always loading every skill |
 | Workflow Rail | phase-specific host handoff |
+
+## Host Router Expansion
+
+Future host work is tracked in [`host-router-rail.md`](host-router-rail.md).
+
+The host-router idea means context-format routing, not model-request routing:
+
+```txt
+one SotuRail context source -> Claude/Codex/Cursor/OpenCode/Gemini/generic exports
+```
+
+SotuRail must not intercept IDE traffic, proxy provider requests, manage browser tokens or bypass quotas.

package/docs/host-router-rail.md

@@ -0,0 +1,73 @@
+# Host Router Rail
+
+Host Router Rail is a planned host/export layer inspired by router products, but it routes context formats, not model traffic.
+
+```txt
+One SotuRail context source -> many host-specific exports.
+```
+
+## Goal
+
+Generate the best safe local artifact for each host:
+
+| Host | Example export |
+| --- | --- |
+| Claude Code | `CLAUDE.md`, skills guidance, MCP read-only manifest |
+| Codex | `AGENTS.md`, instructions and safe command handoff |
+| Cursor | `.cursor/rules` style prompt/rule files |
+| OpenCode | OpenCode-compatible instructions and role packs |
+| Gemini | `GEMINI.md` style guidance |
+| generic | Markdown context pack and report bundle |
+
+## Proposed Commands
+
+```bash
+soturail export all
+soturail translate --to claude
+soturail translate --to codex
+soturail translate --to cursor
+soturail hosts status
+soturail doctor --hosts
+soturail export --fallback
+```
+
+## Context Optimization
+
+Host Router Rail should connect to context budgeting:
+
+```bash
+soturail context optimize
+soturail context budget
+soturail context compact
+```
+
+Potential outputs:
+
+```txt
+.soturail/context/full.md
+.soturail/context/compact.md
+.soturail/context/ultra.md
+.soturail/exports/claude/
+.soturail/exports/codex/
+.soturail/exports/cursor/
+```
+
+## Fallbacks
+
+Fallback should mean safe format fallback, not provider or quota bypass:
+
+- MCP unsupported -> static Markdown/resources;
+- skills unsupported -> prompt-only instructions;
+- huge context -> compact role pack;
+- host unknown -> generic export.
+
+## Hard Boundary
+
+SotuRail must not:
+
+- intercept IDE traffic;
+- proxy model requests;
+- manage or rotate provider accounts;
+- use browser cookies or session tokens;
+- bypass quotas;
+- promise unlimited free model access.

package/docs/knowledge-rail.md

@@ -0,0 +1,76 @@
+# 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/llm-as-judge-policy.md

@@ -0,0 +1,45 @@
+# LLM-As-Judge Policy
+
+SotuRail may eventually support optional LLM-as-judge evaluations for hallucination, clarity and evidence quality. This document defines the boundary before that feature exists.
+
+## Default Policy
+
+```txt
+No LLM-as-judge call is required for normal SotuRail development, testing or release.
+```
+
+Default gates should be deterministic:
+
+- schema validation;
+- JSON parsing;
+- keyword and section checks;
+- file existence checks;
+- redaction checks;
+- golden output checks;
+- snapshot diff checks;
+- link/path checks where local.
+
+## Optional Judge Mode
+
+A future optional command could look like:
+
+```bash
+soturail eval judge --provider openai
+soturail eval judge --provider groq
+soturail eval judge --provider local
+```
+
+Required behavior:
+
+- opt-in only;
+- never uploads repo data without clear user action;
+- stores provider, model, prompt hash, timestamp and result;
+- separates judge results from deterministic release evidence;
+- marks results as subjective/heuristic, not proof.
+
+## Non-Goals
+
+- no mandatory provider keys;
+- no hidden telemetry;
+- no judge score as the only release gate;
+- no claim that a judge result proves correctness.

package/docs/multi-agent-workflow-templates.md

@@ -0,0 +1,63 @@
+# Multi-Agent Workflow Templates
+
+SotuRail should support multi-agent ideas as templates and context packs, not as a required CrewAI/LangGraph runtime.
+
+## Purpose
+
+A multi-agent workflow template defines roles, inputs, outputs, evidence and verification criteria for external agents.
+
+SotuRail can generate:
+
+- role-specific context packs;
+- role boundaries;
+- definition of done per role;
+- handoff files between roles;
+- evidence requirements;
+- a final report skeleton.
+
+## Example Roles
+
+```txt
+Lead Agent
+├── Researcher: collects local evidence and docs
+├── Analyst: compares options and risks
+├── Writer: produces user-facing docs/reports
+└── Verifier: checks claims, tests, links and provenance
+```
+
+## Proposed Commands
+
+```bash
+soturail workflow template research-report
+soturail workflow template validate-fix-verify-report
+soturail context pack --role researcher
+soturail context pack --role analyst
+soturail context pack --role verifier
+soturail agents export --role reviewer
+```
+
+## Template: Validate -> Fix -> Verify -> Report
+
+Inspired by agent pipelines that validate input, repair issues, revalidate and then produce a report.
+
+```txt
+validate
+  input: selected files, schema, policy
+  output: findings.json
+fix
+  input: findings.json and allowed files
+  output: patch proposal or instructions
+verify
+  input: patch proposal and test/report commands
+  output: verification.md
+report
+  input: all prior artifacts
+  output: report.md + provenance.md
+```
+
+## Non-Goals
+
+- no mandatory CrewAI, LangGraph or LangChain dependency;
+- no hidden subagent execution;
+- no external web search by default;
+- no autonomous edits without host/human approval.

package/docs/observability-rail.md

@@ -36,3 +36,39 @@ The timeline is sorted deterministically, and the summary includes:
 - safe next commands.
 
 Observability still does not collect private shell history and does not upload telemetry.
+
+## Pipeline Recorder Expansion
+
+Future observability work can add a pipeline recorder inspired by validate/fix/verify/report agent flows:
+
+```txt
+agent_started
+agent_finished
+agent_failed
+file_read
+schema_validated
+repair_applied
+report_generated
+```
+
+The first implementation can remain local artifacts and dashboard cards. A live SSE/server mode is optional and should not become required.
+
+## Related 2026 Harness Rails
+
+Observability Rail is the local timeline layer that feeds several planned rails:
+
+- [`agent-qa-rail.md`](agent-qa-rail.md) defines eval runs, scores and regression artifacts that can become observability events.
+- [`evidence-provenance-rail.md`](evidence-provenance-rail.md) defines verification status and provenance sidecars that reports and timelines should surface.
+- [`agent-governance-rail.md`](agent-governance-rail.md) extends observability into trace, ledger, experiment and approval records.
+- [`resilience-rail.md`](resilience-rail.md) adds rate-limit/fallback/provider-risk warnings as local events, not cloud telemetry.
+
+This keeps the boundary clear: SotuRail observes local artifacts and user-approved records; it does not upload traces or become a hosted LangFuse/OpenTelemetry replacement by default.
+
+## Ecosystem Direction
+
+Hermes-style trajectory compression and Odysseus-style visual workspaces reinforce two SotuRail rules:
+
+- keep observability as local, recoverable evidence rather than uploaded telemetry;
+- present Context Packs, Memory, Reports, Evidence, Workflows, Host Compatibility, Skills, lifecycle state and Handoffs as bounded dashboard/report sections.
+
+SotuRail does not add a required server, chat workspace or central shell interface. See [Security Boundaries](security-boundaries.md).