markitect-main/docs/composition-guide.md

Infospace Composition Guide

One completed, viable infospace can be reused as a discipline for another infospace — a lens applied to a different topic. This guide explains how composition works and walks through the live examples/supply-chain-vsm/ reference.

---

What composition means

An infospace is a directory of typed entities governed by infospace.yaml. Its entities and relations describe a specific topic (for example, Adam Smith's Wealth of Nations).

A discipline is an infospace declared as a reusable analytical framework by another infospace. When infospace B binds infospace A as a discipline:

1. B's entities can reference A's entities in ## WoN Concept (or equivalent) sections.
2. Properties A has already computed on its entities — such as VSM system placement — become available to B by transitivity through the mapping.
3. B can impose its own viability thresholds independently of A's. The two infospaces each pass or fail viability on their own terms.

The binding is declarative: a relative path in infospace.yaml plus a display name. No code. No import. The discipline is looked up on disk at the declared path when B's commands run.

---

The viability pre-condition

Binding a non-viable infospace as a discipline is a mistake: a framework that fails its own thresholds is not a stable reference frame. Before binding, confirm the candidate discipline is viable:

cd examples/infospace-with-history
markitect infospace viability

Metric                            Value       Threshold   Status
---------------------------------------------------------------
redundancy_ratio                 0.0061         max=0.1     PASS
coverage_ratio                   0.6190         min=0.4     PASS
coherence_components             0.0000           max=3     PASS
consistency_cycles               0.0000           max=0     PASS
granularity_entropy              2.6748         min=1.0     PASS
per_entity_mean                  3.9556         min=3.5     PASS

Viable: YES (6/6 thresholds met)

If the discipline is not viable, fix it first (see examples/infospace-with-history/docs/advanced-usage.md §4 for triaging low scorers).

---

Example — how supply-chain-vsm binds WoN

The supply-chain infospace declares WoN as a discipline in its infospace.yaml:

topic:
  name: "Modern Supply Chain Management"
  domain: "Operations Management"
  sources: artifacts/sources/

disciplines:
  - name: "Wealth of Nations"
    path: ../infospace-with-history

The binding is a relative path, so the two infospaces travel together (they can be moved as a pair without breaking the link).

Verify the binding resolves and the discipline is viable:

cd examples/supply-chain-vsm
markitect infospace disciplines

Name                           Entities   Viable Path
----------------------------------------------------------------------
Wealth of Nations                   988      YES ../infospace-with-history

Each supply-chain entity then carries a ## WoN Concept section mapping it to exactly one WoN entity. The consolidated mapping files (output/mappings/*-mappings.md) record the pairing, rationale, and a conceptual-continuity rating (Strong / Moderate / Weak):

Supply Chain Entity	WoN Concept	Strength	VSM
Demand Signal	Effectual Demand	Strong	S2
Vendor-Managed Inventory	Division of Labour	Strong	S1/S2
Just-in-Time Inventory	Circulating Capital	Strong	S1/S3
Bullwhip Effect	Natural Price as Central Price	Moderate	S2
Safety Stock	Accumulation of Stock	Moderate	S3

Because each WoN entity already has a VSM system placement (S1–S5), the supply-chain entities inherit a VSM position by transitivity through their mapping — without supply-chain-vsm needing its own VSM reference.

---

Creating a new infospace that binds an existing one

Step-by-step, using WoN as the discipline for a hypothetical "Modern Monetary Policy" infospace:

1. Start from the target topic

mkdir -p examples/monetary-policy/artifacts/sources
cd examples/monetary-policy
markitect infospace init

2. Declare the discipline in infospace.yaml

topic:
  name: "Modern Monetary Policy"
  domain: "Macroeconomics"
  sources: artifacts/sources/

disciplines:
  - name: "Wealth of Nations"
    path: ../infospace-with-history

Alternatively, bind imperatively after init:

markitect infospace bind-discipline ../infospace-with-history --name "Wealth of Nations"

3. Set your own viability thresholds

Copy the viability: block from a reference infospace and tune the numbers to the scale and maturity of your topic. A smaller infospace (50 entities, not 988) may need laxer coverage_ratio and stricter redundancy_ratio.

4. Verify the binding

markitect infospace disciplines

If Viable is NO, stop and fix the discipline before continuing.

5. Reference discipline entities in your own entities

For each entity in the new infospace, add a ## <Discipline> Concept section that names the WoN entity the concept maps to, plus a rationale. The exact section heading is configured per schema — see schemas/won-mapping-schema-v1.0.md in supply-chain-vsm for the template used there.

6. Run checks and evaluate

markitect infospace check
markitect infospace evaluate --provider openrouter
markitect infospace eval-summary --update-metrics
markitect infospace viability

The new infospace passes or fails viability independently of WoN.

---

Why composition, not inclusion?

An alternative would be to copy WoN entities directly into the target infospace. Composition avoids that by design:

• One source of truth — if WoN is refined, every infospace that binds it picks up the improvement on the next run without a sync step.
• Separation of concerns — each infospace owns its own schema, thresholds, and entity set. Changing the target topic cannot pollute the discipline.
• Bounded dependency — the binding is a path, so the coupling is visible in one place (infospace.yaml) and easy to remove.

---

See also

• examples/supply-chain-vsm/README.md — the full reference composition.
• examples/supply-chain-vsm/output/mappings/ — consolidated mapping files showing the rationale and strength rating for each pairing.
• examples/infospace-with-history/docs/advanced-usage.md — patterns for maintaining the discipline once it is in use.