roadmap.md

dsh-legion Roadmap

This file tracks implementation status. Design rationale lives in ADRs and the OMO/Senpi research reports.

Product principles:

• Legion is customization-first. Users can define Specialists, Cohorts, and Strategies; the curated Default Catalog must use the same replaceable contracts and carry no hidden runtime privileges.
• Legion is type-driven. TypeScript should make internal illegal states unrepresentable, while runtime schemas validate every external configuration, model, plugin, persistence, and process boundary.

v0.2 — Explainable specialist compiler

• Pure Config + RuntimeSnapshot -> CompiledCatalog seam.
• Stable diagnostic codes and provider-capability preflight.
• Detached EffectiveSpecialists and deterministic ordering.
• SHA-256 policy digest and runtime catalog digest.
• CompiledCatalog + invocation -> DelegationPlan seam.
• Tool schema, prompt, activation, and execution share one compiled catalog.
• Versioned findings-v1 and review-v1 foreground result contracts.
• Revalidate and leaf-project provider-owned structured output.
• Human/JSON doctor CLI over the compiled catalog and explicit provider fixtures.
• Specialist-scoped prompt-fragment references with canonical path confinement and immutable content snapshots.

v0.3 — Deterministic pre-start route planning

• Ordered exact route candidates per specialist.
• Registered LLM adapter and known exact-model metadata snapshot.
• Preserve unknown for unlisted models or unavailable metadata.
• Observe known reasoning controls and validate context/effective-output constraints.
• Freeze one route plan before child start.
• Select one route and start one child; no Legion-owned failure replay.
• Route-specific additive prompt tuning.
• Bounded tool-result explain snapshot with selected/rejected/skipped reasons.

Cross-route recovery is not part of v0.3. It requires a unified DSH recovery seam so provider retry and route switching share one owner and one cancellation/attempt/time/token/cost budget.

v0.4 — Packaging and diagnostics hardening

• Add and enforce a lockfile.
• Windows CI and Node engines lower-bound job.
• DSH peer minimum/latest compatibility matrix.
• Packed harmless real delegation E2E with a scripted provider.
• Config migration and rollback contract.
• Release/tag/tarball/SBOM/provenance automation.

v1.0 — Custom Cohorts and evidence-gated Strategies

Users can build their own Cohorts and orchestration Strategies. Legion ships a useful Default Catalog, but defaults are ordinary versioned data under the same public contracts.

• Public CohortSpec: named Member Slots reference Specialists and declare bounded participation constraints.
• Public Strategy contract that compiles an Objective and Cohort to executable bounded DSH subagent primitive IR.
• Strategy registration and validation shared by Legion defaults and third-party Catalog Layers.
• Catalog layering: extend, replace, or disable default Specialists, Cohorts, and Strategies without hardcoded names.
• Blocking deterministic direct-vs-strategy protocol benchmark with versioned thresholds; it is not model-quality evidence.
• Frozen 12-case review/research development packs plus offline paired-bootstrap campaign and exposure scorers.
• Default-off enableStrategies authority gate exposes active user/default Strategies through the single Legion tool only by explicit deployment opt-in.
• Execute default plan-execute-review: plan, execution evidence, structured review, and one bounded repair delegate.
• Hard member/agent, concurrency, deadline, and accepted-output limits are compiled and enforced.
• Direct/fanout cancellation, degraded outcomes, bounded disposal, and terminal first-wins normalization.
• Authority monotonicity: invocation customization only narrows limits; final widening remains subject to DSH policy and approval.
• Contract tests prove default entries can be recreated entirely through public user configuration.
• Seeded fanout ordering, terminal first-wins, every-waiter/no-lease checks, and catalog-generation commit fencing.

Default Strategies ship as ordinary off-by-default data; automatic model exposure requires benchmarks showing measurable value over direct delegation.

v1.1 — Journal-native evolving workflows (Milestone 8: release hardening implemented)

V1.1 adds an opt-in, Session-anchored durable Strategy controller while preserving DSH ownership of physical execution and durability. The existing v1.0 ephemeral path remains unchanged and is the default. Milestones 1–8 provide the typed journal vocabulary, pure projection and replay, deterministic static Plan Graph compilation, a bounded activation interpreter, public Host coordination/fencing/recovery contracts, journal-native mailbox transitions, and ordered cache-stable Context Manifests. The assessed DSH 0.1.2-alpha.4 composition supplies neither atomic coordination nor a required-event admission seam for out-of-repository legion/* events, so unsafe journal mutation remains deliberately unavailable while read-only inspection and ephemeral execution remain usable.

• Accept ADRs 0015–0020 and update repository ownership and domain vocabulary.
• Authorize only a bounded interpreter for typed Legion DAG IR over plugin-owned events in the invoking DSH Session journal.
• Require DSH Session projections and existing projection cache for derived durable state; no Legion snapshot or state store.
• Require Host-owned atomic coordination for crash-safe durable mutation and fail closed when it is unavailable.
• Keep global admission Host-owned; without it, enforce only existing per-run limits and make no global-scale or aggregate token/cost claim.
• Implement journal event vocabulary, pure projection, replay, and bounded inspection.
• Implement opt-in static durable DAG execution while retaining ephemeral parity.
• Implement public lease/fence Host contracts, fail-closed capability detection, stale-result rejection, deterministic effect-aware recovery, and safe programmatic run controls; production mutation remains capability-gated.
• Implement journal-native mailbox delivery and ordered cache-stable Context Manifests.
• Implement validated Plan Deltas and one-shot Continuations.
• Implement the public Stair-step policy.
• Implement sanitized environment snapshots, immutable per-attempt Specialist/Route/context bindings, cache-prefix dispatch grouping, optional Host admission with honest per-run fallback, bounded hierarchical reducers, and derived parallelism metrics. Cross-route recovery remains disabled without a unified Host seam.
• Implement deterministic protocol, compatibility, packaging, and release gates; defer large live-model scale certification. Tag publication still requires the evidence listed in docs/TODO.md.

V1.1 non-goals remain a second journal/WAL/database/task or mailbox store, a generic scheduler/workflow runtime, a process-global run registry or daemon, exactly-once external side effects, arbitrary model-written code, captured stacks, and silent authority expansion.

v1.2 — Host-sourced live configuration

Legion keeps one configuration vocabulary. The DSH settings service, which from 0.1.0-rc.7 serves every registered namespace instead of an allowlist, becomes an additional source for the existing Config schema rather than a second configuration system.

• Register the legion namespace structurally, with no peer dependency on @deepseek-ai/dsh-settings and no behaviour change when no provider is mounted.
• Layer the composition entry under the stored user section and restore it when the provider detaches.
• Widen a published generation's inputs to configuration, prompt-fragment resources, and runtime facts, with serialized last-commit-wins republication.
• Degrade a rejected registration or unpublishable commit to the last publishable generation instead of withdrawing the delegation surface.
• Ship the browser settings card as an ordinary DSH client bundle, verified by executing the artifact under the loader's protocol.
• Ship the separate dsh-legion-receipts Host/Client companion, which streams live-Session baselines and complete replacements through official DSH Typert/Gateway and renders the current Session in shell.overlay.

The official DSH Client Test Runtime renders the companion overlay and verifies DOM, interaction, accessibility, Session switching, and reconnect behavior. Full Receipt facts remain process-local observation state for one live Session and companion instance; Host restart starts empty, while the bounded terminal tool summary remains available without Web or the companion. The root installs the exact same-version companion package; remote-only facts that official DSH seams cannot prove remain unavailable, and known aggregates report partial coverage rather than false totals.

v1.2 — Optional ACP delegation

DSH owns the Agent Client Protocol backend. Legion contributes the delegation policy for agents mounted through it, as ordinary opt-in catalog data.

• Public ACP agent descriptor, Specialist factory, catalog layer, and composition-row generator sharing one descriptor list.
• Authoring-time rejection of Specialist fields an out-of-process child cannot honor.
• Curated entries for the nine requested agents, with per-entry entrypoint provenance and no guessed spawn command.
• Generated example fragment with a drift test.

Type-system gates

• Distinct authored Config/Spec, materialized catalog, Effective Specialist/Cohort, and Compiled Plan types at catalog boundaries.
• Branded Specialist, Cohort, Strategy, Member Slot, Artifact, Cohort Run, Route/Strategy decision digests; Member Slot replaces a separate Role identity.
• Discriminated Strategy stages, compile results, and completed/degraded/cancelled/failed Cohort Run outcomes.
• Generic Strategy artifact input/output contracts reject forward, duplicate, contract, and cardinality wiring at compile time.
• Default Catalog declared with as const satisfies the public user catalog contract.
• Type-level tests for valid inference and expected compile failures.
• Runtime schema parity tests for external Cohort/Strategy config contracts.

Post-v1 evidence activation

• Complete two paired held-out real-model quality campaigns per curated Strategy with safety/cost/latency gates.
• Automatically expose independent-review and research-panel only after their signed evidence passes; explicit deployment opt-in remains available.

Non-goals

• Another Agent/Session/subagent/workflow/goal runtime.
• Senpi task store, residency manager, RPC runner, mailbox directory, live Host Team runtime, or TTL sweeper. The sole exception is ADRs 0015–0020: an opt-in, bounded, Session-anchored durable Strategy controller whose mailbox and run facts are typed events in the existing DSH journal.
• OMO hook injection, fixed mythology roles, current model leaderboard, or unbounded autonomy.
• Credential storage, provider auth, model adapter registry, sandbox, approval, or telemetry exporter.