Solution Model

Everything Orbit renders, the Orbit agent authors, and Aurora manages is a Trajectory solution tree: a single root directory of YAML and Markdown artefacts with a fully specified on-disk shape. This page documents that base format at Trajectory v1.8 — the version the Orbit loader targets.

The master specification lives in the global methodology repo (trajectory-methodology/03-base-format/solution-tree.md), with a JSON Schema per YAML artefact under trajectory-methodology/08-schemas/. Each solution pins the version it targets via solution.yaml → trajectory — the single source of truth for the spec, file shapes, and schemas that apply to it.

Where the tree lives — the three-repo split

A solution is spread across three repositories:

The base-format spec describes registries under an optional in-solution shared/ folder (e.g. shared/assessment-types/); in the three-repo split those registries live under catalog/ in the internal repo instead. Everything else on this page is about the solution root in the customer repo.

Stages

Trajectory moves a system through three stages, each with its own lifecycle (the per-stage status enums below come from solution-schema.json):

Stage-neutral artefacts sit at the root and apply across stages: solution.yaml, charter.md, glossary.yaml, memory.md, technologies.yaml, assessments.yaml, sources.yaml, domains/{id}/domain.yaml, and sources/{source-id}/orientation.md. (technologies.yaml and assessments.yaml are stage-neutral files that internally declare per-stage activations — both split activation between as-is: and to-be: arrays.)

Per-stage artefacts live under stage/as-is/, stage/r2b/, and stage/to-be/. A component that exists in both as-is and to-be is authored as two component folders — one per stage — sharing the ID.

The solution root

The full tree (trimmed annotations; master spec: 03-base-format/solution-tree.md):

{solution-root}/
├── solution.yaml                    # identity + per-stage status + analysis-depth (v1.8)
├── technologies.yaml                # per-stage activated technology guides
├── assessments.yaml                 # per-stage activated assessment-types (optional)
├── sources.yaml                     # declared source systems for as-is (optional)
├── charter.md                       # business overview (stage-neutral)
├── glossary.yaml                    # shared vocabulary (structured)
├── memory.md                        # running log
│
├── domains/
│   └── {domain-id}/domain.yaml      # identity only; per-stage content lives under stage/
│
├── sources/                         # v1.7.1 — per-source orientation artefacts
│   └── {source-id}/
│       ├── orientation.md           # frontmatter + 11 required sections
│       ├── notes.md                 # optional hand-authored corrections
│       └── subsystem-cards/{candidate-id}.md   # optional, large codebases
│
├── stage/
│   ├── as-is/
│   │   ├── system-overview.md
│   │   ├── landscape.md
│   │   ├── assumptions.md
│   │   ├── assessments/{type-id}/{run-id}/     # run-id = YYYY-MM-DD[-NN]
│   │   │   ├── assessment.yaml + summary.md + evidence/
│   │   ├── concerns/{c-NNN-slug}/concern.yaml [+ concern.md]      # negative outcomes
│   │   ├── attestations/{a-NNN-slug}/attestation.yaml             # positive outcomes
│   │   ├── findings/{f-NNN-slug}/finding.yaml [+ finding.md]
│   │   ├── questions/{q-NNN-slug}/question.yaml [+ question.md]   # v1.8
│   │   ├── entities/{entity-id}/entity.yaml    # as-is: ID-subfolder per entry
│   │   ├── workflows/{wf-NNN-slug}/workflow.md
│   │   ├── touchpoints/{domain-id}/touchpoints.yaml
│   │   ├── domain-notes/{domain-id}/notes.md
│   │   └── components/{component-id}/
│   │       ├── component.yaml                  # stage: as-is
│   │       ├── operations/{op-id}/{operation.yaml, operation.md, specs/}
│   │       ├── stores/{store-id}/store.yaml
│   │       ├── dependencies/{target-id}/dependency.yaml
│   │       ├── integrations/{external-name}/integration.yaml
│   │       ├── auth.yaml, permissions.yaml, write-interceptors.yaml   # optional
│   │       └── packaging.md, testing.md        # optional prose sidecars
│   ├── r2b/                                    # v1.8: relocated under stage/
│   │   ├── finding-to-revision.yaml
│   │   ├── gaps.md
│   │   ├── preserve.md
│   │   ├── questions/{q-NNN-slug}/             # typically kind: decision
│   │   └── domain-diffs/                       # optional
│   └── to-be/
│       ├── vision.md
│       ├── architecture-overview.md
│       ├── assessments/ concerns/ attestations/   # same shape as as-is
│       ├── entities/{entity-id}.yaml           # to-be: flat files
│       ├── workflows/{wf-NNN-slug}.md
│       ├── touchpoints/{domain-id}.yaml
│       ├── domain-notes/{domain-id}.md
│       ├── questions/{q-NNN-slug}/             # typically kind: clarification
│       ├── capabilities/{cap-NNN-slug}/{capability.yaml, description.md}
│       ├── revisions/rev-NNN/{revision.yaml, change.md}
│       ├── stories/story-NNN/{story.yaml, notes.md}
│       └── components/{component-id}/
│           ├── component.yaml                  # stage: to-be
│           ├── operations/{op-id}.yaml         # flat
│           ├── stores/ dependencies/ integrations/   # flat
│           └── specs/                          # to-be only; driven by component.type
│
├── iterations/iteration-NNNN.yaml   # plus release-notes/retro as sibling .md
├── raw/                             # optional: interviews, exports, uploaded docs
├── repositories/                    # optional mount point for declared sources
│   ├── git/{source-id}/             # cloned; gitignored
│   └── local/{source-id}/           # hand-off content; committed
├── .generated/                      # optional rollup indexes (workflows.yaml, ...)
└── shared/                          # optional in-solution registries
    ├── technology-guides/ architecture-types/ component-types/
    └── assessment-types/{id}/{assessment-type.yaml, v1/...}

Required at the root, always: solution.yaml, charter.md, glossary.yaml, memory.md. Everything else appears as the solution grows: assessments.yaml once any assessment-type is activated, sources.yaml once the as-is analysis spans two or more codebases, stage/{stage}/ once that stage’s status is beyond not-started, iterations/ once an iteration is planned.

Root artefacts

solution.yaml

The root artefact — one per solution. Required fields: id, name, trajectory. This repo dogfoods Trajectory on itself; its real solution-definition/solution.yaml:

id: orbit
name: Orbit Platform
description: >-
  The MaxQ Labs Orbit platform: the per-solution Orbit apps (reader webapp,
  authoring agent, Mission Control) that drive the Trajectory methodology for
  a single solution, plus Aurora — the portfolio / control-plane layer ...
trajectory: "1.8"
status: "draft"
owners:
  - [email protected]
stages:
  as-is:
    status: "not-started"
  r2b:
    status: "not-started"
  to-be:
    status: "not-started"
domains: []
raw-sources: []
tags:
  - orbit-platform
  - control-plane

Schema highlights (solution-schema.json):

• id — kebab-case (^[a-z][a-z0-9-]*[a-z0-9]$), unique within the organisation.
• trajectory — pinned version string (MAJOR.MINOR[.PATCH]).
• status — draft | active | released | deprecated | archived.
• stages.{as-is,r2b,to-be}.status — the per-stage lifecycle enums in the stages table above; as-is additionally carries frozen-at (meaningful only at frozen).
• analysis-depth (v1.8, optional) — essential | full | detailed, either a single value or a per-stage object; see Analysis depth.
• domains[] — identity-only declarations (id + optional stages[]); each must resolve to domains/{id}/domain.yaml.
• architecture.{as-is,to-be} — optional architecture-type registry reference (type + version).
• raw-sources[] — optional documentation of inherited material under raw/ (kind + path required; origin, received-on, notes optional).

charter.md and memory.md

charter.md is the stage-neutral business overview — free-form Markdown, no schema. memory.md is the solution’s running log, appended to as work progresses.

glossary.yaml

Structured shared vocabulary. Required fields: solution, terms (with minItems: 1 — an empty terms: [] is invalid). From this repo’s own definition:

solution: "orbit"
description: >-
  Vocabulary for the Orbit platform ...
terms:
  - id: solution-tree
    term: solution tree
    definition: >-
      The structured, machine-readable artefact tree a Trajectory solution
      produces at each stage; the unit of work Orbit renders and Aurora
      manages across the portfolio.
    category: domain-concept
    see-also:
      - trajectory

domains/

domains/{domain-id}/domain.yaml is identity only (required: id, name; optional description, owners, status, tags) and is stable across stages. All per-stage domain content — entities, workflows, touchpoints, notes — lives under stage/{stage}/, keyed back to the domain by its domain field.

assessments.yaml

Activates assessment-type registry entries per stage with pinned versions ('latest' is not valid). The MAJOR component of the pin selects the v{MAJOR}/ subfolder of the registry entry.

# assessments.yaml — per-stage activation of assessment-types
as-is:
  - assessment-type: transport-security   # illustrative activation
    version: "1.0"
to-be: []

Each activation produces, per run, a folder at stage/{stage}/assessments/{assessment-type-id}/{run-id}/ — see the assessment triple below.

sources.yaml and sources/ (v1.7.1)

sources.yaml declares the source systems the as-is stage analyses. Optional: a single-codebase analysis can rely on the implicit-root convention; it becomes required once the analysis spans two or more codebases, so file: source-refs can disambiguate via the source-id prefix. Per source (sources-schema.json): id (required; becomes the directory name under repositories/git/ or repositories/local/), kind (git | local, auto-detected when omitted), url (required when kind: git), ref, github-account, description, primary-language, origin, received-on, notes.

Each catalogued source gets an orientation at sources/{source-id}/orientation.md: YAML frontmatter (validated by orientation-frontmatter-schema.json; required source-id, source-ref, generated-at) plus a free-form body steered by eleven required sections, in order:

1. Identity · 2. Folder map · 3. Entry points · 4. Subsystem-candidates ·
2. Data-layer map · 6. Operation surface · 7. External integrations ·
3. UI surfaces (omitted entirely when the source has no UI) ·
4. Cross-cutting concerns · 10. Glossary candidates · 11. Anomalies

---
source-id: opvangsd-api
source-ref: a1b2c3d4e5f6          # SHA for kind:git; received-on date for kind:local
generated-at: 2026-05-21T14:33:00Z
generator: [email protected] # optional
---

Orientations are generated once per source ref by the source-cataloguer agent and re-read by every downstream walker; they regenerate only when the materialised ref diverges from the frontmatter’s source-ref. Human corrections go in the sibling notes.md, never into orientation.md itself. Large codebases split section 5–9 detail into subsystem-cards/{candidate-id}.md (frontmatter adds card-id, optional parent-card).

Per-stage artefacts

Entities

entity-schema.json — required: id, name, domain, stage, fields. Notable structure:

• category — master-data | transaction | reference | configuration | data-quality | projection.
• sensitivity — public | internal | confidential | personal-data | special-category (also per field).
• identity.primary-key + identity.natural-keys[], where each natural key records where uniqueness is actually enforced: db | app | none (app implies a race window; none is a documented but unenforced rule).
• fields[].type — open vocabulary (string, date, money, …) plus cross-entity references: ref:{entity-id}, or the cross-store forms ref:{component-id}/{entity-id} and ref:{store-id}:{entity-id} (logical pointer, no FK enforced).
• lifecycle (states/transitions/initial), relations[] (cardinality 1..1 | 0..1 | 1..n | 0..n), invariants[], optional single parent inheritance (max depth 2, abstract parents allowed).
• v1.8 sidecars: any field may carry <field>-confidence / <field>-source-ref siblings (see the honesty layer).

As-is entities live at stage/as-is/entities/{entity-id}/entity.yaml; to-be entities are flat at stage/to-be/entities/{entity-id}.yaml.

Workflows

Markdown documents with YAML frontmatter (workflow-schema.json validates the frontmatter — required id, name, domain; optional participating-domains, stage, status draft | documented | archived, components-involved, source-refs, tags). As-is: stage/as-is/workflows/{wf-NNN-slug}/workflow.md; to-be: stage/to-be/workflows/{wf-NNN-slug}.md.

Touchpoints and domain-notes

touchpoints/{domain-id}/touchpoints.yaml (as-is) / touchpoints/{domain-id}.yaml (to-be) is the per-domain polymorphic rollup of where users and systems touch the domain (touchpoints-schema.json, required entries[]). domain-notes/{domain-id}/notes.md holds optional free-form per-domain notes.

Components

A component is “a deployable or runnable unit” (component-schema.json — required: id, name, stage, status). A component present in both stages is two folders, one per stage, sharing the ID:

stage/as-is/components/opvangsd-api/
├── component.yaml            # stage: as-is
├── operations/               # {op-id}/operation.yaml + optional operation.md + specs/
├── stores/                   # {store-id}/store.yaml
├── dependencies/             # {target-id}/dependency.yaml
└── integrations/             # {external-name}/integration.yaml

stage/to-be/components/opvangsd-api/
├── component.yaml            # stage: to-be
├── operations/               # flat: {op-id}.yaml
├── stores/ dependencies/ integrations/   # flat
└── specs/                    # to-be only — OpenAPI, app-spec, JGF process files

Identity fields (id, name, domain, type when set) must agree across the two files; stage-specific fields (status, platform, runtime-kind, language, source-refs, packaging, testing) are authored per stage, and stage: must match the parent folder. Schema highlights:

• stage — as-is | to-be; status — planned | draft | active | deprecated | retired.
• type (component-type registry reference) requires type-version when set.
• Open vocabularies: kind (api-backend, admin-console, batch-program, …), platform, language, runtime-kind; technologies[] lists active guide IDs.
• testing — suites by name, not by quality (coverage is an informational hint: none | scaffold-only | partial | comprehensive | unknown; an empty suites: [] is legal and meaningful — “tests were looked for and none were found”). Quality assertions belong in findings.
• packaging — artefact-kind, build-recipe-ref, and named config-inputs[] / secret-inputs[] (names only, never values). Long narrative goes in the packaging.md / testing.md prose sidecars.
• source-refs[] — prefixed references (^[a-z][a-z0-9-]*:.+$), e.g. file:src/App.cs or cobol-program:ACCT0100.

Per-component sub-artefacts:

• Operations (operation-schema.json, required id, component, kind, trigger) — endpoints, jobs, handlers; carry contract-ref, touches-entities, touches-stores, auth-required, idempotent, etc. As-is operations may carry an optional operation.md behaviour companion (mermaid sequence diagram); to-be operations never do.
• Stores (store-schema.json, required id, name, component, kind) — with ownership owned | shared | external, entities[], and cross-store-refs[].
• Dependencies — in-solution component-to-component edges; integrations — edges to external systems.
• Optional auth.yaml, permissions.yaml, write-interceptors.yaml.

Findings

An as-is observation worth acting on (or explicitly not acting on), always source-grounded. finding-schema.json — required: id, title, domain, severity, category, status.

# stage/as-is/findings/f-021-unhandled-concurrency/finding.yaml (illustrative values)
id: f-021-unhandled-concurrency
title: Concurrent reservation writes are not guarded
domain: billing
severity: high
category: correctness
status: confirmed
confidence: confirmed          # v1.8, optional; absent ⇒ confirmed
source-refs:
  - "file:src/api/reservations.cs:42-110"

• id — f-NNN-slug (^f-[0-9]+-...$); the folder name equals the id.
• severity — info | low | medium | high | critical.
• category — closed 9-value vocabulary: security | correctness | availability | performance | maintainability | compliance | operational | documentation | data-quality.
• status — draft | confirmed | addressed | dismissed.
• polarity — negative (default) or positive (a thing done well, worth preserving); orthogonal to category.
• source-refs[] — minItems: 1; findings must be source-grounded. evidence[] holds independently verified source-refs, while extracted-from[] records inherited material (a prior audit, an interview) the finding surfaced from before verification — entries migrate from extracted-from to evidence as they are verified.
• suggested-revision-kind — optional R2B hint: rewrite | refactor | patch | policy | preserve | new-capability.

R2B artefacts

The bridge stage owns finding-to-revision.yaml (the mapping of as-is findings to to-be revisions), gaps.md, preserve.md, optional per-domain domain-diffs/, and its own questions/ (typically kind: decision). Since v1.8 it lives at stage/r2b/, a peer of as-is/ and to-be/.

To-be planning chain

• Capabilities (capability-schema.json — required id, name, domain, status, first-revision) at stage/to-be/capabilities/{cap-NNN-slug}/ with a description.md.
• Revisions (revision-schema.json — required id, name, capability, revision-number, domain, status, functional-changes; status proposed | accepted | in-progress | delivered | cancelled) at stage/to-be/revisions/rev-NNN/ with a change.md.
• Stories (story-schema.json — required id, name, revision, capability, domain, component, area-type, status, acceptance-criteria; area-type is backend | frontend | data | integration | ops) at stage/to-be/stories/story-NNN/.
• Iterations at iterations/iteration-NNNN.yaml group stories into delivery cycles.

Capabilities and revisions also accept the v1.8 top-level confidence field.

Assessments, concerns, attestations (v1.7)

v1.7 disentangled the overloaded word “concern” into four artefact kinds. Rule of thumb: the -type suffix means registry definition; the bare noun means an instance/output.

The run’s assessment.yaml (required: assessment-type, assessment-type-version, run-id, stage, started-at, completed-at, assessed-by, coverage, verdict-counts) makes it queryable: coverage[] lists every artefact assessed as a typed reference, verdict-counts tallies outcomes by status, and concerns-emitted[] / attestations-emitted[] / findings-emitted[] link the outputs.

Concerns and attestations both target exactly one artefact via a typed applies-to reference with a closed prefix vocabulary:

(solution|component|domain|store|entity|operation|workflow|dependency|integration|finding):<identifier>
# e.g. store:opvangsd-db · operation:opvangsd-api/post-intakes

Resolution is bidirectional: when a later run finds a previously-failed condition now passes, it emits an attestation whose resolves-concerns[] lists the prior concern IDs, and each of those concerns flips to status: resolved with resolved-at, resolved-by-run, and resolved-by-attestation populated — validators enforce that both directions agree. Re-confirmations of a still-standing concern append the run-id to its confirmed-by-runs[] while assessment-ref keeps pointing at the original raising run.

The honesty layer (v1.8)

Three additive features let a solution say not just where a fact came from (source-refs) but how sure it is, and give “ask the human” a formal channel. Every part defaults to pre-v1.8 behaviour when absent.

Calibrated confidence

The enum is confirmed | inferred | gap — rendered as green/amber/red in Orbit. Absence means implicit confirmed, so every pre-v1.8 artefact reads unchanged.

• Pattern A (structured). Single-claim artefacts (findings, capabilities, revisions) take a top-level confidence field. Many-claim artefacts (component.yaml, operation.yaml, store.yaml, entity.yaml) attach confidence per field via sidecars admitted by schema patternProperties:

  idempotent: false
  idempotent-confidence: inferred
  idempotent-source-ref: "file:src/api/reservations.cs:42-110"
  # inferred: no idempotency-key handling was found — absence is evidence, not proof

• Pattern B (narrative). In Markdown prose, sentences/paragraphs are prefixed with the matching emoji (green = confirmed, amber = inferred, red = gap/undetermined).

Promotion: gap → inferred when a human answers a question (the answer becomes the source-ref); inferred → confirmed when subsequent evidence is found. Demotion is allowed when review reveals over-confidence. confidence is orthogonal to status: a status: confirmed finding may still carry confidence: inferred.

The questions loop

An open item requiring human input — distinct from a finding (something wrong), a concern (assessment outcome), and a revision/story (planned work). One folder per item at stage/{stage}/questions/{q-NNN-slug}/ in all three stages, containing question.yaml (+ optional question.md).

question-schema.json — required: id (q-NNN-slug), title, kind, stage, status, asks-about (≥ 1 resolving artefact refs), raised-by (ai:<agent> or human:<name>), raised-on.

• kind — information-gap (typically as-is; drives the gap-confidence-promotion loop) | decision (typically r2b) | clarification (typically to-be). The mapping is typical, not enforced.
• status — open | answered | dismissed | deferred. Conditionals are schema-enforced: answered requires answer, answered-by, answered-on, and a non-empty promoted-to[]; dismissed requires dismissed-reason.
• blocks[] — items or transitions the question gates; R2B cannot reach accepted while an open question underpins one of its decisions.

Worked example from the methodology (trimmed):

# stage/as-is/questions/q-001-payment-timeout-policy/question.yaml
id: q-001-payment-timeout-policy
title: Payment gateway timeout policy is undocumented
kind: information-gap
stage: as-is
status: answered
asks-about:
  - "stage/as-is/components/opvangsd-api/operations/post-reservations/operation.yaml"
raised-by: "ai:archaeologist"
raised-on: "2026-05-01"
answer: >
  No automated timeout handling exists. Support manually retries the next
  business morning. This is an operational workaround, not designed behaviour.
answered-by: "human:patrick"
answered-on: "2026-05-08"
promoted-to:
  - "stage/as-is/components/opvangsd-api/operations/post-reservations/operation.yaml"
confidence-effect: confirmed
domain: billing

The answer-promotion contract: the answer lands in the asks-about artefacts’ narratives (each citing the question id), promoted-to[] records where, and for information-gap questions the referenced claim’s confidence is reclassified to confidence-effect (gap → inferred, or gap → confirmed when the answer is authoritative).

Analysis depth (v1.8)

solution.yaml → analysis-depth declares intended documentation depth — essential | full | detailed — as a single value or per stage:

analysis-depth:
  as-is: full
  r2b: essential
  to-be: full

Absent means full for every stage (the pre-v1.8 implicit standard). Depth drives x-expected-at-depth completeness warnings on schemas that carry the annotation (touchpoints, entities, workflows); it never makes an existing artefact invalid.

Naming rules and validation

• All file and folder names are kebab-case; no spaces. (README.md / CLAUDE.md at the tree root are the only exceptions.)
• ID-subfolder artefacts: the folder name carries the ID, the inner file is named for the artefact type (entity.yaml, workflow.md, operation.yaml, question.yaml, …). Flat artefacts: the filename matches the ID.
• Counter-based IDs are solution-wide: f-NNN-slug (findings), c-NNN-slug (concerns), a-NNN-slug (attestations), q-NNN-slug (questions), rev-NNN, story-NNN, cap-NNN-slug.
• Structural validation checks: required root files exist, all referenced IDs resolve to files on disk, no duplicate IDs at the same level, folder names match their id: fields. Full rules: 07-governance/validation.md.

Version history

What changed across the recent format versions (migration recipes live in trajectory-methodology/09-migration/):

The methodology repo freezes each release under releases/v<X.Y>/; a solution vendors the snapshot matching its solution.yaml → trajectory pin.