@formicoidea/labre-framework-wardley 0.31.0 → 0.32.0

package/dist/nudges.js

@@ -0,0 +1,69 @@
+/**
+ * Wardley **map quality** — the checklist (PF13.9).
+ *
+ * Level 1 is `./rules.ts`: deterministic, decidable, real time. This file is
+ * level 2, and the split is the whole point of the taxonomy — a rule only enters
+ * the deterministic engine if an algorithm can decide it on persisted data
+ * inside the ~16 ms budget. Everything else is a NUDGE: an expectation offered
+ * as a checklist, never evaluated, never blocking anything. Ticking is assuming.
+ *
+ * ## The check-up rules are gone (PO decision, 02/08/2026)
+ *
+ * Q5 (tone convention) and Q6 (phase nomenclature) used to live beside these,
+ * as on-demand rules behind a "Run check-up" button. The panel is now the
+ * checklist and nothing else: the PO's recette found that a second verdict, a
+ * button and a scope line asked the reader to hold three different kinds of
+ * statement in their head over a map that mostly wanted a title. Nothing was
+ * deleted from the platform — the on-demand MOMENT (PF5.14) and the
+ * `tone-convention` / `majority-fact` families are still in the engine, still
+ * tested, and the next framework that wants a check-up declares one. Wardley
+ * simply stopped exposing one.
+ *
+ * Registered from the flag-gated `WardleyViewExtension`, beside the rules and
+ * the profiles: a checklist is tooling. Switching the flag off takes it away and
+ * leaves the ticks written on the map, unread, until it comes back (PF7.10).
+ */
+/**
+ * **Q1–Q4** — the four things a Wardley map needs in order to do its job, and
+ * that no algorithm can check.
+ *
+ * Every one of them is about whether the map can be DISCUSSED. A map with no
+ * title is a diagram nobody can situate; one with no legend is a private
+ * notation; one whose evolution axis is drawn but not used is a value chain
+ * wearing a Wardley costume. The tool can put all four on screen and it cannot
+ * judge a single one — "the title contextualises the study" is a statement about
+ * meaning, and a rule claiming to have verified it would be lying.
+ *
+ * The wordings are the PO's own, from the review of 01/08/2026, carried as
+ * `fallback` so a host with no catalogue reads them exactly as written.
+ */
+export const WARDLEY_NUDGES = [
+    {
+        id: 'wardley.q1-title',
+        framework: 'wardley',
+        labelKey: 'com.labre.wardley.quality.title',
+        fallback: 'The map has a title that frames the study (scope, objective) and states what kind of map it is.',
+        order: 1,
+    },
+    {
+        id: 'wardley.q2-context',
+        framework: 'wardley',
+        labelKey: 'com.labre.wardley.quality.context',
+        fallback: 'The context of the map is stated.',
+        order: 2,
+    },
+    {
+        id: 'wardley.q3-legend',
+        framework: 'wardley',
+        labelKey: 'com.labre.wardley.quality.legend',
+        fallback: 'The map is legended.',
+        order: 3,
+    },
+    {
+        id: 'wardley.q4-evolution-axis',
+        framework: 'wardley',
+        labelKey: 'com.labre.wardley.quality.evolution-axis',
+        fallback: 'The evolution axis is used and legended.',
+        order: 4,
+    },
+];

package/dist/profiles.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationProfile } from '@formicoidea/labre-core/blocks/surface';
+export declare const WARDLEY_PROFILES: readonly ValidationProfile[];

package/dist/profiles.js

@@ -0,0 +1,87 @@
+/**
+ * Wardley validation profiles (PF9).
+ *
+ * DATA owned by the framework, like its rules, its roles and its background:
+ * the engine knows how to APPLY a profile, never which ones Wardley has. Adding
+ * a level of requirement is adding an entry to this array.
+ *
+ * A profile is chosen per MAP, not per document (PF9.1) — a rough sketch and a
+ * deliverable diagram coexist on the same canvas with different requirements,
+ * and the choice rides on the background element itself.
+ *
+ * Registered from the flag-gated `WardleyViewExtension`, beside the rules:
+ * switching the Wardley flag off takes the choice away with the rest of the
+ * tooling, and a map already set to `strict` simply stops being checked until
+ * it comes back — the id stays written, untouched.
+ */
+/**
+ * Learning: every rule is demoted to `audit`, so findings still reach
+ * `violations$` — a host panel and a conformance report see them — and the
+ * canvas says nothing at all. Nobody drawing gets interrupted.
+ *
+ * The DEFAULT, and deliberately so: the sketch wins (PRD principle 3). Somebody
+ * opening a Wardley map for the first time is exploring, not filing a
+ * deliverable, and the tool has no business telling them off for an arrow they
+ * have not finished turning round. Being the default also means it is the one
+ * profile that WRITES NOTHING: a map on `sketch` carries no profile key, so
+ * every map ever drawn is on it, with no migration and no backfill.
+ *
+ * Silencing ALL THREE is the architect's recommendation and is written here for
+ * the PO to confirm or overturn — it is one word per line either way.
+ */
+const sketch = {
+    id: 'wardley.sketch',
+    framework: 'wardley',
+    labelKey: 'com.labre.wardley.profile.sketch',
+    fallback: 'Sketch',
+    isDefault: true,
+    rules: {
+        'wardley.change-arrow-against-evolution': 'audit',
+        'wardley.inertia-off-transition': 'audit',
+        'wardley.overlapping-artefacts': 'audit',
+        // W4 too, and it is the one where the demotion matters most: a value chain
+        // is drawn before it is arranged, so half the links are momentarily
+        // upside-down while somebody thinks. The finding still reaches a host panel
+        // and a conformance report; the canvas says nothing.
+        'wardley.provider-above-consumer': 'audit',
+    },
+};
+/**
+ * Strict: the deliverable level. Every rule bites, and every severity a user
+ * gets is spelled out here rather than left absent — PF9.4 wants the answer
+ * readable in one place, and a profile that says "warning" out loud cannot be
+ * misread as "whatever the rule happens to declare this quarter".
+ *
+ * ## Why W1 and W2 are not `blocking-overridable`
+ *
+ * They should be: pointing a change arrow backwards and parking an inertia bar
+ * in the middle of a phase are both statements that are simply false, and the
+ * architect's recommendation is that strict refuse the gesture and offer the
+ * way out.
+ *
+ * Nothing implements that yet. `blocking-overridable` is carried by the engine
+ * and read by nobody: no gesture is refused anywhere in this library. Declaring
+ * it here would be data claiming an effect that does not exist, and the honest
+ * move is a `warning` plus this paragraph. When the refusal lands, this is a
+ * two-word change and the profile is the only file that moves.
+ *
+ * W3 stays `warning` on its own merits: an overlap is a readability problem,
+ * and refusing a drag because two labels touch would be the tool fighting the
+ * hand.
+ */
+const strict = {
+    id: 'wardley.strict',
+    framework: 'wardley',
+    labelKey: 'com.labre.wardley.profile.strict',
+    fallback: 'Strict',
+    rules: {
+        'wardley.change-arrow-against-evolution': 'warning',
+        'wardley.inertia-off-transition': 'warning',
+        'wardley.overlapping-artefacts': 'warning',
+        // W4 is a `warning` for the same reason W1 and W2 are, plus one of its own:
+        // its two honest resolutions are a MOVE and a REVERSAL, and both are the
+        // user's call. A rule that refused the gesture would be picking one.
+        'wardley.provider-above-consumer': 'warning',
+    },
+};
+export const WARDLEY_PROFILES = [sketch, strict];

package/dist/reading.d.ts

@@ -0,0 +1,3 @@
+import type { ReadingNamingConvention, ReadingProfile } from '@formicoidea/labre-core/blocks/surface';
+export declare const WARDLEY_NAMING_CONVENTIONS: readonly ReadingNamingConvention[];
+export declare const WARDLEY_READING: ReadingProfile;

package/dist/reading.js

@@ -0,0 +1,129 @@
+import { WARDLEY_BACKGROUND } from './background.js';
+import { WARDLEY_NATURE, WARDLEY_NATURE_TAG_ID } from './natures.js';
+import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
+/**
+ * What Wardley lets the tool read of a component (MF3, the reversed reading).
+ *
+ * DATA, like the rules and the profiles beside it: the engine
+ * (`@labre/affine-block-surface`) knows how to read a role, a tag, a typed edge
+ * and a declared background — it knows nothing about Wardley. Everything below
+ * is already stated somewhere else in this framework and is merely POINTED AT
+ * here: the role vocabulary (`roles.ts`), the nature tag (`natures.ts`), the
+ * dependency edge (ADR 0010 § 2 tier 2) and the map's own zones
+ * (`background.ts`).
+ *
+ * Registered from the FLAG-GATED view extension: reading a map is tooling, so a
+ * board whose Wardley flag is off keeps every element it has and simply stops
+ * being read (ADR 0009).
+ */
+/**
+ * ## The naming convention, and why it is one motif rather than a grammar
+ *
+ * Wardley's four natures answer "what KIND of thing is this?", and two of the
+ * four answers are visible in the NAME long before anyone opens a picker: an
+ * activity is something that is DONE, and the other three are things that
+ * ARE — something recorded, a way of doing, something known.
+ *
+ * So the convention retained is exactly one motif — **does the name read as an
+ * action?** — expressed as the English gerund (`…ing`), applied POSITIVELY to
+ * `activity` and NEGATIVELY to the three others:
+ *
+ * | nature    | expected                          | example              |
+ * | --------- | --------------------------------- | -------------------- |
+ * | activity  | reads as an action                | "Brewing tea"        |
+ * | data      | does NOT read as an action        | "Customer register"  |
+ * | practice  | does NOT read as an action        | "Agile method"       |
+ * | knowledge | does NOT read as an action        | "Thermodynamics"     |
+ *
+ * One motif, four entries, no word list. A vocabulary of "practice-ish nouns"
+ * would be a dictionary the library would then own, in one language, and would
+ * be wrong for the first client who names things in their own — whereas the
+ * gerund is a single, checkable shape a user can predict from the sentence they
+ * are shown.
+ *
+ * ## The motif is ENGLISH, and it says so
+ *
+ * `\p{L}+ing` is a fact about English, so every entry below declares
+ * `lang: 'en'` and the engine keeps quiet unless the host says it is serving
+ * English. That is not a detail: on a board named in French the same motif is
+ * wrong in BOTH directions — "Facturation" on an activity would be told to use
+ * a verb, and "Planning", "Sourcing" or "Reporting" on data would be told they
+ * read as actions. An out-of-scope suggestion is worse than none, because it is
+ * confident.
+ *
+ * Extending the coverage is adding entries, not changing code: one more
+ * convention per `valueId` with its own `lang` and its own motif (French, say,
+ * would key on the `-tion`/`-ment` nominalisations against an infinitive), and
+ * the first one in scope wins. A host that declares no language gets silence,
+ * which is the honest answer to "I do not know what language these words are
+ * in".
+ *
+ * It is a SUGGESTION and never a verdict: it produces no violation, blocks no
+ * gesture, and the panel prints the wording below rather than a red mark. A
+ * component named "Tea" whose nature is `activity` is very often correct — the
+ * architect writing shorthand — and the reading's job is to ask, not to insist.
+ *
+ * The wording travels as an i18n key with an English fallback, like every other
+ * declaration in this framework: the host localises it, and a host with no
+ * catalogue still reads a real sentence.
+ */
+const ACTION_MOTIF = String.raw `\b\p{L}+ing\b`;
+const naming = (valueId, expectsAction, key, fallback) => ({
+    valueId,
+    // The gerund is a fact about English: out of that scope the engine says
+    // nothing rather than something confident and wrong.
+    lang: 'en',
+    // The negative form is the same motif under a lookahead, so the two can never
+    // drift apart: change what "reads as an action" means and both sides move.
+    // `[\s\S]` rather than `.` because a canvas label wraps, and a name on two
+    // lines must be judged on what it says, not on where it broke.
+    pattern: expectsAction
+        ? ACTION_MOTIF
+        : `^(?![\\s\\S]*${ACTION_MOTIF})[\\s\\S]+$`,
+    hintKey: key,
+    hintFallback: fallback,
+});
+export const WARDLEY_NAMING_CONVENTIONS = [
+    naming(WARDLEY_NATURE.activity, true, 'com.labre.wardley.reading.naming.activity', 'An activity is something that is done — name it with a verb ("Brewing tea"), not with a thing.'),
+    naming(WARDLEY_NATURE.data, false, 'com.labre.wardley.reading.naming.data', 'Data is something recorded — name it as a thing ("Customer register"), not as an action.'),
+    naming(WARDLEY_NATURE.practice, false, 'com.labre.wardley.reading.naming.practice', 'A practice is a way of doing — name the practice ("Agile method"), not the doing.'),
+    naming(WARDLEY_NATURE.knowledge, false, 'com.labre.wardley.reading.naming.knowledge', 'Knowledge is something known — name what is known ("Thermodynamics"), not an activity.'),
+];
+export const WARDLEY_READING = {
+    id: 'wardley',
+    framework: 'wardley',
+    roles: WARDLEY_ROLES,
+    // The subject is a component. `market` and `ecosystem` specialise it and are
+    // read for free through `roleIsA` — that is the entire reason role hierarchy
+    // is data. The `anchor` (a user / need) is deliberately NOT a child of
+    // `component` and is deliberately not read: a need has no nature and no
+    // phase, it has a demand.
+    appliesTo: WARDLEY_ROLE.component,
+    // On this canvas a name IS a separate free text element grouped with the
+    // node — the same fact W3 measures overlaps against.
+    labelRole: WARDLEY_ROLE.label,
+    nature: {
+        tagId: WARDLEY_NATURE_TAG_ID,
+        conventions: WARDLEY_NAMING_CONVENTIONS,
+    },
+    // The value-chain link. ADR 0010 § 2: `source` is the subject of the role's
+    // verb, and this role's verb is "depends on" — so the source is the consumer
+    // and the target is what it needs.
+    relation: { edgeRole: WARDLEY_ROLE.dependency },
+    frame: {
+        backgroundRole: WARDLEY_ROLE.map,
+        background: WARDLEY_BACKGROUND,
+        // Evolution runs along the plot's x axis; its four zones ARE the phases.
+        axis: 'x',
+    },
+    /**
+     * The two record properties a reading may compare itself against.
+     *
+     * Host keys, and plain ones on purpose: the library does not name a property
+     * of somebody else's document, it states which two it would read IF the host
+     * ships them (and lists them in `hoverFields`). A host whose record spells
+     * them differently gets no comparison and no drift — silence, which is the
+     * correct answer to "I cannot see the record's nature".
+     */
+    recordKeys: { nature: 'nature', phase: 'phase' },
+};

package/dist/roles.d.ts

@@ -0,0 +1,50 @@
+import type { WardleyNodeKind } from '@formicoidea/labre-core/model';
+import type { RoleDefs } from '@formicoidea/labre-core/std/gfx';
+/**
+ * Wardley role vocabulary (PF13.1).
+ *
+ * Roles are the semantic identity of a Wardley artefact — no rule will ever
+ * look at a shape type. They mirror {@link WardleyNodeKind}, which the user
+ * already picks when choosing the artefact in the toolbox, plus the typed
+ * `dependency` EDGE carried by the Wardley link connector.
+ *
+ * Hierarchy is DATA (`parent`), never TS inheritance: `market` and `ecosystem`
+ * specialise `component`, so a rule written on `wardley:component` applies to
+ * them for free (see `roleIsA`). The `anchor` (user / need) is a role of its
+ * own — a component with no need of its own — and is deliberately NOT a child
+ * of `component`.
+ */
+/**
+ * ## Revision of decision #71 (PF13.4, 01/08/2026)
+ *
+ * PF1 left three artefacts NEUTRAL — the evolution arrow ("a movement
+ * annotation, not a dependency"), the inertia bar and the node labels — on the
+ * ground that nothing was written on them yet. That was right while the only
+ * rule was the pilot; it is wrong now that the framework has rules about them:
+ * an element with no role is never evaluated (proportionality, PRD principle
+ * 8), so leaving these neutral would have meant W1, W2 and W3 could not exist.
+ *
+ * The reversal writes new VALUES into the existing `role` field. No schema
+ * change, no migration, and no backfill of documents already drawn: a map
+ * authored before today carries arrows and bars with no role, so it raises
+ * nothing — which is the same promise every earlier role made.
+ */
+/** Every role this framework declares. */
+export type WardleyRole = WardleyNodeKind | 'dependency' | 'map' | 'change-arrow' | 'inertia' | 'label';
+export type WardleyRoleId = `wardley:${WardleyRole}`;
+/** Role ids, keyed by the `kind` used at the creation sites. */
+export declare const WARDLEY_ROLE: {
+    readonly component: "wardley:component";
+    readonly anchor: "wardley:anchor";
+    readonly pipeline: "wardley:pipeline";
+    readonly handle: "wardley:handle";
+    readonly market: "wardley:market";
+    readonly ecosystem: "wardley:ecosystem";
+    readonly method: "wardley:method";
+    readonly dependency: "wardley:dependency";
+    readonly map: "wardley:map";
+    readonly changeArrow: "wardley:change-arrow";
+    readonly inertia: "wardley:inertia";
+    readonly label: "wardley:label";
+};
+export declare const WARDLEY_ROLES: RoleDefs;

package/dist/roles.js

@@ -0,0 +1,132 @@
+/** Role ids, keyed by the `kind` used at the creation sites. */
+export const WARDLEY_ROLE = {
+    component: 'wardley:component',
+    anchor: 'wardley:anchor',
+    pipeline: 'wardley:pipeline',
+    handle: 'wardley:handle',
+    market: 'wardley:market',
+    ecosystem: 'wardley:ecosystem',
+    method: 'wardley:method',
+    dependency: 'wardley:dependency',
+    map: 'wardley:map',
+    changeArrow: 'wardley:change-arrow',
+    inertia: 'wardley:inertia',
+    label: 'wardley:label',
+};
+const DEFS = [
+    {
+        id: WARDLEY_ROLE.component,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.component',
+    },
+    // A user / need: a component with no need of its own, hence its own role
+    // rather than a specialisation of `component`.
+    {
+        id: WARDLEY_ROLE.anchor,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.anchor',
+    },
+    // The pipeline body. Connections go through its handle, never the body.
+    {
+        id: WARDLEY_ROLE.pipeline,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.pipeline',
+    },
+    {
+        id: WARDLEY_ROLE.handle,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.handle',
+    },
+    {
+        id: WARDLEY_ROLE.market,
+        parent: WARDLEY_ROLE.component,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.market',
+    },
+    {
+        id: WARDLEY_ROLE.ecosystem,
+        parent: WARDLEY_ROLE.component,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.ecosystem',
+    },
+    {
+        id: WARDLEY_ROLE.method,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.method',
+    },
+    /**
+     * The value-chain link: "A depends on B".
+     *
+     * The comment above was the whole of the convention until `docs/adr/0010`
+     * made it DATA. Tier 1 of that ADR is generic — `source` is the subject of
+     * the role's verb, `target` its object — and tier 2 is this `direction`
+     * block: the verb of THIS role is "depends on", so its source is the
+     * consumer and its target is what the consumer needs. Needs descend from
+     * source to target; value flows back up. W4 evaluates exactly that reading,
+     * and the tool hint below is what makes it a statement the user made rather
+     * than a by-product of which end their finger landed on first.
+     */
+    {
+        id: WARDLEY_ROLE.dependency,
+        kind: 'edge',
+        labelKey: 'com.labre.wardley.role.dependency',
+        labelFallback: 'Dependency',
+        direction: {
+            verbKey: 'com.labre.wardley.role.dependency.verb',
+            verbFallback: 'depends on',
+            gestureHintKey: 'com.labre.wardley.role.dependency.gesture',
+            gestureHintFallback: 'Drag from the component that has the need to what it needs.',
+        },
+    },
+    // The map itself: the axes frame the other roles are positioned against.
+    // A frame, not a component, so it specialises nothing — a rule written on
+    // `wardley:component` must never match the map it measures against.
+    {
+        id: WARDLEY_ROLE.map,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.map',
+    },
+    // The change (evolution) arrow: "this is where it is going". An EDGE, and
+    // deliberately not a specialisation of `dependency` — it says nothing about
+    // what depends on what, and W1 must not fall on a value-chain link.
+    {
+        id: WARDLEY_ROLE.changeArrow,
+        kind: 'edge',
+        labelKey: 'com.labre.wardley.role.change-arrow',
+        labelFallback: 'Evolution arrow',
+        // Tier 1 applies to every edge role, so this one states its own verb — and
+        // it is NOT "depends on". An arrow says where a component is going: source
+        // is where it stands today, target where it is heading. W4 reads the
+        // dependency's verb and never this one.
+        direction: {
+            verbKey: 'com.labre.wardley.role.change-arrow.verb',
+            verbFallback: 'is evolving towards',
+            gestureHintKey: 'com.labre.wardley.role.change-arrow.gesture',
+            gestureHintFallback: 'Drag from where the component stands today to where it is heading.',
+        },
+    },
+    // The inertia bar: resistance to a movement, drawn ASTRIDE the phase divider
+    // the thing refuses to cross (W2). A plain filled rect on the canvas, which
+    // is exactly why it needs a role — nothing about its shape says what it
+    // means.
+    {
+        id: WARDLEY_ROLE.inertia,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.inertia',
+    },
+    // The name written next to an artefact. A role of its own rather than a
+    // property of the node it labels: on this canvas a label IS a separate free
+    // text element, grouped with its node, and W3 is about where it lands.
+    //
+    // `text`, not `node`: a label is created 120 to 200 units wide whatever it
+    // reads, so its BOX is not a statement about anything the eye can see. The
+    // kind is what tells a rule to measure the words instead.
+    {
+        id: WARDLEY_ROLE.label,
+        kind: 'text',
+        labelKey: 'com.labre.wardley.role.label',
+    },
+];
+// Null prototype: this is a lookup table keyed by ids that may one day come
+// from host-supplied packs, so `defs['toString']` must not resolve.
+export const WARDLEY_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));

package/dist/rules.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+export declare const WARDLEY_RULES: readonly ValidationRule[];