gardens-of-nil-3d-u6/discussion/workflow/plans/PLN-0001-world-journey-spec.md

id	ticket	title	status	created	decisions	tags
PLN-0001	world-editor-journey-spec	World Editor / Journey V1 Spec	done	2026-06-19	DEC-0001	spec world-editor journey

Briefing

Write the canonical English specification for the World Editor / Journey V1 contract accepted in DEC-0001. This plan produces documentation only. It does not implement Unity code.

Source Decisions

• DEC-0001: World Editor / Journey V1.

Target

Create or update the canonical spec location used by this repository with an English spec covering:

• WorldLayoutSO as editor authoring data.
• JGraphSO as runtime Journey data.
• JStage, JEndpoint, JEndpointSocket, JEndpointAnchor, JEndpointLift, and JConnection.
• World tile/layer defaults and configurability.
• Commit/publication boundary.
• Validation error and warning rules.
• V1 exclusions.

Scope

• Inspect the repository for the canonical spec/docs location before editing.
• Add an English World Editor / Journey V1 spec if none exists.
• If a relevant spec already exists, update it instead of creating a parallel source of truth.
• Link the spec back to DEC-0001.
• Document that runtime Journey code lives outside Assets/Scripts/Editor.
• Document that Stage bake remains owned by the Stage Editor.

Out Of Scope

• C# implementation.
• Unity Editor UI implementation.
• Stage Editor changes.
• Loading hints, concrete requirements, deep Stage marker sync, and editor unification.

Execution Plan

1. Locate canonical docs/specs.

   • Use rg --files to find existing spec, docs, or design contract files.
   • Target the existing canonical location if present.
   • If no canonical spec location exists, create a minimal specs/ or repository-approved equivalent only after confirming repo convention from nearby files.

2. Draft the V1 spec.

   • Add sections for authoring model, runtime model, endpoint model, connection model, commit flow, validation, and exclusions.
   • Use normative language: MUST, MUST NOT, SHALL, SHOULD, and MAY.
   • Keep the spec in English.

3. Define V1 data contracts in prose.

   • WorldLayoutSO: default worldTileSize = 24m, default worldLayerHeight = 24m, stages, occupied tiles, authoring endpoints, and editor metadata.
   • JGraphSO: sourceWorldLayoutId, publishedAt, schemaVersion, optional contentHash, JStage[], JEndpoint[], and JConnection[].
   • JStage: logical runtime stage record, not scene generation data.

4. Define validation levels.

   • Errors block commit.
   • Warnings do not block commit.
   • Required endpoint without connection is an error.
   • Optional endpoint without connection is a warning.

5. Document non-goals.

   • No loading hints in V1.
   • No concrete requirements in V1.
   • No Stage scene generation from World Editor commit.
   • No automatic World Editor to Stage Editor integration in V1.

Acceptance Criteria

• The spec is in English.
• The spec references DEC-0001.
• The spec names WorldLayoutSO and JGraphSO.
• The spec states that Journey elements use prefix J, and Journey ScriptableObjects use suffix SO.
• The spec states that World Editor commit publishes only logical Journey data.
• The spec states that runtime MUST consume JGraphSO, not WorldLayoutSO or StageDefinition.

Validation

• Review the spec against every invariant in DEC-0001.
• Search the spec for residual Portuguese text before finalizing.
• Confirm no duplicate contradictory spec was created.
• No automated tests are required for this plan.

Risks

• The repository may not yet have a canonical specs directory.
• If spec location is unclear, stop before creating a new documentation tree and ask for direction.
• Over-documenting future features could accidentally make them V1 commitments.