@phuc1403/musketeer 0.9.0 → 0.11.0

package/template/.claude/skills/architecture-characteristic-writer/scripts/ranking-table.cjs

@@ -1,171 +1,171 @@
-#!/usr/bin/env node
-// Scaffolds and repairs the architecture-characteristics ranking table.
-//
-//   scaffold  write a blank ranking holding every catalog characteristic
-//   fix       renumber the Order column and rebuild every "Above X:" prefix
-//             from the row order as it now stands, keeping the justifications
-//
-// Ranking ORDER and justification prose are the architect's work. Everything
-// this script touches — which characteristics appear, the numbering, which row
-// each reason compares against — is mechanical, so no one has to transcribe it.
-//
-// Run `fix` after moving rows. A prefix left naming the wrong row is the usual
-// defect after a reorder, and regenerating them makes it impossible.
-
-const fs = require('fs');
-const path = require('path');
-
-const {
-  loadCatalog,
-  normalise,
-  locateTable,
-  splitCells,
-  isSeparator,
-  RANKING_HEADER,
-} = require('../../../hooks/lib/characteristics/checker.cjs');
-
-const DEFAULT_FILE = 'docs/architecture-characteristics-ranking.md';
-
-// The validation hook resolves the ranking against CLAUDE_PROJECT_DIR. Resolve
-// against the same root, or running this from a subdirectory would quietly
-// write a second ranking somewhere the hook never looks at.
-const projectRoot = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const PLACEHOLDER = '{why}';
-const HEADING = '# Architecture Characteristics Ranking';
-
-const PREAMBLE = [
-  HEADING,
-  '',
-  'All characteristics in priority order. The top 7 feed the worksheet in',
-  '`architecture-characteristics.md`.',
-  '',
-  '<!-- Reason = why this row outranks the row directly BELOW it. Comparative, never a description.',
-  '     Keep the "Above {next characteristic}:" prefix and replace {why} with the justification.',
-  '     Both sides must appear: what this row protects, and what the row below gives up.',
-  '     State WHY the system needs it, meaning the business driver or risk.',
-  '     Never name the mechanism: no patterns, libraries, components, or tactics.',
-  '',
-  '     Move rows freely, then run scripts/ranking-table.cjs fix to renumber and',
-  '     rebuild every prefix. Do not hand-maintain the numbering or the prefixes. -->',
-  '',
-];
-
-const die = (msg) => {
-  process.stderr.write(`${msg}\n`);
-  process.exit(1);
-};
-
-// Builds the three table lines plus data rows for the given ordered names,
-// pairing each row with the justification supplied for it.
-function render(order, justifications) {
-  const rows = order.map((name, i) => {
-    const last = i === order.length - 1;
-    const reason = last ? '—' : `Above ${order[i + 1]}: ${justifications[i] || PLACEHOLDER}`;
-    return `| ${i + 1} | ${name} | ${reason} |`;
-  });
-  return ['| Order | Characteristic | Reason |', '|---|---|---|', ...rows];
-}
-
-// Drops an "Above X:" prefix and a lone em dash, leaving the justification the
-// author actually wrote.
-function justificationOf(reason) {
-  const text = String(reason).trim();
-  if (/^[—-]$/.test(text)) return '';
-  const m = text.match(/^above\s+[^:]+:\s*(.*)$/i);
-  return (m ? m[1] : text).trim();
-}
-
-function scaffold(argv) {
-  const out = argv.out || DEFAULT_FILE;
-  const target = path.resolve(projectRoot(), out);
-
-  if (fs.existsSync(target) && !argv.force) {
-    die(`${out} already exists. Run fix to repair it, or pass --force to start over.`);
-  }
-
-  const { catalog } = loadCatalog(argv.catalog);
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, [...PREAMBLE, ...render(catalog, []), ''].join('\n'), 'utf8');
-
-  process.stdout.write(
-    `Wrote ${out} with ${catalog.length} characteristics in catalog order.\n` +
-      'Reorder the rows, replace every {why}, then run fix.\n'
-  );
-}
-
-function fix(argv) {
-  const file = argv.file || DEFAULT_FILE;
-  const target = path.resolve(projectRoot(), file);
-
-  if (!fs.existsSync(target)) die(`${file} does not exist. Run scaffold first.`);
-
-  const original = fs.readFileSync(target, 'utf8');
-  const eol = original.includes('\r\n') ? '\r\n' : '\n';
-  const lines = original.split(/\r?\n/);
-
-  const bounds = locateTable(lines, RANKING_HEADER);
-  if (!bounds) die(`${file} holds no table with a "| Order | Characteristic | Reason |" header row.`);
-
-  const table = lines.slice(bounds.start, bounds.end);
-  const data = table.filter((l) => {
-    const c = splitCells(l);
-    return c.length >= 3 && !isSeparator(c) && !/^order$/i.test(c[0]);
-  });
-
-  if (!data.length) die(`${file} holds no ranking rows to fix.`);
-
-  const order = data.map((l) => normalise(splitCells(l)[1]));
-  const justifications = data.map((l) => justificationOf(splitCells(l)[2]));
-
-  const { catalog } = loadCatalog(argv.catalog);
-  const unknown = order.filter((n) => !catalog.includes(n));
-  if (unknown.length) die(`${file} names characteristics absent from the catalog: ${unknown.join(', ')}`);
-
-  const rebuilt = render(order, justifications);
-  const next = [...lines.slice(0, bounds.start), ...rebuilt, ...lines.slice(bounds.end)];
-  const updated = next.join(eol);
-
-  // Reported whether or not anything moved: a scaffold is already correct and
-  // still has every justification left to write.
-  const blank = justifications.filter((j, i) => i < justifications.length - 1 && (!j || j === PLACEHOLDER)).length;
-  const outstanding = blank ? `${blank} row(s) still need a justification in place of ${PLACEHOLDER}.\n` : '';
-
-  if (updated === original) {
-    process.stdout.write(`${file} is already correct.\n${outstanding}`);
-    return;
-  }
-
-  fs.writeFileSync(target, updated, 'utf8');
-
-  const repaired = data.filter((l, i) => splitCells(l)[2] !== splitCells(rebuilt[i + 2])[2]).length;
-  const renumbered = data.filter((l, i) => splitCells(l)[0] !== String(i + 1)).length;
-
-  process.stdout.write(
-    `Fixed ${file}: renumbered ${renumbered} row(s), rebuilt ${repaired} reason(s).\n${outstanding}`
-  );
-}
-
-function main() {
-  const [command, ...rest] = process.argv.slice(2);
-  const argv = { force: false };
-
-  for (let i = 0; i < rest.length; i += 1) {
-    const flag = rest[i];
-    if (flag === '--force') argv.force = true;
-    else if (flag === '--out') argv.out = rest[(i += 1)];
-    else if (flag === '--file') argv.file = rest[(i += 1)];
-    else if (flag === '--catalog') argv.catalog = rest[(i += 1)];
-    else die(`unknown argument: ${flag}`);
-  }
-
-  try {
-    if (command === 'scaffold') return scaffold(argv);
-    if (command === 'fix') return fix(argv);
-  } catch (err) {
-    die(err.message);
-  }
-
-  die('usage: ranking-table.cjs scaffold [--out <path>] [--force] | fix [--file <path>]');
-}
-
-main();
+#!/usr/bin/env node
+// Scaffolds and repairs the architecture-characteristics ranking table.
+//
+//   scaffold  write a blank ranking holding every catalog characteristic
+//   fix       renumber the Order column and rebuild every "Above X:" prefix
+//             from the row order as it now stands, keeping the justifications
+//
+// Ranking ORDER and justification prose are the architect's work. Everything
+// this script touches — which characteristics appear, the numbering, which row
+// each reason compares against — is mechanical, so no one has to transcribe it.
+//
+// Run `fix` after moving rows. A prefix left naming the wrong row is the usual
+// defect after a reorder, and regenerating them makes it impossible.
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadCatalog,
+  normalise,
+  locateTable,
+  splitCells,
+  isSeparator,
+  RANKING_HEADER,
+} = require('../../../hooks/lib/characteristics/checker.cjs');
+
+const DEFAULT_FILE = 'docs/architecture-characteristics-ranking.md';
+
+// The validation hook resolves the ranking against CLAUDE_PROJECT_DIR. Resolve
+// against the same root, or running this from a subdirectory would quietly
+// write a second ranking somewhere the hook never looks at.
+const projectRoot = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const PLACEHOLDER = '{why}';
+const HEADING = '# Architecture Characteristics Ranking';
+
+const PREAMBLE = [
+  HEADING,
+  '',
+  'All characteristics in priority order. The top 7 feed the worksheet in',
+  '`architecture-characteristics.md`.',
+  '',
+  '<!-- Reason = why this row outranks the row directly BELOW it. Comparative, never a description.',
+  '     Keep the "Above {next characteristic}:" prefix and replace {why} with the justification.',
+  '     Both sides must appear: what this row protects, and what the row below gives up.',
+  '     State WHY the system needs it, meaning the business driver or risk.',
+  '     Never name the mechanism: no patterns, libraries, components, or tactics.',
+  '',
+  '     Move rows freely, then run scripts/ranking-table.cjs fix to renumber and',
+  '     rebuild every prefix. Do not hand-maintain the numbering or the prefixes. -->',
+  '',
+];
+
+const die = (msg) => {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+};
+
+// Builds the three table lines plus data rows for the given ordered names,
+// pairing each row with the justification supplied for it.
+function render(order, justifications) {
+  const rows = order.map((name, i) => {
+    const last = i === order.length - 1;
+    const reason = last ? '—' : `Above ${order[i + 1]}: ${justifications[i] || PLACEHOLDER}`;
+    return `| ${i + 1} | ${name} | ${reason} |`;
+  });
+  return ['| Order | Characteristic | Reason |', '|---|---|---|', ...rows];
+}
+
+// Drops an "Above X:" prefix and a lone em dash, leaving the justification the
+// author actually wrote.
+function justificationOf(reason) {
+  const text = String(reason).trim();
+  if (/^[—-]$/.test(text)) return '';
+  const m = text.match(/^above\s+[^:]+:\s*(.*)$/i);
+  return (m ? m[1] : text).trim();
+}
+
+function scaffold(argv) {
+  const out = argv.out || DEFAULT_FILE;
+  const target = path.resolve(projectRoot(), out);
+
+  if (fs.existsSync(target) && !argv.force) {
+    die(`${out} already exists. Run fix to repair it, or pass --force to start over.`);
+  }
+
+  const { catalog } = loadCatalog(argv.catalog);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, [...PREAMBLE, ...render(catalog, []), ''].join('\n'), 'utf8');
+
+  process.stdout.write(
+    `Wrote ${out} with ${catalog.length} characteristics in catalog order.\n` +
+      'Reorder the rows, replace every {why}, then run fix.\n'
+  );
+}
+
+function fix(argv) {
+  const file = argv.file || DEFAULT_FILE;
+  const target = path.resolve(projectRoot(), file);
+
+  if (!fs.existsSync(target)) die(`${file} does not exist. Run scaffold first.`);
+
+  const original = fs.readFileSync(target, 'utf8');
+  const eol = original.includes('\r\n') ? '\r\n' : '\n';
+  const lines = original.split(/\r?\n/);
+
+  const bounds = locateTable(lines, RANKING_HEADER);
+  if (!bounds) die(`${file} holds no table with a "| Order | Characteristic | Reason |" header row.`);
+
+  const table = lines.slice(bounds.start, bounds.end);
+  const data = table.filter((l) => {
+    const c = splitCells(l);
+    return c.length >= 3 && !isSeparator(c) && !/^order$/i.test(c[0]);
+  });
+
+  if (!data.length) die(`${file} holds no ranking rows to fix.`);
+
+  const order = data.map((l) => normalise(splitCells(l)[1]));
+  const justifications = data.map((l) => justificationOf(splitCells(l)[2]));
+
+  const { catalog } = loadCatalog(argv.catalog);
+  const unknown = order.filter((n) => !catalog.includes(n));
+  if (unknown.length) die(`${file} names characteristics absent from the catalog: ${unknown.join(', ')}`);
+
+  const rebuilt = render(order, justifications);
+  const next = [...lines.slice(0, bounds.start), ...rebuilt, ...lines.slice(bounds.end)];
+  const updated = next.join(eol);
+
+  // Reported whether or not anything moved: a scaffold is already correct and
+  // still has every justification left to write.
+  const blank = justifications.filter((j, i) => i < justifications.length - 1 && (!j || j === PLACEHOLDER)).length;
+  const outstanding = blank ? `${blank} row(s) still need a justification in place of ${PLACEHOLDER}.\n` : '';
+
+  if (updated === original) {
+    process.stdout.write(`${file} is already correct.\n${outstanding}`);
+    return;
+  }
+
+  fs.writeFileSync(target, updated, 'utf8');
+
+  const repaired = data.filter((l, i) => splitCells(l)[2] !== splitCells(rebuilt[i + 2])[2]).length;
+  const renumbered = data.filter((l, i) => splitCells(l)[0] !== String(i + 1)).length;
+
+  process.stdout.write(
+    `Fixed ${file}: renumbered ${renumbered} row(s), rebuilt ${repaired} reason(s).\n${outstanding}`
+  );
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const argv = { force: false };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i];
+    if (flag === '--force') argv.force = true;
+    else if (flag === '--out') argv.out = rest[(i += 1)];
+    else if (flag === '--file') argv.file = rest[(i += 1)];
+    else if (flag === '--catalog') argv.catalog = rest[(i += 1)];
+    else die(`unknown argument: ${flag}`);
+  }
+
+  try {
+    if (command === 'scaffold') return scaffold(argv);
+    if (command === 'fix') return fix(argv);
+  } catch (err) {
+    die(err.message);
+  }
+
+  die('usage: ranking-table.cjs scaffold [--out <path>] [--force] | fix [--file <path>]');
+}
+
+main();

package/template/.claude/skills/context-map/SKILL.md

@@ -1,80 +1,80 @@
----
-name: context-map
-description: Write or update a DDD Context Map in CML (Context Mapper Language).
----
-
-<what-to-do>
-
-Given a Context Map intent, produce or update the single `docs/bounded-contexts/context-map.cml` (one map per system, spanning every BC). The four intent shapes (use these exact labels):
-
-- **`BC`** — name, optional `type` / `domainVisionStatement` / `responsibilities`. Adds it to `contains` and appends a `BoundedContext <Name>` declaration.
-- **`peer-context`** — same shape as `BC`, named after an external system. Used for every `external_system` declared on the EventStorming wall.
-- **`relationship`** — upstream BC, downstream BC, shape (Partnership / Shared-Kernel / Upstream-Downstream / Customer-Supplier), role brackets, optional name, optional `{ implementationTechnology, downstreamRights, exposedAggregates }` attributes.
-- **`Aggregate`** — name + owning BC. Adds `Aggregate <Name>` inside the BC's `{ … }` body, creating the body if it was empty. Required when the name appears in any relationship's `exposedAggregates`. Maintain 1:1 sync with the wall JSON: every entry in `aggregates[]` on the BC's `docs/bounded-contexts/{bc}/event-storming.json` (or the general `docs/event-storming.json` before segregation) has a matching `Aggregate <Name>` inside its owning BC, written the same turn.
-
-Workflow:
-
-1. **Locate or scaffold the file.** If it doesn't exist, scaffold a minimal `ContextMap SystemContextMap { type = SYSTEM_LANDSCAPE state = AS_IS contains <BCs> }` block followed by one `BoundedContext <Name>` declaration per BC in `contains`. Use [example.cml](./example.cml) as a **syntax reference**, not a literal copy — its DDDSample BCs are illustrative.
-2. **Write the requested change.** Per intent shape: add the `contains` entry + `BoundedContext` declaration (`BC` / `peer-context`); add the relationship line (`relationship`); add `Aggregate <Name>` inside the owning BC's body (`Aggregate`). For every BC newly referenced anywhere, append a `BoundedContext <Name>` declaration — without it Xtext linker fails with `Couldn't resolve reference to BoundedContext '<Name>'`.
-3. **Lint.** A PostToolUse hook auto-runs Context Mapper validation on every `.cml` edit. Treat any `ERROR …` line in its output as blocking; `WARNING …` lines (e.g. ACL on Customer-Supplier per Semantic Rule #7) are allowed when intentional.
-4. **Hand-audit.** `cm validate` is necessary but not sufficient — see Limitations below. Audit three things by hand before reporting success: (i) every `exposedAggregates` name lives in the upstream BC of its relationship; (ii) every role bracket combo respects the 10 Semantic Rules; (iii) no Aggregate name is duplicated across BCs unless deliberate.
-5. **Report.** State the line(s) written and PASS/FAIL of `cm validate` (on FAIL, paste only the first `ERROR` line and where to fix). Call out anything the hand-audit flagged.
-
-If a piece of the intent is ambiguous (e.g. which side is upstream, which roles to use), ask the caller — don't invent. The skill's job is mechanical correctness, not design judgement.
-
-</what-to-do>
-
-<supporting-info>
-
-## File location
-
-`docs/bounded-contexts/context-map.cml` — a single map for the whole system, sitting beside the per-BC folders.
-
-## Reference (load lazily by intent shape)
-
-The reference is an Obsidian folder with `[[wikilinks]]` between files. Load in tiers — don't front-load everything:
-
-- **Always** (first invocation this session):
-  - `./reference/Context Map.md` — top-level grammar, relationship arrows, role brackets, attributes.
-  - `./reference/Semantic Rules.md` — the 10 combination rules.
-- **When writing a `BC` or `peer-context`** with non-trivial attributes:
-  - `./reference/Bounded Context/Bounded Context.md` — attribute docs (`implements`, `refines`, `domainVisionStatement`, `responsibilities`, `type`, `knowledgeLevel`, `businessModel`, `evolution`, `realizes`).
-- **When writing a `relationship`**:
-  - `./reference/Bounded Context Relationship/Bounded Context Relationship.md` — per-pattern pages (Partnership, Shared Kernel, Customer-Supplier, OHS, PL, CF, ACL).
-- **When writing an `Aggregate` or setting `exposedAggregates`**:
-  - `./reference/Aggregate/Aggregate.md` — Aggregate composition.
-- **When a BC uses `implements` / `refines`**:
-  - `./reference/Domain/Domain.md` — Domain / Subdomain framing.
-
-## Linting (mandatory before reporting success)
-
-Validation runs automatically via the PostToolUse `validate-cml-hook` on every `.cml` edit (Context Mapper CLI, self-bootstrapped from Maven on first run; requires Java 8+).
-
-**CML-specific failure modes to recognise:**
-
-- `Couldn't resolve reference to BoundedContext '<Name>'` + `The Bounded Context 'null' is not part of the Context Map.` — a name in `contains` or a relationship line has no `BoundedContext <Name>` declaration. Fix: append the missing declaration.
-- `ERROR in null on line N: no viable alternative at input '<token>'` — parse error. Re-read the grammar at the reported line.
-
-## Limitations of `cm validate` — hand-audit is required after it passes
-
-Confirmed-misses (tested against 6.12.0):
-
-| Catches                                                   | Misses                                                                                                                                                                       |
-| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Parse errors with line numbers                            | Semantic Rule violations from `Semantic Rules.md` (OHS on Customer-Supplier #6, CF on Customer-Supplier #5, ACL/CF/OHS/PL on symmetric relationships #4, etc.)               |
-| Linker errors when they fire                              | Duplicate Aggregate names across different BCs (CML scopes `exposedAggregates` by upstream BC, so duplicates resolve rather than collide — but they're semantically muddled) |
-| Resource-level diagnostics from `cmlResource.getErrors()` | Anything that needs the full Xtext `IResourceValidator` chain (Eclipse/VSCode extension surfaces these; the CLI does not)                                                    |
-
-After `cm validate` prints "without errors", audit by hand:
-
-1. Every `exposedAggregates` name resolves to an Aggregate declared inside the **upstream** BC of that relationship line.
-2. Every role bracket combo is allowed by the 10 Semantic Rules (consult `./reference/Semantic Rules.md`).
-3. No Aggregate name is duplicated across BCs unless deliberate.
-
-For deeper validation, open the file in VSCode with the Context Mapper extension installed.
-
-## Glossary
-
-Same `ubiquitous-language.md` convention as the EventStorming skills. Challenge BC names against the language doc before writing. If a relationship introduces a novel domain term, add a one-sentence definition in `docs/ubiquitous-language.md` the same turn.
-
-</supporting-info>
+---
+name: context-map
+description: Write or update a DDD Context Map in CML (Context Mapper Language).
+---
+
+<what-to-do>
+
+Given a Context Map intent, produce or update the single `docs/bounded-contexts/context-map.cml` (one map per system, spanning every BC). The four intent shapes (use these exact labels):
+
+- **`BC`** — name, optional `type` / `domainVisionStatement` / `responsibilities`. Adds it to `contains` and appends a `BoundedContext <Name>` declaration.
+- **`peer-context`** — same shape as `BC`, named after an external system. Used for every `external_system` declared on the EventStorming wall.
+- **`relationship`** — upstream BC, downstream BC, shape (Partnership / Shared-Kernel / Upstream-Downstream / Customer-Supplier), role brackets, optional name, optional `{ implementationTechnology, downstreamRights, exposedAggregates }` attributes.
+- **`Aggregate`** — name + owning BC. Adds `Aggregate <Name>` inside the BC's `{ … }` body, creating the body if it was empty. Required when the name appears in any relationship's `exposedAggregates`. Maintain 1:1 sync with the wall JSON: every entry in `aggregates[]` on the BC's `docs/bounded-contexts/{bc}/event-storming.json` (or the general `docs/event-storming.json` before segregation) has a matching `Aggregate <Name>` inside its owning BC, written the same turn.
+
+Workflow:
+
+1. **Locate or scaffold the file.** If it doesn't exist, scaffold a minimal `ContextMap SystemContextMap { type = SYSTEM_LANDSCAPE state = AS_IS contains <BCs> }` block followed by one `BoundedContext <Name>` declaration per BC in `contains`. Use [example.cml](./example.cml) as a **syntax reference**, not a literal copy — its DDDSample BCs are illustrative.
+2. **Write the requested change.** Per intent shape: add the `contains` entry + `BoundedContext` declaration (`BC` / `peer-context`); add the relationship line (`relationship`); add `Aggregate <Name>` inside the owning BC's body (`Aggregate`). For every BC newly referenced anywhere, append a `BoundedContext <Name>` declaration — without it Xtext linker fails with `Couldn't resolve reference to BoundedContext '<Name>'`.
+3. **Lint.** A PostToolUse hook auto-runs Context Mapper validation on every `.cml` edit. Treat any `ERROR …` line in its output as blocking; `WARNING …` lines (e.g. ACL on Customer-Supplier per Semantic Rule #7) are allowed when intentional.
+4. **Hand-audit.** `cm validate` is necessary but not sufficient — see Limitations below. Audit three things by hand before reporting success: (i) every `exposedAggregates` name lives in the upstream BC of its relationship; (ii) every role bracket combo respects the 10 Semantic Rules; (iii) no Aggregate name is duplicated across BCs unless deliberate.
+5. **Report.** State the line(s) written and PASS/FAIL of `cm validate` (on FAIL, paste only the first `ERROR` line and where to fix). Call out anything the hand-audit flagged.
+
+If a piece of the intent is ambiguous (e.g. which side is upstream, which roles to use), ask the caller — don't invent. The skill's job is mechanical correctness, not design judgement.
+
+</what-to-do>
+
+<supporting-info>
+
+## File location
+
+`docs/bounded-contexts/context-map.cml` — a single map for the whole system, sitting beside the per-BC folders.
+
+## Reference (load lazily by intent shape)
+
+The reference is an Obsidian folder with `[[wikilinks]]` between files. Load in tiers — don't front-load everything:
+
+- **Always** (first invocation this session):
+  - `./reference/Context Map.md` — top-level grammar, relationship arrows, role brackets, attributes.
+  - `./reference/Semantic Rules.md` — the 10 combination rules.
+- **When writing a `BC` or `peer-context`** with non-trivial attributes:
+  - `./reference/Bounded Context/Bounded Context.md` — attribute docs (`implements`, `refines`, `domainVisionStatement`, `responsibilities`, `type`, `knowledgeLevel`, `businessModel`, `evolution`, `realizes`).
+- **When writing a `relationship`**:
+  - `./reference/Bounded Context Relationship/Bounded Context Relationship.md` — per-pattern pages (Partnership, Shared Kernel, Customer-Supplier, OHS, PL, CF, ACL).
+- **When writing an `Aggregate` or setting `exposedAggregates`**:
+  - `./reference/Aggregate/Aggregate.md` — Aggregate composition.
+- **When a BC uses `implements` / `refines`**:
+  - `./reference/Domain/Domain.md` — Domain / Subdomain framing.
+
+## Linting (mandatory before reporting success)
+
+Validation runs automatically via the PostToolUse `validate-cml-hook` on every `.cml` edit (Context Mapper CLI, self-bootstrapped from Maven on first run; requires Java 8+).
+
+**CML-specific failure modes to recognise:**
+
+- `Couldn't resolve reference to BoundedContext '<Name>'` + `The Bounded Context 'null' is not part of the Context Map.` — a name in `contains` or a relationship line has no `BoundedContext <Name>` declaration. Fix: append the missing declaration.
+- `ERROR in null on line N: no viable alternative at input '<token>'` — parse error. Re-read the grammar at the reported line.
+
+## Limitations of `cm validate` — hand-audit is required after it passes
+
+Confirmed-misses (tested against 6.12.0):
+
+| Catches                                                   | Misses                                                                                                                                                                       |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Parse errors with line numbers                            | Semantic Rule violations from `Semantic Rules.md` (OHS on Customer-Supplier #6, CF on Customer-Supplier #5, ACL/CF/OHS/PL on symmetric relationships #4, etc.)               |
+| Linker errors when they fire                              | Duplicate Aggregate names across different BCs (CML scopes `exposedAggregates` by upstream BC, so duplicates resolve rather than collide — but they're semantically muddled) |
+| Resource-level diagnostics from `cmlResource.getErrors()` | Anything that needs the full Xtext `IResourceValidator` chain (Eclipse/VSCode extension surfaces these; the CLI does not)                                                    |
+
+After `cm validate` prints "without errors", audit by hand:
+
+1. Every `exposedAggregates` name resolves to an Aggregate declared inside the **upstream** BC of that relationship line.
+2. Every role bracket combo is allowed by the 10 Semantic Rules (consult `./reference/Semantic Rules.md`).
+3. No Aggregate name is duplicated across BCs unless deliberate.
+
+For deeper validation, open the file in VSCode with the Context Mapper extension installed.
+
+## Glossary
+
+Same `ubiquitous-language.md` convention as the EventStorming skills. Challenge BC names against the language doc before writing. If a relationship introduces a novel domain term, add a one-sentence definition in `docs/ubiquitous-language.md` the same turn.
+
+</supporting-info>