Add OnlineWardleyMaps (OWM) syntax validation for generated Wardley artefacts

[tractorjuice]

Problem

ArcKit Wardley commands (/arckit:wardley, /arckit:wardley.value-chain, /arckit:wardley.doctrine, /arckit:wardley.gameplay, /arckit:wardley.climate) emit OnlineWardleyMaps (OWM) DSL inside fenced ```wardley / ```owm blocks. There is no parse-time validation, so syntactically broken maps are written, committed, and indexed by the docs/pages site before anyone notices.

This is the sibling issue to #435 (Mermaid syntax validation). Same hook architecture, different parser.

Why this needs its own validator

The Mermaid validator from #435 covers the Mermaid blocks that appear alongside OWM in the Wardley templates (templates/wardley-map-template.md mixes both languages). It does not cover the OWM blocks themselves — they need an OWM parser.

Concrete failure classes the model produces

• Out-of-range coordinates — OWM plane is unit square [0, 1]; LLM-generated maps occasionally write 0.45, 1.2 or negative values.
• Dangling references — link A -> B, evolve C 0.7, or pipeline [Foo] referencing components that were never declared (or were renamed earlier in the block).
• Inertia / evolve syntax mix-ups — evolve A 0.7 vs evolve+>> A 0.7 vs trailing inertia.
• Annotation drift — annotation 1 [0.4, 0.5] text where annotation index 1 is reused or annotations [0.6, 0.1] block coordinates outside the plane.
• Pipeline bracketing — pipeline [Foo] with no matching declared component, or coordinates that put pipeline endpoints below visibility 0.
• Style typos — style wardely / style handritten / unknown style names.

These all parse cleanly as text but fail when OnlineWardleyMaps actually tries to render them.

Suggested approaches

(Mirroring #435 — pick whichever fits the existing hook architecture.)

1. PreToolUse:Write hook (owm-block-scanner.mjs) — extract every ```wardley and ```owm block, parse via the OWM parser, block on parse failure with line-anchored error messages. Same JSON-blocking contract as secret-file-scanner.mjs.
2. Post-generation validation in the Wardley commands — each /arckit:wardley.* command runs its emitted block through the parser before writing.
3. CI / pre-commit walker — scan projects/**/*.md for OWM blocks and validate.
4. Template-level guard rails — augment skills/wardley-mapping/references/mapping-examples.md and the wardley template prompts with explicit cautions: declare-before-link, coordinates ∈ [0,1], one annotation index per map.

(1) or (2) gives the fastest feedback loop. (4) is cheap and complementary.

Parser options

• wardley-script-parser (npm — extracted from OnlineWardleyMaps source) — produces a JSON AST and surfaces parser errors with line numbers.
• @owm/parser — same upstream, packaged differently.
• Vendored copy of OnlineWardleyMaps' parser — if avoiding an npm dependency in hooks is preferred.

All three are MIT-compatible.

Scope clarification vs #435

• Add Mermaid syntax validation for generated diagrams (linter / pre-commit hook) #435 = Mermaid blocks (every command, including the Mermaid blocks inside Wardley templates).
• This issue = OWM/Wardley DSL blocks specifically.
• The two hooks should coexist; there's no overlap in what they parse.

Environment

• ArcKit plugin v4.14.0
• Templates with OWM blocks: templates/wardley-map-template.md, templates/wardley-value-chain-template.md, plus the wardley-mapping skill examples.
• Encountered while discussing Add Mermaid syntax validation for generated diagrams (linter / pre-commit hook) #435 in tractorjuice/arckit-test-project-v48-arckit-as-a-service.

Related

• Add Mermaid syntax validation for generated diagrams (linter / pre-commit hook) #435 — sibling issue for Mermaid blocks

[tractorjuice]

Two prior-art notes before anyone starts:

hooks/validate-wardley-math.mjs already exists and is unwired.

The hook (271 lines) currently does:

1. Stage-evolution alignment against the Component Inventory table
2. Coordinate range validation ([0.00, 1.00])
3. OWM syntax consistency (wardley block vs Component Inventory)
4. Mermaid wardley-beta bare-digit token check

It's not registered in hooks/hooks.json. Suggested first step is to wire it up under PreToolUse: Write with if: "Write(/projects/**/wardley-maps/**)" (matching the existing pattern for validate-arc-filename.mjs and score-validator.mjs).

That covers (a), (b)-partially, and (d) from the issue's failure-class list. The remaining classes (dangling refs in link/evolve/pipeline, annotation index reuse, style-name typos, pipeline coordinates below visibility 0) need a real OWM parser, not regex.

Parser choice: wardley-script-parser (pure JS, no browser).

Same constraint as the Mermaid issue (#435): PreToolUse hooks live in a millisecond budget. wardley-script-parser produces a JSON AST with line-anchored errors and has no headless-browser dependency. That's the right pick over vendoring the OnlineWardleyMaps source.

Consider a shared hook with #435.

A single diagram-block-scanner.mjs that dispatches by fence language (mermaid vs wardley/owm) avoids duplicating the file-scanning, block-extraction, and JSON-blocking boilerplate twice. One registration entry, one telemetry path, one place to add PlantUML next.

Suggested scope for this issue:

1. Wire validate-wardley-math.mjs into hooks.json
2. Extend it (or fold it into a shared diagram scanner) with wardley-script-parser to catch the parser-class failures
3. Cover both wardley and owm fence aliases
4. Coexist with the Mermaid validator from Add Mermaid syntax validation for generated diagrams (linter / pre-commit hook) #435 (they parse different blocks within the same Wardley templates)