yarramate 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,10 @@
 # YarraMate
 
+[![npm](https://img.shields.io/npm/v/yarramate)](https://www.npmjs.com/package/yarramate)
+[![CI](https://github.com/yarrasys/yarramate/actions/workflows/ci.yml/badge.svg)](https://github.com/yarrasys/yarramate/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/yarrasys/yarramate/actions/workflows/codeql.yml/badge.svg)](https://github.com/yarrasys/yarramate/actions/workflows/codeql.yml)
+[![license: MIT](https://img.shields.io/github/license/yarrasys/yarramate)](LICENSE)
+
 YarraMate is a tool-neutral semantic architecture engine and guided
 methodology. It turns architectural intent into deterministic, testable
 context shared by people and agents.
@@ -94,8 +99,16 @@ pnpm docs:dev
 
 ## CLI
 
-Build the repository, then invoke the same executable surface intended for
-published use:
+Install the published executable or invoke it directly with `npx`:
+
+```sh
+npm install --global yarramate
+yarramate --help
+
+npx yarramate check .yarramate/workspace.yaml
+```
+
+When developing the repository, build and invoke the same executable surface:
 
 ```sh
 pnpm build
@@ -117,7 +130,7 @@ For a local consumer test, create a package artifact:
 
 ```sh
 pnpm pack --pack-destination /tmp/yarramate-package
-npm install --global /tmp/yarramate-package/yarramate-0.1.0.tgz
+npm install --global /tmp/yarramate-package/yarramate-*.tgz
 yarramate --help
 ```
 
@@ -169,6 +182,8 @@ You do not need to provide a solution, formal proposal, or implementation.
 
 Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes to native
 semantics or stable interfaces. Report suspected vulnerabilities according to
-[SECURITY.md](SECURITY.md).
+[SECURITY.md](SECURITY.md). Participation is governed by the
+[Code of Conduct](CODE_OF_CONDUCT.md), and help channels are described in
+[SUPPORT.md](SUPPORT.md).
 
 YarraMate is available under the [MIT License](LICENSE).

package/assets/likec4/specification.likec4

@@ -0,0 +1,500 @@
+// YarraMate semantic profile for LikeC4.
+//
+// This vocabulary is ArchiMate-inspired but independently expressed. The tags
+// encode semantic coordinates; element kinds carry the human-facing notation.
+specification {
+  color motivationColor #E8D7F1
+  color strategyColor #F3E5AB
+  color businessColor #FFF1B8
+  color applicationColor #C9E7FF
+  color technologyColor #D8F0D2
+  color physicalColor #D5E8D4
+  color implementationColor #F5D5CB
+  color compositeColor #E6E6E6
+  color relationColor #5B6470
+
+  tag layerMotivation
+  tag layerStrategy
+  tag layerBusiness
+  tag layerApplication
+  tag layerTechnology
+  tag layerPhysical
+  tag layerImplementation
+  tag layerComposite
+
+  tag aspectActive
+  tag aspectBehavior
+  tag aspectPassive
+
+  // Adapter-owned deployment presentation kinds.
+  deploymentNode environment {
+    notation 'Environment'
+    style { color technologyColor }
+  }
+
+  deploymentNode zone {
+    notation 'Zone'
+    style { color compositeColor }
+  }
+
+  deploymentNode host {
+    notation 'Host'
+    style { color technologyColor }
+  }
+
+  deploymentNode runtime {
+    notation 'Runtime'
+    style { color applicationColor }
+  }
+
+  // ── Motivation ────────────────────────────────────────────────────────────
+
+  element stakeholder {
+    #layerMotivation
+    notation 'Stakeholder'
+    style { shape person; color motivationColor }
+  }
+
+  element driver {
+    #layerMotivation
+    notation 'Driver'
+    style { color motivationColor }
+  }
+
+  element assessment {
+    #layerMotivation
+    notation 'Assessment'
+    style { color motivationColor }
+  }
+
+  element goal {
+    #layerMotivation
+    notation 'Goal'
+    style { color motivationColor }
+  }
+
+  element outcome {
+    #layerMotivation
+    notation 'Outcome'
+    style { color motivationColor }
+  }
+
+  element principle {
+    #layerMotivation
+    notation 'Principle'
+    style { color motivationColor }
+  }
+
+  element requirement {
+    #layerMotivation
+    notation 'Requirement'
+    style { color motivationColor }
+  }
+
+  element constraint {
+    #layerMotivation
+    notation 'Constraint'
+    style { color motivationColor }
+  }
+
+  element meaning {
+    #layerMotivation
+    notation 'Meaning'
+    style { color motivationColor }
+  }
+
+  element value {
+    #layerMotivation
+    notation 'Value'
+    style { color motivationColor }
+  }
+
+  // ── Strategy ──────────────────────────────────────────────────────────────
+
+  element resource {
+    #layerStrategy #aspectActive
+    notation 'Resource'
+    style { color strategyColor }
+  }
+
+  element capability {
+    #layerStrategy #aspectBehavior
+    notation 'Capability'
+    style { color strategyColor }
+  }
+
+  element valueStream {
+    #layerStrategy #aspectBehavior
+    notation 'Value stream'
+    style { color strategyColor }
+  }
+
+  element courseOfAction {
+    #layerStrategy #aspectBehavior
+    notation 'Course of action'
+    style { color strategyColor }
+  }
+
+  // ── Business layer ────────────────────────────────────────────────────────
+
+  element businessActor {
+    #layerBusiness #aspectActive
+    notation 'Business actor'
+    style { shape person; color businessColor }
+  }
+
+  element businessRole {
+    #layerBusiness #aspectActive
+    notation 'Business role'
+    style { color businessColor }
+  }
+
+  element businessCollaboration {
+    #layerBusiness #aspectActive
+    notation 'Business collaboration'
+    style { color businessColor; multiple true }
+  }
+
+  element businessInterface {
+    #layerBusiness #aspectActive
+    notation 'Business interface'
+    style { color businessColor }
+  }
+
+  element businessProcess {
+    #layerBusiness #aspectBehavior
+    notation 'Business process'
+    style { color businessColor }
+  }
+
+  element businessFunction {
+    #layerBusiness #aspectBehavior
+    notation 'Business function'
+    style { color businessColor }
+  }
+
+  element businessInteraction {
+    #layerBusiness #aspectBehavior
+    notation 'Business interaction'
+    style { color businessColor }
+  }
+
+  element businessEvent {
+    #layerBusiness #aspectBehavior
+    notation 'Business event'
+    style { color businessColor }
+  }
+
+  element businessService {
+    #layerBusiness #aspectBehavior
+    notation 'Business service'
+    style { color businessColor }
+  }
+
+  element businessObject {
+    #layerBusiness #aspectPassive
+    notation 'Business object'
+    style { color businessColor }
+  }
+
+  element contract {
+    #layerBusiness #aspectPassive
+    notation 'Contract'
+    style { color businessColor }
+  }
+
+  element representation {
+    #layerBusiness #aspectPassive
+    notation 'Representation'
+    style { color businessColor }
+  }
+
+  element product {
+    #layerBusiness #aspectPassive
+    notation 'Product'
+    style { color businessColor }
+  }
+
+  // ── Application layer ─────────────────────────────────────────────────────
+
+  element applicationComponent {
+    #layerApplication #aspectActive
+    notation 'Application component'
+    style { shape component; color applicationColor }
+  }
+
+  element applicationCollaboration {
+    #layerApplication #aspectActive
+    notation 'Application collaboration'
+    style { color applicationColor; multiple true }
+  }
+
+  element applicationInterface {
+    #layerApplication #aspectActive
+    notation 'Application interface'
+    style { color applicationColor }
+  }
+
+  element applicationFunction {
+    #layerApplication #aspectBehavior
+    notation 'Application function'
+    style { color applicationColor }
+  }
+
+  element applicationInteraction {
+    #layerApplication #aspectBehavior
+    notation 'Application interaction'
+    style { color applicationColor }
+  }
+
+  element applicationProcess {
+    #layerApplication #aspectBehavior
+    notation 'Application process'
+    style { color applicationColor }
+  }
+
+  element applicationEvent {
+    #layerApplication #aspectBehavior
+    notation 'Application event'
+    style { color applicationColor }
+  }
+
+  element applicationService {
+    #layerApplication #aspectBehavior
+    notation 'Application service'
+    style { color applicationColor }
+  }
+
+  element dataObject {
+    #layerApplication #aspectPassive
+    notation 'Data object'
+    style { shape storage; color applicationColor }
+  }
+
+  // ── Technology layer ──────────────────────────────────────────────────────
+
+  element node {
+    #layerTechnology #aspectActive
+    notation 'Node'
+    style { color technologyColor }
+  }
+
+  element device {
+    #layerTechnology #aspectActive
+    notation 'Device'
+    style { color technologyColor }
+  }
+
+  element systemSoftware {
+    #layerTechnology #aspectActive
+    notation 'System software'
+    style { color technologyColor }
+  }
+
+  element technologyCollaboration {
+    #layerTechnology #aspectActive
+    notation 'Technology collaboration'
+    style { color technologyColor; multiple true }
+  }
+
+  element technologyInterface {
+    #layerTechnology #aspectActive
+    notation 'Technology interface'
+    style { color technologyColor }
+  }
+
+  element path {
+    #layerTechnology #aspectActive
+    notation 'Path'
+    style { color technologyColor }
+  }
+
+  element communicationNetwork {
+    #layerTechnology #aspectActive
+    notation 'Communication network'
+    style { color technologyColor }
+  }
+
+  element technologyFunction {
+    #layerTechnology #aspectBehavior
+    notation 'Technology function'
+    style { color technologyColor }
+  }
+
+  element technologyProcess {
+    #layerTechnology #aspectBehavior
+    notation 'Technology process'
+    style { color technologyColor }
+  }
+
+  element technologyInteraction {
+    #layerTechnology #aspectBehavior
+    notation 'Technology interaction'
+    style { color technologyColor }
+  }
+
+  element technologyEvent {
+    #layerTechnology #aspectBehavior
+    notation 'Technology event'
+    style { color technologyColor }
+  }
+
+  element technologyService {
+    #layerTechnology #aspectBehavior
+    notation 'Technology service'
+    style { color technologyColor }
+  }
+
+  element artifact {
+    #layerTechnology #aspectPassive
+    notation 'Artifact'
+    style { color technologyColor }
+  }
+
+  // ── Physical layer ────────────────────────────────────────────────────────
+
+  element equipment {
+    #layerPhysical #aspectActive
+    notation 'Equipment'
+    style { color physicalColor }
+  }
+
+  element facility {
+    #layerPhysical #aspectActive
+    notation 'Facility'
+    style { color physicalColor }
+  }
+
+  element distributionNetwork {
+    #layerPhysical #aspectActive
+    notation 'Distribution network'
+    style { color physicalColor }
+  }
+
+  element material {
+    #layerPhysical #aspectPassive
+    notation 'Material'
+    style { color physicalColor }
+  }
+
+  // ── Implementation and migration ─────────────────────────────────────────
+
+  element workPackage {
+    #layerImplementation #aspectBehavior
+    notation 'Work package'
+    style { color implementationColor }
+  }
+
+  element deliverable {
+    #layerImplementation #aspectPassive
+    notation 'Deliverable'
+    style { color implementationColor }
+  }
+
+  element implementationEvent {
+    #layerImplementation #aspectBehavior
+    notation 'Implementation event'
+    style { color implementationColor }
+  }
+
+  element plateau {
+    #layerImplementation
+    notation 'Plateau'
+    style { color implementationColor }
+  }
+
+  element gap {
+    #layerImplementation
+    notation 'Gap'
+    style { color implementationColor }
+  }
+
+  // ── Composite and relationship connectors ────────────────────────────────
+
+  element grouping {
+    #layerComposite
+    notation 'Grouping'
+    style { color compositeColor; border dashed }
+  }
+
+  element location {
+    #layerComposite
+    notation 'Location'
+    style { color compositeColor }
+  }
+
+  element andJunction {
+    #layerComposite
+    notation 'AND junction'
+    style { color compositeColor }
+  }
+
+  element orJunction {
+    #layerComposite
+    notation 'OR junction'
+    style { color compositeColor }
+  }
+
+  // ── Relationships ─────────────────────────────────────────────────────────
+
+  relationship composition {
+    description 'Strong whole-part relationship.'
+    color relationColor
+  }
+
+  relationship aggregation {
+    description 'Weak whole-part relationship.'
+    color relationColor
+    line dashed
+  }
+
+  relationship assignment {
+    description 'Allocation of responsibility, execution, or use.'
+    color relationColor
+  }
+
+  relationship realization {
+    description 'Implementation or fulfillment of a more abstract concept.'
+    color relationColor
+    line dashed
+  }
+
+  relationship serving {
+    description 'Functionality made available to another concept.'
+    color relationColor
+  }
+
+  relationship access {
+    description 'Use, creation, modification, or reading of passive structure.'
+    color relationColor
+    line dashed
+  }
+
+  relationship influence {
+    description 'Effect on a motivation concept.'
+    color relationColor
+    line dotted
+  }
+
+  relationship association {
+    description 'Semantically relevant connection not expressed more specifically.'
+    color relationColor
+    line dashed
+  }
+
+  relationship triggering {
+    description 'Temporal or causal precedence between behaviors or events.'
+    color relationColor
+  }
+
+  relationship flow {
+    description 'Transfer of information, value, goods, or another object.'
+    color relationColor
+    line dashed
+  }
+
+  relationship specialization {
+    description 'Concept is a more specific form of another concept.'
+    color relationColor
+  }
+}

package/dist/adapters/likec4-cli.js

@@ -151,7 +151,7 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
     else {
         mkdirSync(projectPath, { recursive: true });
     }
-    const specificationSource = readFileSync(fileURLToPath(new URL('../../.yarramate/integrations/likec4/prototype/specification.likec4', import.meta.url)));
+    const specificationSource = readFileSync(fileURLToPath(new URL('../../assets/likec4/specification.likec4', import.meta.url)));
     const configSource = `${JSON.stringify({
         $schema: 'https://likec4.dev/schemas/config.json',
         name: input.projectName,

package/dist/adapters/likec4-export.js

@@ -133,6 +133,10 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
                 'constraints',
                 referencesFor(projection.claims, concept.id, 'yarramate/constraint/requires'),
             ],
+            [
+                'references',
+                referencesFor(projection.claims, concept.id, 'yarramate/reference/refers-to'),
+            ],
         ], '    ');
         if (description === undefined && metadata.length === 0) {
             lines.push(`  ${external} = ${kind} ${quote(name)}`);
@@ -159,6 +163,7 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
         if (source === undefined || target === undefined)
             continue;
         const name = valueFor(projection.claims, relationship.id, 'yarramate/relationship/name');
+        const description = valueFor(projection.claims, relationship.id, 'yarramate/relationship/description');
         const metadata = metadataLines([
             ['yarramateId', relationship.id],
             ['yarramateKind', structural.predicate],
@@ -175,8 +180,16 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
                 'content',
                 valueFor(projection.claims, relationship.id, 'yarramate/flow/content'),
             ],
+            [
+                'references',
+                referencesFor(projection.claims, relationship.id, 'yarramate/reference/refers-to'),
+            ],
         ], '    ');
-        lines.push(`  ${source} -[${externalRelationshipKind.get(structural.predicate) ?? kindId(structural.predicate)}]-> ${target}${name === undefined ? '' : ` ${quote(name)}`}${metadata.length === 0 ? '' : ' {'}`, ...metadata, ...(metadata.length === 0 ? [] : ['  }']));
+        lines.push(`  ${source} -[${externalRelationshipKind.get(structural.predicate) ?? kindId(structural.predicate)}]-> ${target}${name === undefined ? '' : ` ${quote(name)}`}${description === undefined && metadata.length === 0 ? '' : ' {'}`, ...(description === undefined
+            ? []
+            : [`    description ${quote(description)}`]), ...metadata, ...(description === undefined && metadata.length === 0
+            ? []
+            : ['  }']));
     }
     const viewId = identifier.test(projection.projection.split('@')[0] ?? '')
         ? projection.projection.split('@')[0]

package/dist/adapters/likec4-project.js

@@ -73,7 +73,7 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
     }
     if (dynamic !== undefined) {
         const claimsById = new Map(prepared.projection.claims.map((claim) => [claim.id, claim]));
-        const lines = dynamic.steps.map((step) => {
+        const lines = dynamic.steps.flatMap((step) => {
             const structural = claimsById.get(step.relationship);
             const source = externalByNative.get(structural.subject);
             const target = 'ref' in structural.object
@@ -86,7 +86,21 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
                 (declaredTitle !== undefined && 'value' in declaredTitle.object
                     ? declaredTitle.object.value
                     : undefined);
-            return `    ${source} -> ${target}${title === undefined ? '' : ` ${quote(title)}`}`;
+            const declaredDescription = prepared.projection.claims.find((claim) => claim.subject === step.relationship &&
+                claim.predicate === 'yarramate/relationship/description' &&
+                'value' in claim.object);
+            const description = declaredDescription !== undefined &&
+                'value' in declaredDescription.object
+                ? declaredDescription.object.value
+                : undefined;
+            const statement = `    ${source} -> ${target}${title === undefined ? '' : ` ${quote(title)}`}`;
+            return description === undefined
+                ? [statement]
+                : [
+                    `${statement} {`,
+                    `      description ${quote(description)}`,
+                    '    }',
+                ];
         });
         const viewId = id ?? prepared.projection.projection.split('@')[0];
         return [

package/dist/cli-support.d.ts

@@ -5,7 +5,7 @@ export interface CliResult {
     readonly stderr: string;
 }
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
-export declare const usage = "Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--status <status>] [--mode <mode>] [--content <text>] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
+export declare const usage = "Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown) => string;
 export declare const humanDiagnostics: (diagnostics: readonly Pick<Diagnostic, "path" | "line" | "column" | "code" | "message">[]) => string;

package/dist/cli-support.js

@@ -14,7 +14,7 @@ export const isMainModule = (moduleUrl, entrypoint) => {
         return false;
     }
 };
-export const usage = 'Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--status <status>] [--mode <mode>] [--content <text>] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n';
+export const usage = 'Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/cli.js

@@ -301,6 +301,7 @@ const oneFlag = (flags, flag) => {
 };
 const hasRepeatedSingletonFlag = (flags) => [...flags.entries()].some(([flag, values]) => flag !== '--source' &&
     flag !== '--constraint' &&
+    flag !== '--reference' &&
     flag !== '--present-in' &&
     values.length !== 1);
 const appendBlockItem = (document, collection, item) => {
@@ -310,6 +311,20 @@ const appendBlockItem = (document, collection, item) => {
         sequence.flow = false;
     }
 };
+const identifiedReferences = (values) => {
+    const parsed = values.map((value) => {
+        const separator = value.indexOf('=');
+        return separator <= 0 || separator === value.length - 1
+            ? undefined
+            : {
+                id: value.slice(0, separator),
+                ref: value.slice(separator + 1),
+            };
+    });
+    return parsed.some((reference) => reference === undefined)
+        ? undefined
+        : parsed;
+};
 const runAdd = (options, cwd) => {
     const parsed = parseFlags(options);
     if (parsed === undefined) {
@@ -323,6 +338,7 @@ const runAdd = (options, cwd) => {
         '--description',
         '--owner',
         '--constraint',
+        '--reference',
         '--present-in',
         '--source',
     ]);
@@ -336,16 +352,9 @@ const runAdd = (options, cwd) => {
     if (id === undefined || kind === undefined || name === undefined) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
-    const constraints = (parsed.flags.get('--constraint') ?? []).map((value) => {
-        const separator = value.indexOf('=');
-        return separator <= 0 || separator === value.length - 1
-            ? undefined
-            : {
-                id: value.slice(0, separator),
-                ref: value.slice(separator + 1),
-            };
-    });
-    if (constraints.some((constraint) => constraint === undefined)) {
+    const constraints = identifiedReferences(parsed.flags.get('--constraint') ?? []);
+    const references = identifiedReferences(parsed.flags.get('--reference') ?? []);
+    if (constraints === undefined || references === undefined) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -365,6 +374,7 @@ const runAdd = (options, cwd) => {
                 ? {}
                 : { owner: oneFlag(parsed.flags, '--owner') }),
             ...(constraints.length === 0 ? {} : { constraints }),
+            ...(references.length === 0 ? {} : { references }),
             ...(parsed.flags.get('--present-in') === undefined
                 ? {}
                 : { presentIn: parsed.flags.get('--present-in') }),
@@ -417,9 +427,11 @@ const runConnect = (options, cwd) => {
         '--from',
         '--to',
         '--name',
+        '--description',
         '--status',
         '--mode',
         '--content',
+        '--reference',
         '--present-in',
         '--source',
     ]);
@@ -437,6 +449,10 @@ const runConnect = (options, cwd) => {
         to === undefined) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
+    const references = identifiedReferences(parsed.flags.get('--reference') ?? []);
+    if (references === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
     try {
         const absolutePath = resolve(cwd, parsed.path);
         const document = parseDocument(readFileSync(absolutePath, 'utf8'));
@@ -448,6 +464,9 @@ const runConnect = (options, cwd) => {
             ...(oneFlag(parsed.flags, '--name') === undefined
                 ? {}
                 : { name: oneFlag(parsed.flags, '--name') }),
+            ...(oneFlag(parsed.flags, '--description') === undefined
+                ? {}
+                : { description: oneFlag(parsed.flags, '--description') }),
             ...(oneFlag(parsed.flags, '--status') === undefined
                 ? {}
                 : { status: oneFlag(parsed.flags, '--status') }),
@@ -457,6 +476,7 @@ const runConnect = (options, cwd) => {
             ...(oneFlag(parsed.flags, '--content') === undefined
                 ? {}
                 : { content: oneFlag(parsed.flags, '--content') }),
+            ...(references.length === 0 ? {} : { references }),
             ...(parsed.flags.get('--present-in') === undefined
                 ? {}
                 : { presentIn: parsed.flags.get('--present-in') }),
@@ -535,6 +555,9 @@ const runCompile = (options, cwd) => {
 };
 export function runCli(args, cwd = process.cwd()) {
     const [command, ...options] = args;
+    if (command === '--help' || command === '-h' || command === 'help') {
+        return { exitCode: 0, stdout: usage, stderr: '' };
+    }
     if (command === 'init') {
         return runInit(options, cwd);
     }

package/dist/compiler.js

@@ -376,6 +376,11 @@ function compileWorkspaceResolved(sources) {
     ])));
     const qualifyReference = (documentId, reference) => reference.includes('#') ? reference : `${documentId}#${reference}`;
     const architectureStateIds = new Set(documents.flatMap(({ value }) => (value.states ?? []).map((state) => `${value.id}#${state.id}`)));
+    const subjectIds = new Set(documents.flatMap(({ value }) => [
+        ...(value.states ?? []).map((state) => `${value.id}#${state.id}`),
+        ...value.concepts.map((concept) => `${value.id}#${concept.id}`),
+        ...value.relationships.map((relationship) => `${value.id}#${relationship.id}`),
+    ]));
     const architectureStateAfter = new Map(documents.flatMap(({ value }) => (value.states ?? []).flatMap((state) => state.after === undefined
         ? []
         : [
@@ -582,6 +587,36 @@ function compileWorkspaceResolved(sources) {
                     });
                 }
             }
+            const seenReferenceIds = new Set();
+            for (const [referenceIndex, reference] of (concept.references ?? []).entries()) {
+                if (seenReferenceIds.has(reference.id)) {
+                    const pointer = `/concepts/${index}/references/${referenceIndex}/id`;
+                    const source = location(['concepts', index, 'references', referenceIndex, 'id'], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM309',
+                        message: `Duplicate reference ID "${reference.id}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+                seenReferenceIds.add(reference.id);
+                if (!subjectIds.has(qualifyReference(value.id, reference.ref))) {
+                    const pointer = `/concepts/${index}/references/${referenceIndex}/ref`;
+                    const source = location(['concepts', index, 'references', referenceIndex, 'ref'], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM308',
+                        message: `Unresolved subject reference "${reference.ref}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+            }
             for (const [stateIndex, state] of (concept.presentIn ?? []).entries()) {
                 if (!architectureStateIds.has(qualifyReference(value.id, state))) {
                     const pointer = `/concepts/${index}/presentIn/${stateIndex}`;
@@ -599,6 +634,48 @@ function compileWorkspaceResolved(sources) {
             }
         }
         for (const [index, relationship] of value.relationships.entries()) {
+            const seenReferenceIds = new Set();
+            for (const [referenceIndex, reference] of (relationship.references ?? []).entries()) {
+                if (seenReferenceIds.has(reference.id)) {
+                    const pointer = `/relationships/${index}/references/${referenceIndex}/id`;
+                    const source = location([
+                        'relationships',
+                        index,
+                        'references',
+                        referenceIndex,
+                        'id',
+                    ], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM309',
+                        message: `Duplicate reference ID "${reference.id}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+                seenReferenceIds.add(reference.id);
+                if (!subjectIds.has(qualifyReference(value.id, reference.ref))) {
+                    const pointer = `/relationships/${index}/references/${referenceIndex}/ref`;
+                    const source = location([
+                        'relationships',
+                        index,
+                        'references',
+                        referenceIndex,
+                        'ref',
+                    ], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM308',
+                        message: `Unresolved subject reference "${reference.ref}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+            }
             for (const [stateIndex, state] of (relationship.presentIn ?? []).entries()) {
                 const stateIdentity = qualifyReference(value.id, state);
                 if (!architectureStateIds.has(stateIdentity)) {
@@ -785,6 +862,18 @@ function compileWorkspaceResolved(sources) {
                     source: location(['concepts', index, 'constraints', constraintIndex, 'ref'], `/concepts/${index}/constraints/${constraintIndex}/ref`),
                 });
             }
+            for (const [referenceIndex, reference] of (concept.references ?? []).entries()) {
+                claims.push({
+                    id: `${subject}~reference-${reference.id}`,
+                    subject,
+                    predicate: 'yarramate/reference/refers-to',
+                    object: {
+                        ref: qualifyReference(value.id, reference.ref),
+                    },
+                    origin: 'declared',
+                    source: location(['concepts', index, 'references', referenceIndex, 'ref'], `/concepts/${index}/references/${referenceIndex}/ref`),
+                });
+            }
             for (const [stateIndex, state] of (concept.presentIn ?? []).entries()) {
                 const stateIdentity = qualifyReference(value.id, state);
                 claims.push({
@@ -819,6 +908,16 @@ function compileWorkspaceResolved(sources) {
                     source: location(['relationships', index, 'name'], `/relationships/${index}/name`),
                 });
             }
+            if (relationship.description !== undefined) {
+                claims.push({
+                    id: `${id}~description`,
+                    subject: id,
+                    predicate: 'yarramate/relationship/description',
+                    object: { value: relationship.description },
+                    origin: 'declared',
+                    source: location(['relationships', index, 'description'], `/relationships/${index}/description`),
+                });
+            }
             if (relationship.mode !== undefined) {
                 claims.push({
                     id: `${id}~mode`,
@@ -849,6 +948,18 @@ function compileWorkspaceResolved(sources) {
                     source: location(['relationships', index, 'status'], `/relationships/${index}/status`),
                 });
             }
+            for (const [referenceIndex, reference] of (relationship.references ?? []).entries()) {
+                claims.push({
+                    id: `${id}~reference-${reference.id}`,
+                    subject: id,
+                    predicate: 'yarramate/reference/refers-to',
+                    object: {
+                        ref: qualifyReference(value.id, reference.ref),
+                    },
+                    origin: 'declared',
+                    source: location(['relationships', index, 'references', referenceIndex, 'ref'], `/relationships/${index}/references/${referenceIndex}/ref`),
+                });
+            }
             for (const [stateIndex, state] of (relationship.presentIn ?? []).entries()) {
                 const stateIdentity = qualifyReference(value.id, state);
                 claims.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
   ],
   "files": [
     "dist",
+    "assets/likec4",
     "schema",
     "skills/yarramate-architecture",
     "docs/CONSUMING-YARRAMATE.md"
@@ -78,7 +79,7 @@
     "build": "tsc -p tsconfig.build.json",
     "prepack": "pnpm build",
     "docs:dev": "pnpm self:export:likec4 && likec4 serve .yarramate-out/likec4",
-    "format": "likec4 format .yarramate/integrations/likec4/prototype",
+    "format": "likec4 format assets/likec4",
     "self:check": "pnpm build && node dist/cli.js check .yarramate/workspace.yaml",
     "self:check:json": "pnpm build && node dist/cli.js check .yarramate/workspace.yaml --json",
     "self:compile": "pnpm build && node dist/cli.js compile .yarramate/workspace.yaml",

package/schema/yarramate-core-contract.schema.json

@@ -92,6 +92,7 @@
           "deterministic-diagnostic-order",
           "git-native-governance",
           "globally-qualified-compiled-identities",
+          "identified-reference-integrity",
           "no-partial-graph-on-error",
           "portable-projection-selectors",
           "source-located-diagnostics"
@@ -110,6 +111,7 @@
           "architectural-quality",
           "automatic-discovery",
           "external-language-conformance",
+          "formal-workflow-semantics",
           "state-scoped-claim-values"
         ]
       }

package/schema/yarramate-document.schema.json

@@ -100,6 +100,9 @@
             "$ref": "#/$defs/constraint"
           }
         },
+        "references": {
+          "$ref": "#/$defs/identifiedReferences"
+        },
         "presentIn": {
           "$ref": "#/$defs/stateReferences"
         }
@@ -118,6 +121,26 @@
         }
       }
     },
+    "identifiedReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "ref"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "ref": {
+          "$ref": "#/$defs/reference"
+        }
+      }
+    },
+    "identifiedReferences": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/identifiedReference"
+      }
+    },
     "relationship": {
       "type": "object",
       "additionalProperties": false,
@@ -139,6 +162,9 @@
         "name": {
           "$ref": "#/$defs/nonEmptyText"
         },
+        "description": {
+          "$ref": "#/$defs/nonEmptyText"
+        },
         "mode": {
           "enum": ["read", "write", "read-write", "unspecified"]
         },
@@ -148,6 +174,9 @@
         "status": {
           "$ref": "#/$defs/lifecycleStatus"
         },
+        "references": {
+          "$ref": "#/$defs/identifiedReferences"
+        },
         "presentIn": {
           "$ref": "#/$defs/stateReferences"
         }

package/skills/yarramate-architecture/references/native-authoring.md

@@ -43,7 +43,11 @@ relationships:
     kind: access
     from: delivery-api
     to: delivery-data
+    description: The API uses the governed record without maintaining a copy.
     mode: read-write
+    references:
+      - id: residency-policy
+        ref: delivery-data
 ```
 
 IDs are document-local and compile to `document-id#subject-id`. Cross-document
@@ -76,6 +80,29 @@ use association when no stronger semantic meaning is justified.
 Ownership is one accountable reference, not approval workflow. Constraints are
 identified references, not a policy engine or free-form metadata bag.
 
+## Rationale and citations
+
+Use `description` on either a concept or relationship for decided narrative
+about that exact subject. Use an identified `references` entry when the
+narrative depends on another concept or relationship and the citation must
+remain checkable:
+
+```yaml
+description: Failure releases the lease and retains partial evidence.
+references:
+  - id: failure-destination
+    ref: retry-pool
+```
+
+Core checks the explicit target and local reference ID. It does not scan prose
+for IDs or interpret descriptions as formal preconditions, postconditions, or
+workflow rules.
+
+For interaction flows, model steps that need identity as behavior concepts and
+model normal or failure transitions as native relationships. A LikeC4 dynamic
+view may order those projected relationships and display their descriptions;
+the view does not become the workflow source of truth.
+
 ## Architecture states
 
 ```yaml
@@ -153,7 +180,9 @@ yarramate add .yarramate/architecture/main.yaml \
   --id delivery-api --kind applicationComponent --name "Delivery API"
 yarramate connect .yarramate/architecture/main.yaml \
   --id api-realizes-service --kind realization \
-  --from delivery-api --to delivery-service
+  --from delivery-api --to delivery-service \
+  --description "The API implements the agreed delivery boundary" \
+  --reference decision-source=delivery-service
 yarramate check .yarramate/workspace.yaml --json
 yarramate compile .yarramate/workspace.yaml
 yarramate context <projection.yaml> .yarramate/workspace.yaml