Skip to content

spec.md

Latest commit

 

History

History
168 lines (122 loc) · 10.7 KB

spec.md

File metadata and controls

168 lines (122 loc) · 10.7 KB

Feature Specification: Traverse Expedition Example Artifacts

Feature Branch: 009-expedition-example-artifacts
Created: 2026-03-27
Status: Draft
Input: Issue #33, the approved expedition example domain, capability contract rules, event contract rules, and workflow registry rules.

Purpose

This specification defines the first concrete expedition example artifacts for Traverse.

It narrows the approved expedition domain into implementation-governing artifacts for:

  • example capability contract boundaries
  • example event contract boundaries
  • the plan-expedition workflow artifact
  • the workflow-backed composed capability relationship for plan-expedition

This slice exists so future example implementation can be contract-first and workflow-first instead of inventing example artifact semantics during coding.

User Scenarios and Testing

User Story 1 - Author the First Expedition Capability Contracts (Priority: P1)

As a platform developer, I want the first expedition example capabilities to have concrete contract boundaries so that Traverse can demonstrate governed example artifacts instead of abstract domain notes.

Why this priority: The approved domain direction is not enough by itself. The example artifacts must become real contract candidates before implementation can begin.

Independent Test: A developer can inspect this spec and derive one concrete capability contract boundary for each of the five expedition capabilities without ambiguity.

Acceptance Scenarios:

  1. Given capture-expedition-objective, When the example contract is authored, Then the contract boundary clearly covers structured objective intake and not downstream interpretation or validation.
  2. Given interpret-expedition-intent, When the example contract is authored, Then the capability is clearly AI-assisted and bounded to interpretation rather than final safety or readiness truth.
  3. Given the deterministic expedition capabilities, When the example contracts are authored, Then each one has a distinct business action and non-overlapping contract responsibility.

User Story 2 - Author the First Expedition Event Contracts (Priority: P1)

As a platform developer, I want the expedition example domain to expose concrete governed events so that the workflow and future UI/runtime subscriptions can use first-class event contracts.

Why this priority: Traverse’s example workflow should use governed event semantics, not informal event names.

Independent Test: A developer can derive the first event contract artifacts from this spec and map each event to one producing capability and one domain outcome.

Acceptance Scenarios:

  1. Given the expedition example event set, When event contracts are authored, Then each event has a stable identity, producing capability boundary, and payload purpose.
  2. Given the canonical workflow, When event-triggered progression is modeled later, Then the workflow can reference the governed expedition events declared here.
  3. Given future runtime or UI subscribers, When they consume expedition domain updates, Then they can rely on the same event identities declared here.

User Story 3 - Define the Concrete Workflow Artifact (Priority: P1)

As a platform developer, I want the plan-expedition workflow to be defined as a concrete workflow artifact so that Traverse can later execute one deterministic composed example end to end.

Why this priority: The workflow order is approved, but the actual workflow artifact still needs concrete node, edge, and output semantics.

Independent Test: A developer can derive one valid workflow definition artifact for plan-expedition from this spec, including nodes, direct transitions, terminal outcome, and workflow-backed capability linkage.

Acceptance Scenarios:

  1. Given the plan-expedition workflow, When the artifact is authored, Then it contains one start node, deterministic edges, one terminal node, and one composed planning result.
  2. Given the workflow-backed composed capability plan-expedition, When it is modeled, Then it remains a first-class capability linked to the workflow artifact.
  3. Given the expedition example artifacts, When future demos are implemented, Then they can use the same capability ids, event ids, and workflow id declared here.

Scope

In scope:

  • concrete example capability identities and responsibilities
  • concrete example event identities and producing capability mapping
  • concrete workflow artifact identity, nodes, edges, and output intent
  • workflow-backed composed capability identity for plan-expedition
  • example artifact relationships across capability, event, and workflow slices

Out of scope:

  • Rust implementation of the expedition example capabilities
  • actual AI prompt content
  • external integrations for weather, route, or hazard systems
  • browser demo rendering
  • mobile demo rendering

Requirements

Functional Requirements

  • FR-001: The expedition example artifacts MUST use the namespace expedition.planning.
  • FR-002: The first example capability contract ids MUST be:
    • expedition.planning.capture-expedition-objective
    • expedition.planning.interpret-expedition-intent
    • expedition.planning.assess-conditions-summary
    • expedition.planning.validate-team-readiness
    • expedition.planning.assemble-expedition-plan
  • FR-003: capture-expedition-objective MUST accept structured expedition goal input and MUST output a normalized expedition objective record.
  • FR-004: interpret-expedition-intent MUST accept an expedition objective plus free-form planning intent and MUST output a structured interpreted planning intent record.
  • FR-005: interpret-expedition-intent MUST be the only AI-assisted example capability in this slice.
  • FR-006: assess-conditions-summary MUST accept objective plus interpreted intent context and MUST output a deterministic conditions summary.
  • FR-007: validate-team-readiness MUST accept the expedition objective, conditions summary, and team profile context and MUST output a deterministic readiness result.
  • FR-008: assemble-expedition-plan MUST accept the normalized outputs of the previous expedition capabilities and MUST output one final expedition plan artifact.
  • FR-009: The expedition example event contract ids MUST be:
    • expedition.planning.expedition-objective-captured
    • expedition.planning.expedition-intent-interpreted
    • expedition.planning.conditions-summary-assessed
    • expedition.planning.team-readiness-validated
    • expedition.planning.expedition-plan-assembled
  • FR-010: Each expedition example event MUST map to exactly one producing capability in this slice.
  • FR-011: The plan-expedition workflow artifact id MUST be expedition.planning.plan-expedition.
  • FR-012: The plan-expedition workflow MUST contain exactly five nodes, one for each expedition example capability.
  • FR-013: The plan-expedition workflow MUST use deterministic direct edges in the following order:
    1. capture_objective
    2. interpret_intent
    3. assess_conditions
    4. validate_readiness
    5. assemble_plan
  • FR-014: The workflow start node MUST be capture_objective.
  • FR-015: The workflow terminal node MUST be assemble_plan.
  • FR-016: The workflow-backed composed capability id MUST be expedition.planning.plan-expedition.
  • FR-017: The composed capability expedition.planning.plan-expedition MUST declare implementation_kind = workflow.
  • FR-018: The workflow-backed capability expedition.planning.plan-expedition MUST reference workflow id expedition.planning.plan-expedition.
  • FR-019: Example artifact naming across capabilities, events, and workflow ids MUST remain consistent with this slice and the approved expedition example domain.
  • FR-020: Approved implementation under this spec MUST be validated against this governing spec before merge.

Key Entities

  • Expedition Example Capability Contract: One capability contract candidate for the expedition example domain.
  • Expedition Example Event Contract: One event contract candidate emitted by an expedition example capability.
  • Plan-Expedition Workflow Artifact: The governed workflow definition connecting the five expedition example capabilities.
  • Workflow-backed Plan Capability: The composed capability identity representing plan-expedition as a first-class capability.

Non-Functional Requirements

  • NFR-001 Consistency: Capability ids, event ids, and workflow ids MUST follow one stable expedition namespace and naming pattern.
  • NFR-002 Explainability: The example workflow artifact MUST remain easy to understand from the artifact definitions alone.
  • NFR-003 Determinism: The example workflow artifact MUST not rely on heuristic path selection or ambiguous event routing.
  • NFR-004 Reusability: The example capability artifacts MUST be reusable outside the canonical workflow.
  • NFR-005 Maintainability: Example artifact semantics MUST remain separate from core Traverse runtime semantics.

Non-Negotiable Quality Gates

  • QG-001: The example artifacts MUST stay aligned with the approved expedition domain and MUST NOT drift into a different domain without a new governing spec.
  • QG-002: The AI-assisted example capability MUST remain bounded and MUST NOT take over deterministic readiness or final planning responsibilities.
  • QG-003: The plan-expedition workflow MUST remain deterministic and workflow-backed.
  • QG-004: Example artifact ids MUST be stable and machine-readable enough for later registry, workflow, and UI use.

Success Criteria

  • SC-001: Traverse has a concrete example artifact set for the expedition domain, not only a conceptual example direction.
  • SC-002: Each expedition example capability can be authored later as a governed contract without redefining its business boundary.
  • SC-003: The expedition event set can be authored later as governed event contracts without renaming or reinterpretation.
  • SC-004: The plan-expedition workflow can be authored later as a deterministic workflow definition directly from this spec.
  • SC-005: The workflow-backed composed capability relationship for plan-expedition is defined clearly enough for later registry and runtime use.

Governing Relationship

This specification is governed by:

  • 001-foundation-v0-1
  • 002-capability-contracts
  • 003-event-contracts
  • 007-workflow-registry-traversal
  • 008-expedition-example-domain
  • constitution version 1.2.0

This specification, once approved, is intended to govern future example artifact work in:

  • contracts/examples/
  • workflows/examples/
  • examples/