Skip to main content

0026: Retire The Redundant Visual Capability Manifest

Status: Accepted

Context​

STAGE corrected its first detached visual-evidence workflow by moving review back into the engine and, when persistence was earned, into a product-native Visual Almanac. It then added a separate versioned Visual Almanac capability manifest, schemas, templates, validator, and compatibility tests to describe subject sources, entry points, presentation, lifecycle, evidence, and limitations.

Lanternworks dogfood showed that the useful product was the in-game Borough Almanac and its ordinary project operation. The same repository's existing STAGE project map already records the Almanac's source paths, authoring surfaces, callable operation, readiness, effects, evidence, and limitations. No runtime, authoring tool, or independent maintainer consumes the separate capability manifest. Its validator proves only that STAGE's duplicate description is internally coherent.

This is the metadata form of the earlier evidence-first inversion: a secondary control plane became easier to elaborate than the native review loop it was supposed to describe.

Decision​

  • Keep direct engine-native Visual Review as the default activity.
  • Keep the optional product-native Visual Almanac and Native Review Driver when recurring questions, expensive setup, or player utility earn them.
  • Record a persistent route in the project's ordinary map and operating docs: canonical subject and Scenario sources, human and agent entry points, truth and temporal modes, human-owned settings, readiness, reset, teardown, evidence, and limitations.
  • Do not maintain a second visual-specific manifest, schema family, template, validator, or compatibility version.
  • Keep real project content, Scenario authoring, and presentation data under their existing project owners rather than copying them into STAGE metadata.
  • Preserve the retired interface in Git history. Current STAGE tooling does not validate it, and projects may delete local copies without changing their native review capability.

This decision supersedes the capability-manifest retention in ADR 0025 and the active interface decisions in ADRs 0010 through 0015. Their observations about control, state, sight, subject ownership, temporal semantics, runtime hosts, and fresh-launch parity remain valid guidance for native operations.

Consequences​

  • The useful native review workflow remains intact and becomes easier to explain and adopt.
  • Lanternworks deletes 202 lines of duplicated declaration while retaining its complete Almanac operation in .stage/project.yaml.
  • STAGE removes four versioned schemas, an alias, two templates, a validator, and their dedicated test suite.
  • A project map is orientation and an operation contract, not proof that the engine ran or that visuals satisfy product intent. Native execution, observation, and human judgment remain separate evidence.
  • STAGE gives up compatibility for an unconsumed pre-1.0 interface. This is an intentional simplification rather than a migration to another artifact.

Revisit When​

Introduce a separate interchange format only when at least two independent tools or repositories must exchange native-review capability and cannot do so through their ordinary project maps. Name the consumer, compatibility need, and migration cost before adding the format.

Last updated on