/arckit:wardley Mermaid block applies sourcing decorators by evolution band, producing decorator-soup that hides signal

[tractorjuice]

Summary

The /arckit:wardley command instructs the LLM to enrich the wardley-beta Mermaid block with sourcing decorators based on the component's evolution band:

"Components with evolution < 0.50 that are strategic differentiators: (build). Components procured from market (Product stage): (buy). ... Commodity/utility components: no decorator (or (buy) if via G-Cloud/marketplace). Components with identified inertia: append (inertia)."

Applied as written, this produces blanket annotation: every Custom-band component gets (build), every Product/Commodity gets (buy). On a 39-component map, ~95% of nodes end up decorated. The decorators stop carrying information beyond what the X-axis position already communicates, and the rendered Mermaid loses the per-node visual differentiation the decorators were supposed to provide.

Reproduction

Run /arckit:wardley against any project with ≥ 20 components covering the full evolution range. Inspect the generated wardley-beta block. Result: most components decorated; the OWM block (canonical Wardley, no decorators) is the cleaner artefact.

Concrete example: projects/003-arckit-consulting/wardley-maps/ARC-003-WARD-001-v1.0.md.

• Original (commit 5177994): 24 (build) + 20 (buy) + 6 (inertia) decorators on 41 nodes.
• Cleaned-up (commit a49a268): 2 (inertia) decorators only — applied where they communicate something the position cannot (GA-timing dependency on ArcKit Project 001 SaaS / 002 Sovereign).

Root Cause

The current instruction maps decorators to evolution bands (if evolution < 0.50: (build)) rather than to strategic exceptions to position-implied sourcing. Position-driven Wardley Mapping already communicates build / buy / use intent via the X-axis; a decorator that restates the position is redundant.

Proposed Fix

Change the decorator-enrichment block in commands/wardley.md from band-mapping to selectivity-guarded:

Current (paraphrased):

The Mermaid version adds sourcing decorators derived from the Build vs Buy analysis: evolution < 0.50 → (build); Product → (buy); commodity → no decorator; inertia → (inertia).

Proposed:

The Mermaid version applies sourcing decorators selectively — only where the decorator communicates something the position cannot. Default: no decorator (the X-axis evolution position already implies build / buy / use). Apply a decorator only when:

• The position-implied sourcing is deliberately overridden (e.g., a Commodity component you've chosen to build, or a Genesis component for which a buy decision was forced — flag the anti-pattern).
• The component has external timing or dependency inertia that the position cannot show — append (inertia).
• In rare cases, the component is internally constructed in-house and a visual marker would help non-Wardley-fluent readers — append (build) only on those constructed artefacts, not on policies, governance bodies, capabilities, methods, or outcomes.

Avoid blanket application. If more than ~25% of components have the same decorator, the decoration has stopped carrying signal — remove it.

Related Evidence (already in the plugin)

This is consistent with how /arckit:wardley.value-chain already handles decorators:

• commands/wardley.value-chain.md:320: "Mermaid wardley-beta equivalent in collapsible <details> block (no sourcing decorators at value chain stage)"
• commands/wardley.value-chain.md:324: "At the value chain stage, no sourcing decorators are used (build/buy analysis has not been performed yet)."
• skills/wardley-mapping/references/mapping-examples.md:525: "the wardley-beta Mermaid block uses the same coordinates but omits sourcing decorators"

The plugin author has already articulated the principle elsewhere; the /arckit:wardley command is the inconsistent one.

Out of Scope (mentioned for completeness)

A deterministic OWM → wardley-beta converter would eliminate the editorial-drift problem entirely. All of the syntactic differences are mechanical (quote tokens that contain hyphens / dots / digits / slashes; convert note text [v,e] → note "text" [v,e]; convert annotation comma form; nest pipelines; drop style wardley and evolve label). This would be ~200 LOC of Node.js. Not asking for it here — just noting that the validator (hooks/validate-wardley-math.mjs) already operates between the two representations, so a converter would have a natural home next to it.

Validator Note

The current validator hooks/validate-wardley-math.mjs catches OWM ↔ Mermaid coordinate drift and unquoted bare-digit tokens — but does not catch decorator-bloat. Optional: add a soft warning when ≥ 70% of Mermaid components share the same decorator (likely a sign of blanket application).

---

Filed against ArcKit v4.19.0; /arckit:wardley command in commands/wardley.md.

[tractorjuice]

Update: The converter already exists in your own repo

A deterministic OWM → wardley-beta converter exists at:

tractorjuice/wardleymap_math_model/scripts/owm_to_mermaid.mjs (12.7 KB, ~370 LOC, ESM module exporting convert(owm, filename)).

Per the file's own header comment:

"Derived from tractorjuice/arc-kit's tests/mermaid-wardley/convert.mjs with added explicit-block pipeline handling and evolution-stage quoting."

That precursor (tests/mermaid-wardley/convert.mjs) is no longer in the arc-kit main branch — either removed or never merged. Either way, the runtime /arckit:wardley command does not call it; the LLM authors the Mermaid block from scratch.

Why this matters for the original issue

The converter handles decorator emission correctly by construction:

const sourcing = {};                             // name → 'build'|'buy'|'outsource'
const SRC_RE  = /^(build|buy|outsource)\s+(.+)$/i;

// Pass 1: collect explicit sourcing declarations from OWM source
for (const raw of lines) {
  const ms = s.match(SRC_RE);
  if (ms) sourcing[ms[2].trim().toLowerCase()] = ms[1].toLowerCase();
}

// Pass 2: emit only what the OWM author asked for
if (sourcing[cname.toLowerCase()]) decorators.push(`(${sourcing[cname.toLowerCase()]})`);
if (hasInertia) decorators.push('(inertia)');

Decorators only appear in the Mermaid output when the OWM source explicitly contains build X, buy Y, or outsource Z lines (a real OWM extension — see OnlineWardleyMaps sourcing syntax). And (inertia) is emitted from the inertia keyword on a component line. No band-mapping, no LLM editorial layer, no decorator-soup.

This is exactly the principle the issue body argues for — it just needs to be plumbed through.

Revised recommendation (supersedes the prompt-edit suggestion in the issue body)

Rather than tweaking the prompt to instruct the LLM to be more selective about decorators (which depends on LLM discretion every time), the cleanest fix is:

1. Pull owm_to_mermaid.mjs into the arc-kit plugin at e.g. scripts/owm_to_mermaid.mjs.
2. Have /arckit:wardley author only the OWM block. Decorators in OWM come from explicit build X / buy Y / outsource Z lines (which the LLM should add selectively, only where the position-implied sourcing is being deliberately overridden).
3. Mechanically derive the Mermaid block from the OWM via the converter — ideally as a hook (alongside validate-wardley-math.mjs) or as a step the command runs via node scripts/owm_to_mermaid.mjs <owm-file>.
4. Update the validator (validate-wardley-math.mjs) to assert that the Mermaid block matches what the converter would produce from the OWM block — making editorial drift impossible.

Result: the LLM's editorial responsibility shrinks to "decide whether to add a build/buy/outsource line in OWM," not "translate OWM into Mermaid while applying decorators by band." Mermaid output becomes a deterministic function of the canonical OWM source. The validator catches drift. Issue closed permanently, not just for one regeneration.

Bonus

The converter also handles all the syntactic translation correctly: name quoting (hyphens / dots / digits / slashes / keyword-prefix like labelling), evolution stage quoting, pipeline both proximity-based and explicit-block forms, note quoting, annotation comma form, style wardley stripping, evolve label stripping. ~370 LOC vs ~200 LOC I estimated — accurate-but-pessimistic estimate; the harder cases (pipeline detection, evolution stage with @boundary and / secondaryName) are already solved.

Happy to draft the integration PR if useful.

[tractorjuice]

Already fixed in #451 (merged 2026-05-07, shipped in v4.19.2).

PR #451 implements the converter-integration path the comment thread settled on:

• Vendored arckit-claude/scripts/owm-to-mermaid.mjs (364 LOC) — deterministic OWM → Mermaid wardley-beta converter.
• Replaced the band-mapping decorator instructions in commands/wardley.md (lines 235–277) with a three-step procedure: write OWM to a temp file, run the converter, paste stdout verbatim into the <details> block. Includes the explicit note: "Do not re-author the wardley-beta block by hand."
• Sourcing decorators now only appear on the Mermaid output when the OWM source contains explicit build X / buy Y / outsource Z lines (or inertia on the component line). No band-mapping, no LLM editorial layer.

Decorator-soup is mechanically impossible: the LLM no longer authors Mermaid; the converter does.

Validator-assertion follow-up (step 4 in the comment's plan — making the validator check Mermaid matches what the converter would produce from OWM) is not in #451 and remains parked. Happy to file a fresh issue for that if you want to track it separately; it's small enough now that the converter is in-tree.