yarramate 0.4.0 → 0.5.0

package/dist/adapters/graphify-cli.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { adapterMappingEntryLocation, adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { compileWorkspace } from '../compiler.js';
-import { diagnosticJson, isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
+import { diagnosticJson, isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
 import { observeGraphify, } from './graphify.js';
 const usage = 'Usage:\n' +
     '  yarramate-graphify observe <graph.json> <mapping.yaml> <workspace-or-source...> --id <evidence-id> --version <major.minor>\n';
@@ -35,6 +35,9 @@ const parseOptions = (options) => {
 };
 export function runGraphifyCli(args, cwd = process.cwd()) {
     const [command, ...options] = args;
+    if (command === '--version') {
+        return versionResult('yarramate-graphify');
+    }
     const parsed = command === 'observe' ? parseOptions(options) : undefined;
     if (parsed === undefined ||
         !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(parsed.id) ||

package/dist/adapters/likec4-cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { isMap, isSeq, parseDocument } from 'yaml';
-import { isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
+import { isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
 import { compileWorkspace } from '../compiler.js';
 import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { locateSourcePath } from '../source-document.js';
@@ -88,6 +88,33 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
     ok,
     diagnostics,
 }, null, 2)}\n`;
+const unmappedSubjectPreviewLength = 3;
+const summarizeUnmappedConcepts = (diagnostics) => {
+    const unmapped = diagnostics.filter((diagnostic) => diagnostic.code === 'YMLC102');
+    if (unmapped.length <= unmappedSubjectPreviewLength)
+        return diagnostics;
+    const preview = unmapped
+        .slice(0, unmappedSubjectPreviewLength)
+        .map((diagnostic) => 'subject' in diagnostic && diagnostic.subject !== undefined
+        ? `"${diagnostic.subject}"`
+        : `"${diagnostic.path}:${diagnostic.line}"`)
+        .join(', ');
+    const summary = {
+        ...unmapped[0],
+        message: `${unmapped.length} projected concepts have no LikeC4 mapping ` +
+            `(first: ${preview}); run "yarramate-likec4 map --sync" to add ` +
+            'the missing mappings',
+    };
+    let summarized = false;
+    return diagnostics.flatMap((diagnostic) => {
+        if (diagnostic.code !== 'YMLC102')
+            return [diagnostic];
+        if (summarized)
+            return [];
+        summarized = true;
+        return [summary];
+    });
+};
 const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
@@ -371,6 +398,9 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
     };
 };
 export function runLikeC4Cli(args, cwd = process.cwd()) {
+    if (args[0] === '--version') {
+        return versionResult('yarramate-likec4');
+    }
     if (args[0] === 'map') {
         return runLikeC4MapSync(args.slice(1), cwd);
     }
@@ -460,7 +490,11 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
         sourcePaths.some((argument) => argument.startsWith('-'))) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
-    const diagnosticOutput = (diagnostics) => (json ? checkJson(false, diagnostics) : diagnosticJson(diagnostics));
+    const diagnosticOutput = (diagnostics) => json
+        ? checkJson(false, diagnostics)
+        : diagnosticJson(command === 'check'
+            ? summarizeUnmappedConcepts(diagnostics)
+            : diagnostics);
     try {
         const resolved = resolveCliWorkspaceSources(sourcePaths, cwd);
         if (!resolved.ok) {
@@ -487,6 +521,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                     stderr: '',
                 };
             }
+            const projectDirectory = dirname(resolve(cwd, projectionPath));
             const referencedSources = new Map();
             const referenceDiagnostics = [];
             const readProjectReference = (path, label, yamlPath, pointer) => {
@@ -496,7 +531,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 try {
                     const source = {
                         path,
-                        source: readFileSync(resolve(cwd, path), 'utf8'),
+                        source: readFileSync(resolve(projectDirectory, path), 'utf8'),
                     };
                     referencedSources.set(path, source);
                     return source;

package/dist/adapters/mcp-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createInterface } from 'node:readline';
-import { isMainModule } from '../cli-support.js';
+import { isMainModule, packageVersion, versionResult, } from '../cli-support.js';
 import { runCli } from '../cli.js';
 const workspaceProperty = {
     workspace: {
@@ -97,7 +97,7 @@ export const handleRequest = (request) => {
         respond(id, {
             protocolVersion: '2025-06-18',
             capabilities: { tools: {} },
-            serverInfo: { name: 'yarramate', version: '0.1' },
+            serverInfo: { name: 'yarramate', version: packageVersion },
             instructions: 'Read-only architecture context for YarraMate workspaces. The native documents in the repository remain canonical; this server never mutates them.',
         });
         return;
@@ -142,24 +142,31 @@ export const handleRequest = (request) => {
     }
 };
 if (isMainModule(import.meta.url, process.argv[1])) {
-    const lines = createInterface({ input: process.stdin });
-    lines.on('line', (line) => {
-        const text = line.trim();
-        if (text.length === 0)
-            return;
-        let request;
-        try {
-            request = JSON.parse(text);
-        }
-        catch {
-            respondError(null, -32700, 'Parse error');
-            return;
-        }
-        try {
-            handleRequest(request);
-        }
-        catch (error) {
-            respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
-        }
-    });
+    if (process.argv[2] === '--version') {
+        const result = versionResult('yarramate-mcp');
+        process.stdout.write(result.stdout);
+        process.exitCode = result.exitCode;
+    }
+    else {
+        const lines = createInterface({ input: process.stdin });
+        lines.on('line', (line) => {
+            const text = line.trim();
+            if (text.length === 0)
+                return;
+            let request;
+            try {
+                request = JSON.parse(text);
+            }
+            catch {
+                respondError(null, -32700, 'Parse error');
+                return;
+            }
+            try {
+                handleRequest(request);
+            }
+            catch (error) {
+                respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
 }

package/dist/cli-support.d.ts

@@ -5,7 +5,9 @@ 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> ...] [--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 new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\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 packageVersion: string;
+export declare const versionResult: (binary: string) => CliResult;
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\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 new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\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, counted?: {
     readonly documents: number;

package/dist/cli-support.js

@@ -3,6 +3,9 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { loadWorkspaceManifest } from './workspace.js';
+import packageManifest from '../package.json' with {
+    type: 'json'
+};
 export const isMainModule = (moduleUrl, entrypoint) => {
     if (entrypoint === undefined)
         return false;
@@ -14,7 +17,13 @@ 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> ...] [--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 new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\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 packageVersion = packageManifest.version;
+export const versionResult = (binary) => ({
+    exitCode: 0,
+    stdout: `${binary} ${packageVersion}\n`,
+    stderr: '',
+});
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\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 new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\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

@@ -5,7 +5,7 @@ import { isSeq, parseDocument } from 'yaml';
 import { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
 import { compareArchitectureStates } from './architecture-state.js';
 import { serializeSemanticGraph } from './graph.js';
-import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, } from './cli-support.js';
+import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, versionResult, } from './cli-support.js';
 import { runCheckCommand } from './check-command.js';
 import { runNewCommand } from './new-command.js';
 import { runStatusCommand } from './status-command.js';
@@ -297,7 +297,7 @@ const runReconciliation = (options, cwd) => {
         }
         return {
             exitCode: 0,
-            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports), null, 2)}\n`,
+            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports, compilation.graph), null, 2)}\n`,
             stderr: '',
         };
     }
@@ -353,8 +353,10 @@ const runStateComparison = (options, cwd) => {
     }
 };
 const runInit = (options, cwd) => {
-    const target = options[0];
-    if (options.length !== 1 ||
+    const positional = options.filter((option) => option !== '--no-pointer');
+    const writePointer = positional.length === options.length;
+    const target = positional[0];
+    if (positional.length !== 1 ||
         target === undefined ||
         target.startsWith('-')) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -389,10 +391,8 @@ const runInit = (options, cwd) => {
         'projections: []\n' +
         'adapterMappings: []\n' +
         'evidence: []\n', 'utf8');
-    const agentsPath = resolve(workspaceRoot, 'AGENTS.md');
-    const displayAgentsPath = relative(cwd, agentsPath);
-    const agentsMarker = '## YarraMate architecture';
-    const agentsBlock = `${agentsMarker}\n` +
+    const pointerMarker = '## YarraMate architecture';
+    const pointerBlock = `${pointerMarker}\n` +
         '\n' +
         'This repository declares its architecture as canonical, versioned\n' +
         'YarraMate documents in `.yarramate/`. When prose documentation and the\n' +
@@ -403,24 +403,34 @@ const runInit = (options, cwd) => {
         '- Bounded task context: `yarramate context <projection.yaml> .yarramate/workspace.yaml`\n' +
         '\n' +
         'Author native documents only; never edit generated output.\n';
-    let agentsNote;
-    if (!existsSync(agentsPath)) {
-        writeFileSync(agentsPath, agentsBlock, 'utf8');
-        agentsNote = `Created ${displayAgentsPath} with the YarraMate pointer\n`;
-    }
-    else {
-        const existingAgents = readFileSync(agentsPath, 'utf8');
-        if (existingAgents.includes(agentsMarker)) {
-            agentsNote = `${displayAgentsPath} already declares the YarraMate pointer\n`;
-        }
-        else {
-            writeFileSync(agentsPath, `${existingAgents.replace(/\n*$/, '\n\n')}${agentsBlock}`, 'utf8');
-            agentsNote = `Extended ${displayAgentsPath} with the YarraMate pointer\n`;
+    // Harnesses look in different files: AGENTS.md is the cross-harness
+    // convention, while Claude Code auto-loads CLAUDE.md only. Delivering to
+    // both is what makes the pointer reach an agent without instruction.
+    const pointerNotes = [];
+    if (writePointer) {
+        for (const pointerFile of ['AGENTS.md', 'CLAUDE.md']) {
+            const pointerPath = resolve(workspaceRoot, pointerFile);
+            const displayPointerPath = relative(cwd, pointerPath);
+            if (!existsSync(pointerPath)) {
+                writeFileSync(pointerPath, pointerBlock, 'utf8');
+                pointerNotes.push(`Created ${displayPointerPath} with the YarraMate pointer\n`);
+            }
+            else {
+                const existingPointer = readFileSync(pointerPath, 'utf8');
+                if (existingPointer.includes(pointerMarker)) {
+                    pointerNotes.push(`${displayPointerPath} already declares the YarraMate pointer\n`);
+                }
+                else {
+                    writeFileSync(pointerPath, `${existingPointer.replace(/\n*$/, '\n\n')}${pointerBlock}`, 'utf8');
+                    pointerNotes.push(`Extended ${displayPointerPath} with the YarraMate pointer\n`);
+                }
+            }
         }
     }
     return {
         exitCode: 0,
-        stdout: `Created ${displayPath} and ${displayManifestPath}\n` + agentsNote,
+        stdout: `Created ${displayPath} and ${displayManifestPath}\n` +
+            pointerNotes.join(''),
         stderr: '',
     };
 };
@@ -706,6 +716,9 @@ export function runCli(args, cwd = process.cwd()) {
     if (command === '--help' || command === '-h' || command === 'help') {
         return { exitCode: 0, stdout: usage, stderr: '' };
     }
+    if (command === '--version' || command === '-v') {
+        return versionResult('yarramate');
+    }
     if (command === 'init') {
         return runInit(options, cwd);
     }

package/dist/compiler.js

@@ -54,6 +54,7 @@ function compileWorkspaceResolved(sources) {
             lineage: [`${coreProfile}#${policy.id}`],
             sourceAspects: policy.sourceAspects,
             targetAspects: policy.targetAspects,
+            repair: policy.repair,
         };
         coreRelationshipKinds.set(policy.id, resolved);
         relationshipKindByIdentity.set(resolved.identity, resolved);
@@ -798,7 +799,7 @@ function compileWorkspaceResolved(sources) {
                         diagnostics.push({
                             severity: 'error',
                             code: 'YM404',
-                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((aspect) => `"${aspect}"`).join(' or ')}; "${reference}" has aspect "${kind.aspect}"`,
+                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((aspect) => `"${aspect}"`).join(' or ')}; "${reference}" has aspect "${kind.aspect}"${policy.repair === undefined ? '' : `; ${policy.repair}`}`,
                             path: input.path,
                             pointer,
                             line: source.line,

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { checkCoreContract, loadCoreContract, type CoreContract, type CoreContra
 export { compareArchitectureStates, type StateComparison, type StateComparisonIssue, type StateComparisonResult, } from './architecture-state.js';
 export { loadWorkspaceManifest, type ResolvedWorkspace, type WorkspaceManifest, type WorkspaceManifestResult, } from './workspace.js';
 export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, type EvidenceDocument, type EvidenceEvaluationResult, type EvidenceLoadResult, type EvidenceLocator, type EvidenceObservation, type EvidenceReport, type EvidenceResult, type EvidenceWorkspaceEvaluationResult, } from './evidence.js';
-export { reconcileEvidenceReports, type ReconciliationFinding, type ReconciliationReport, } from './reconciliation.js';
+export { reconcileEvidenceReports, type AssertedRelationship, type ReconciliationFinding, type ReconciliationReport, } from './reconciliation.js';
 export type { CompilationResult, ContextualCompilationResult, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
 export { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, type AdapterMapping, type AdapterMappingLoadResult, type AdapterMappingValidationResult, type AdapterMappingsValidationResult, type AdapterSubjectMapping, } from './adapter-mapping.js';

package/dist/profile.d.ts

@@ -21,6 +21,11 @@ export interface RelationshipPolicy {
     readonly intent: string;
     readonly sourceAspects?: readonly Aspect[];
     readonly targetAspects?: readonly Aspect[];
+    /**
+     * Repair hint appended to endpoint-aspect diagnostics (YM404). A remedy,
+     * never a correction: the compiler still rejects the input.
+     */
+    readonly repair?: string;
 }
 /**
  * Safe, intentionally broad semantic constraints. A future licensed

package/dist/profile.js

@@ -137,6 +137,7 @@ export const relationshipPolicies = [
         id: 'assignment',
         intent: 'Allocate an active structure to behavior or responsibility',
         sourceAspects: ['active-structure'],
+        repair: 'assign from an active-structure element (an actor, component, or node), or use "association"',
     },
     { id: 'realization', intent: 'Fulfil a more abstract concept' },
     { id: 'serving', intent: 'Make behavior or an interface available' },
@@ -144,11 +145,13 @@ export const relationshipPolicies = [
         id: 'access',
         intent: 'Read, write, create, or use passive structure',
         targetAspects: ['passive-structure'],
+        repair: 'point "access" at passive structure (a business object, data object, or artifact), or use "association"',
     },
     {
         id: 'influence',
         intent: 'Affect a motivation concept',
         targetAspects: ['motivation'],
+        repair: 'point "influence" at a motivation concept (a goal, requirement, or principle), or use "association"',
     },
     { id: 'association', intent: 'Relevant connection with no stronger meaning' },
     {
@@ -156,6 +159,7 @@ export const relationshipPolicies = [
         intent: 'Express temporal or causal precedence',
         sourceAspects: ['behavior'],
         targetAspects: ['behavior'],
+        repair: 'use "flow" between active-structure elements, or introduce a behavior concept and "assignment"',
     },
     { id: 'flow', intent: 'Transfer information, value, goods, or material' },
     { id: 'specialization', intent: 'Express a more specific form' },

package/dist/reconciliation.d.ts

@@ -1,9 +1,17 @@
+import type { SemanticGraph } from './compiler.js';
 import type { EvidenceLocator, EvidenceReport, EvidenceResult } from './evidence.js';
+export interface AssertedRelationship {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: string;
+    readonly name?: string;
+}
 export interface ReconciliationFinding {
     readonly target: {
         readonly type: 'subject' | 'claim';
         readonly id: string;
     };
+    readonly asserted?: AssertedRelationship;
     readonly result: Exclude<EvidenceResult, 'confirmed'>;
     readonly provider: string;
     readonly evidenceDocument: string;
@@ -23,4 +31,4 @@ export interface ReconciliationReport {
     };
     readonly findings: readonly ReconciliationFinding[];
 }
-export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[]): ReconciliationReport;
+export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[], graph?: SemanticGraph): ReconciliationReport;

package/dist/reconciliation.js

@@ -1,4 +1,32 @@
-export function reconcileEvidenceReports(workspace, reports) {
+const assertedRelationshipsByClaim = (graph) => {
+    const asserted = new Map();
+    if (graph === undefined)
+        return asserted;
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const names = new Map();
+    for (const claim of graph.claims) {
+        if (claim.predicate === 'yarramate/relationship/name' &&
+            'value' in claim.object) {
+            names.set(claim.subject, claim.object.value);
+        }
+    }
+    for (const claim of graph.claims) {
+        if (!relationshipIds.has(claim.id) || !('ref' in claim.object))
+            continue;
+        const name = names.get(claim.id);
+        asserted.set(claim.id, {
+            from: claim.subject,
+            to: claim.object.ref,
+            kind: claim.predicate,
+            ...(name === undefined ? {} : { name }),
+        });
+    }
+    return asserted;
+};
+export function reconcileEvidenceReports(workspace, reports, graph) {
+    const assertedByClaim = assertedRelationshipsByClaim(graph);
     const summary = {
         evidenceDocuments: reports.length,
         observations: 0,
@@ -22,10 +50,13 @@ export function reconcileEvidenceReports(workspace, reports) {
             else {
                 summary[observation.result] += 1;
             }
+            const target = 'subject' in observation
+                ? { type: 'subject', id: observation.subject }
+                : { type: 'claim', id: observation.claim };
+            const asserted = target.type === 'claim' ? assertedByClaim.get(target.id) : undefined;
             findings.push({
-                target: 'subject' in observation
-                    ? { type: 'subject', id: observation.subject }
-                    : { type: 'claim', id: observation.claim },
+                target,
+                ...(asserted === undefined ? {} : { asserted }),
                 result: observation.result,
                 provider: report.provider,
                 evidenceDocument: report.evidence,

package/dist/status-command.js

@@ -91,7 +91,7 @@ export function runStatusCommand(options, cwd) {
                     });
                     const evaluation = evaluateEvidenceWorkspace(compilation.graph, evidenceDocuments);
                     if (evaluation.ok) {
-                        reconciliation = reconcileEvidenceReports(workspace.id, evaluation.reports).summary;
+                        reconciliation = reconcileEvidenceReports(workspace.id, evaluation.reports, compilation.graph).summary;
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -92,11 +92,11 @@
     "self:contract": "pnpm build && node dist/cli.js context .yarramate/projections/core-contract-foundation.yaml .yarramate/workspace.yaml",
     "self:evidence": "pnpm build && node dist/cli.js evidence .yarramate/evidence/repository.yaml .yarramate/workspace.yaml",
     "self:reconcile": "pnpm build && node dist/cli.js reconcile .yarramate/workspace.yaml",
-    "self:check:likec4": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/integrations/likec4/project.yaml .yarramate/workspace.yaml",
-    "self:check:likec4:json": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml",
-    "self:export:likec4": "pnpm build && node dist/adapters/likec4-cli.js export-project .yarramate/integrations/likec4/project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml",
+    "self:check:likec4": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/likec4-project.yaml .yarramate/workspace.yaml",
+    "self:check:likec4:json": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml",
+    "self:export:likec4": "pnpm build && node dist/adapters/likec4-cli.js export-project .yarramate/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml",
     "validate": "pnpm self:export:likec4 && likec4 validate --no-layout .yarramate-out/likec4",
-    "verify": "pnpm typecheck && pnpm test && pnpm self:check && pnpm validate",
+    "verify": "pnpm typecheck && pnpm build && pnpm test && pnpm self:check && pnpm validate",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },

package/schema/yarramate-likec4-project.schema.json

@@ -41,7 +41,7 @@
     },
     "path": {
       "type": "string",
-      "description": "Repository-relative path resolved from the CLI working directory. Parent traversal, absolute paths, and backslashes are rejected.",
+      "description": "Path resolved from the project-definition document's directory, matching workspace-manifest semantics. Parent traversal, absolute paths, and backslashes are rejected, so references stay beneath the project document.",
       "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
     },
     "subjectIdentity": {

package/schema/yarramate-reconciliation-report.schema.json

@@ -66,6 +66,21 @@
         "message": { "type": "string", "minLength": 1 }
       }
     },
+    "subjectIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*#[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "assertedRelationship": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to", "kind"],
+      "properties": {
+        "from": { "$ref": "#/$defs/subjectIdentity" },
+        "to": { "$ref": "#/$defs/subjectIdentity" },
+        "kind": { "type": "string", "pattern": "^\\S+$" },
+        "name": { "type": "string", "minLength": 1 }
+      }
+    },
     "finding": {
       "type": "object",
       "additionalProperties": false,
@@ -78,6 +93,7 @@
       ],
       "properties": {
         "target": { "$ref": "#/$defs/target" },
+        "asserted": { "$ref": "#/$defs/assertedRelationship" },
         "result": {
           "enum": ["contradicted", "unknown", "not-observed"]
         },

package/skills/yarramate-architecture/SKILL.md

@@ -67,7 +67,7 @@ document, projection, evidence, or architecture-state syntax is needed.
 7. Add the focused projections needed to answer the
    repository-orientation question. Add a separate projection for every
    ordered flow that needs a dynamic view, then include each intended view in
-   `.yarramate/integrations/likec4/project.yaml`.
+   `.yarramate/likec4-project.yaml`.
 8. Unless the user requested semantic-only output, create the optional LikeC4
    mapping and project described in the authoring reference. Synchronize the
    project mapping before every export, then run:
@@ -79,9 +79,9 @@ yarramate evidence .yarramate/evidence/<evidence>.yaml .yarramate/workspace.yaml
 yarramate reconcile .yarramate/workspace.yaml
 yarramate context .yarramate/projections/<projection>.yaml .yarramate/workspace.yaml
 yarramate view .yarramate/projections/<projection>.yaml .yarramate/workspace.yaml
-yarramate-likec4 check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml
+yarramate-likec4 check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml
 yarramate-likec4 map --sync .yarramate/integrations/likec4/subject-mapping.yaml .yarramate/workspace.yaml
-yarramate-likec4 export-project .yarramate/integrations/likec4/project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
+yarramate-likec4 export-project .yarramate/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
 ```
 
 9. Audit rendering coverage before handoff. Answer these as reporting
@@ -114,7 +114,7 @@ yarramate-likec4 export-project .yarramate/integrations/likec4/project.yaml .yar
    - a bounded target projection for implementation agents.
    - one focused projection per ordered flow that needs a dynamic view.
    Include every intended view in
-   `.yarramate/integrations/likec4/project.yaml`.
+   `.yarramate/likec4-project.yaml`.
 6. Synchronize the project mapping before every export, then run:
 
 ```sh
@@ -125,9 +125,9 @@ yarramate context .yarramate/projections/<target>.yaml .yarramate/workspace.yaml
 yarramate view .yarramate/projections/<target>.yaml .yarramate/workspace.yaml
 yarramate view .yarramate/projections/<flow>.yaml .yarramate/workspace.yaml
 yarramate compare <document-id>#<baseline-state> <document-id>#<target-state> .yarramate/workspace.yaml
-yarramate-likec4 check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml
+yarramate-likec4 check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml
 yarramate-likec4 map --sync .yarramate/integrations/likec4/subject-mapping.yaml .yarramate/workspace.yaml
-yarramate-likec4 export-project .yarramate/integrations/likec4/project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
+yarramate-likec4 export-project .yarramate/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
 ```
 
    Skip the two adapter commands only when the user requested semantic-only
@@ -169,7 +169,7 @@ retired concept.
 
 ```sh
 yarramate check .yarramate/workspace.yaml --json
-yarramate-likec4 check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml
+yarramate-likec4 check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml
 ```
 
 6. If the adapter check reports intended mapping drift, repair it locally,
@@ -181,8 +181,8 @@ yarramate-likec4 check .yarramate/integrations/likec4/project.yaml --json .yarra
 yarramate-likec4 map --sync --prune .yarramate/integrations/likec4/subject-mapping.yaml .yarramate/workspace.yaml
 git diff -- .yarramate
 yarramate check .yarramate/workspace.yaml --json
-yarramate-likec4 check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml
-yarramate-likec4 export-project .yarramate/integrations/likec4/project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
+yarramate-likec4 check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml
+yarramate-likec4 export-project .yarramate/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
 ```
 
 7. Require both configured read-only checks to exit successfully after the

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

@@ -67,6 +67,71 @@ Use `mode: read|write|read-write|unspecified` only with `access`. Use
 `content` only with `flow`. Prefer a precise relationship over `association`;
 use association when no stronger semantic meaning is justified.
 
+Every concept kind carries an aspect: `motivation`, `active-structure`
+(actors, roles, components, nodes, interfaces), `behavior` (processes,
+functions, interactions, services, events), `passive-structure` (objects,
+data, artifacts, material), or `composite`. Four relationship kinds constrain
+endpoint aspects, and the compiler rejects violations as `YM404`:
+
+```text
+assignment  source must be active-structure
+access      target must be passive-structure
+influence   target must be motivation
+triggering  source and target must be behavior
+```
+
+The other kinds accept endpoints of any aspect.
+
+## Invocation chains
+
+"User invokes command" and "component invokes component" fail `YM404` when
+written as `triggering` between active-structure elements. Name the invoked
+behavior, assign the performers, and trigger between behaviors:
+
+```yaml
+concepts:
+  - id: user
+    kind: businessActor
+    name: User
+  - id: cli
+    kind: applicationComponent
+    name: CLI
+  - id: run-check
+    kind: applicationProcess
+    name: Run check
+relationships:
+  - id: user-starts-run-check
+    kind: assignment
+    from: user
+    to: run-check
+    name: User invokes the check command
+  - id: cli-performs-run-check
+    kind: assignment
+    from: cli
+    to: run-check
+```
+
+Chain steps with `triggering` only between behavior concepts, for example
+`run-check` triggering a downstream process owned by another component.
+
+## Degrading a blocked kind
+
+When aspect policy blocks the kind you want—`triggering` between two
+components is the common case—keep the edge legal with `kind: flow` and carry
+the invocation semantics on the edge's `name` and `description`:
+
+```sh
+yarramate connect .yarramate/architecture/main.yaml \
+  --id cli-invokes-engine --kind flow \
+  --from cli --to engine \
+  --name "invokes" \
+  --description "The CLI invokes the engine once per check run"
+```
+
+Both fields compile to claims, so evidence can later confirm or contradict
+the recorded invocation semantics; the degradation loses no reviewable
+information.
+
 ## Ownership and constraints
 
 ```yaml
@@ -176,18 +241,21 @@ evidence result.
 
 ## LikeC4 project
 
-Keep visualization configuration outside native documents:
+Keep visualization configuration outside native documents. Project `mapping`,
+`kindMapping`, and `views[].projection` paths resolve from the
+project-definition document's directory, so place the definition at or above
+everything it references — `.yarramate/likec4-project.yaml` in this layout:
 
 ```yaml
 format: yarramate/likec4-project/v1
 id: delivery
 version: "1.0"
 title: Delivery architecture
-mapping: .yarramate/integrations/likec4/subject-mapping.yaml
+mapping: integrations/likec4/subject-mapping.yaml
 views:
-  - projection: .yarramate/projections/delivery-target.yaml
+  - projection: projections/delivery-target.yaml
   - id: submit-order
-    projection: .yarramate/projections/submit-order.yaml
+    projection: projections/submit-order.yaml
     dynamic:
       steps:
         - relationship: delivery#customer-triggers-submit
@@ -237,14 +305,14 @@ yarramate compare <from-state> <to-state> .yarramate/workspace.yaml
 yarramate evidence <evidence.yaml> .yarramate/workspace.yaml
 yarramate reconcile .yarramate/workspace.yaml
 yarramate-likec4 check \
-  .yarramate/integrations/likec4/project.yaml \
+  .yarramate/likec4-project.yaml \
   --json \
   .yarramate/workspace.yaml
 yarramate-likec4 map --sync \
   .yarramate/integrations/likec4/subject-mapping.yaml \
   .yarramate/workspace.yaml
 yarramate-likec4 export-project \
-  .yarramate/integrations/likec4/project.yaml \
+  .yarramate/likec4-project.yaml \
   .yarramate-out/likec4 \
   .yarramate/workspace.yaml
 ```