yarramate 0.1.0

package/dist/workspace.js

@@ -0,0 +1,114 @@
+import { globSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep, } from 'node:path';
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { diagnosticOrder, loadSourceDocument, } from './source-document.js';
+import workspaceSchema from '../schema/yarramate-workspace.schema.json' with {
+    type: 'json'
+};
+const Ajv2020 = Ajv2020Module.default;
+const validateWorkspace = new Ajv2020({ allErrors: true }).compile(workspaceSchema);
+export function loadWorkspaceManifest(source, cwd) {
+    const loaded = loadSourceDocument(source, validateWorkspace, 'Workspace');
+    if (!loaded.ok)
+        return loaded;
+    const { value, yaml, lineCounter } = loaded.document;
+    const base = dirname(resolve(cwd, source.path));
+    const realBase = realpathSync(base);
+    const resolutionDiagnostics = [];
+    const categoryByPath = new Map();
+    const expand = (field, label, patterns) => [
+        ...new Set(patterns.flatMap((pattern, index) => {
+            const node = yaml.getIn([field, index], true);
+            const offset = typeof node === 'object' &&
+                node !== null &&
+                'range' in node &&
+                Array.isArray(node.range)
+                ? node.range[0]
+                : 0;
+            const position = lineCounter.linePos(offset);
+            const unsafe = isAbsolute(pattern) ||
+                /^[A-Za-z]:[\\/]/.test(pattern) ||
+                pattern.includes('\\') ||
+                pattern.split('/').includes('..');
+            if (unsafe) {
+                resolutionDiagnostics.push({
+                    severity: 'error',
+                    code: 'YM701',
+                    message: `Workspace ${label} pattern "${pattern}" must be a relative path beneath the manifest directory`,
+                    path: source.path,
+                    pointer: `/${field}/${index}`,
+                    line: position.line,
+                    column: position.col,
+                });
+                return [];
+            }
+            const matches = globSync(pattern, { cwd: base }).filter((path) => statSync(resolve(base, path)).isFile());
+            if (matches.length === 0) {
+                resolutionDiagnostics.push({
+                    severity: 'error',
+                    code: 'YM702',
+                    message: `Workspace ${label} pattern "${pattern}" matched no files`,
+                    path: source.path,
+                    pointer: `/${field}/${index}`,
+                    line: position.line,
+                    column: position.col,
+                });
+            }
+            const safeMatches = matches.filter((path) => {
+                const realMatch = realpathSync(resolve(base, path));
+                const withinBase = realMatch === realBase ||
+                    realMatch.startsWith(`${realBase}${sep}`);
+                if (!withinBase) {
+                    resolutionDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM701',
+                        message: `Workspace ${label} pattern "${pattern}" resolved outside the manifest directory`,
+                        path: source.path,
+                        pointer: `/${field}/${index}`,
+                        line: position.line,
+                        column: position.col,
+                    });
+                }
+                return withinBase;
+            });
+            return safeMatches.map((path) => {
+                const resolvedPath = relative(cwd, resolve(base, path))
+                    .split(sep)
+                    .join('/');
+                const physicalPath = realpathSync(resolve(base, path));
+                const previousLabel = categoryByPath.get(physicalPath);
+                if (previousLabel !== undefined && previousLabel !== label) {
+                    resolutionDiagnostics.push({
+                        severity: 'error',
+                        code: 'YM703',
+                        message: `Resolved file "${resolvedPath}" is declared as both ${previousLabel} and ${label}`,
+                        path: source.path,
+                        pointer: `/${field}/${index}`,
+                        line: position.line,
+                        column: position.col,
+                    });
+                }
+                else {
+                    categoryByPath.set(physicalPath, label);
+                }
+                return resolvedPath;
+            });
+        })),
+    ].sort();
+    const workspace = {
+        id: value.id,
+        documents: expand('documents', 'document', value.documents),
+        profiles: expand('profiles', 'profile', value.profiles),
+        projections: expand('projections', 'projection', value.projections),
+        adapterMappings: expand('adapterMappings', 'adapter mapping', value.adapterMappings),
+        evidence: expand('evidence', 'evidence', value.evidence ?? []),
+        contracts: expand('contracts', 'Core contract', value.contracts ?? []),
+    };
+    if (resolutionDiagnostics.length > 0) {
+        return {
+            ok: false,
+            diagnostics: resolutionDiagnostics.sort(diagnosticOrder),
+        };
+    }
+    return { ok: true, manifest: value, workspace };
+}

package/docs/CONSUMING-YARRAMATE.md

@@ -0,0 +1,145 @@
+# Consuming YarraMate
+
+Native documents in the consuming repository remain canonical. Consumer
+commands are documented as `yarramate ...` because the executable is the
+stable product interface regardless of how it was installed.
+
+## Published quick start
+
+Once the package and public repository are published:
+
+```sh
+npm install --global yarramate
+npx skills add yarrasys/yarramate --skill yarramate-architecture
+yarramate init .
+yarramate check .yarramate/workspace.yaml --json
+```
+
+The first command installs the engine executable. The second installs the
+canonical guided methodology for supported agent harnesses. They are separate:
+the skill orchestrates the CLI and does not contain its runtime.
+
+Projects that prefer a version-pinned development dependency may instead use:
+
+```sh
+npm install --save-dev yarramate
+npx yarramate init .
+```
+
+Inside package scripts and agent harness commands, the project-local
+executable is resolved as `yarramate`:
+
+```json
+{
+  "scripts": {
+    "architecture:check": "yarramate check .yarramate/workspace.yaml --json",
+    "architecture:reconcile": "yarramate reconcile .yarramate/workspace.yaml"
+  }
+}
+```
+
+The remainder of this guide uses the direct executable form.
+
+## Install a local artifact
+
+Before the first npm release, validate consumption through a local package
+artifact. From the YarraMate repository:
+
+```sh
+pnpm pack --pack-destination /tmp/yarramate-package
+```
+
+In a consuming project:
+
+```sh
+npm install --save-dev /tmp/yarramate-package/yarramate-0.1.0.tgz
+npx yarramate init .
+npx yarramate check .yarramate/workspace.yaml --json
+```
+
+The package contains the CLI runtime, normative schemas, and the canonical
+`yarramate-architecture` skill. It excludes the YarraMate repository
+self-model, source, tests, and fixtures.
+
+## Install the agent skill
+
+After the repository is public, use the agent-skills installer:
+
+```sh
+npx skills add yarrasys/yarramate --skill yarramate-architecture
+```
+
+The installed directory is a deployment of the canonical repository skill,
+not a harness-specific fork. Before publication, packed-artifact testing may
+instead expose the packaged copy through thin local links:
+
+```sh
+mkdir -p .agents/skills .claude/skills
+ln -s ../../node_modules/yarramate/skills/yarramate-architecture \
+  .agents/skills/yarramate-architecture
+ln -s ../../node_modules/yarramate/skills/yarramate-architecture \
+  .claude/skills/yarramate-architecture
+```
+
+Do not independently edit installed or linked copies. Changes to the
+methodology belong in the canonical repository skill.
+
+## Existing-project discovery
+
+Ask the harness to use `$yarramate-architecture` to discover the project.
+The skill will inspect repository evidence, propose native documents, and run:
+
+```sh
+yarramate check .yarramate/workspace.yaml --json
+yarramate evidence \
+  .yarramate/evidence/<evidence>.yaml \
+  .yarramate/workspace.yaml
+yarramate reconcile .yarramate/workspace.yaml
+yarramate context \
+  .yarramate/projections/<projection>.yaml \
+  .yarramate/workspace.yaml
+```
+
+Evidence remains distinct from declared intent. A generated proposal becomes
+canonical only through the consuming repository's normal Git review.
+
+## Architecture-first design
+
+Ask the harness to use `$yarramate-architecture` to design the solution before
+implementation. The skill records alternatives, target intent, and bounded
+implementation context, then runs:
+
+```sh
+yarramate check .yarramate/workspace.yaml --json
+yarramate context \
+  .yarramate/projections/<alternatives>.yaml \
+  .yarramate/workspace.yaml
+yarramate context \
+  .yarramate/projections/<target>.yaml \
+  .yarramate/workspace.yaml
+yarramate compare \
+  <baseline-state> <target-state> \
+  .yarramate/workspace.yaml
+```
+
+The CLI verifies deterministic correctness. It does not approve the design or
+require a complete model.
+
+## Optional Graphify evidence
+
+When Graphify has generated `graphify-out/graph.json`, an explicit subject
+mapping can produce a standard evidence overlay:
+
+```sh
+yarramate-graphify observe \
+  graphify-out/graph.json \
+  .yarramate/integrations/graphify/subject-mapping.yaml \
+  .yarramate/workspace.yaml \
+  --id repository-graphify \
+  --version 1.0 \
+  > .yarramate/evidence/graphify.yaml
+```
+
+Graphify extraction remains a separate installation and operation. The
+adapter observes only explicitly mapped nodes and never promotes them into
+canonical architecture.

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "yarramate",
+  "version": "0.1.0",
+  "description": "Tool-neutral semantic architecture engine and guided methodology",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yarrasys/yarramate.git"
+  },
+  "homepage": "https://github.com/yarrasys/yarramate#readme",
+  "bugs": {
+    "url": "https://github.com/yarrasys/yarramate/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "architecture",
+    "architecture-as-code",
+    "semantic-graph",
+    "cli",
+    "likec4"
+  ],
+  "files": [
+    "dist",
+    "schema",
+    "skills/yarramate-architecture",
+    "docs/CONSUMING-YARRAMATE.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter/likec4": {
+      "types": "./dist/adapters/likec4.d.ts",
+      "import": "./dist/adapters/likec4.js"
+    },
+    "./adapter/graphify": {
+      "types": "./dist/adapters/graphify-entry.d.ts",
+      "import": "./dist/adapters/graphify-entry.js"
+    },
+    "./schema/document": "./schema/yarramate-document.schema.json",
+    "./schema/profile": "./schema/yarramate-profile.schema.json",
+    "./schema/projection": "./schema/yarramate-projection.schema.json",
+    "./schema/projection-result": "./schema/yarramate-projection-result.schema.json",
+    "./schema/adapter-mapping": "./schema/yarramate-adapter-mapping.schema.json",
+    "./schema/check-result": "./schema/yarramate-check-result.schema.json",
+    "./schema/diagnostic-result": "./schema/yarramate-diagnostic-result.schema.json",
+    "./schema/likec4-diagnostic-result": "./schema/yarramate-likec4-diagnostic-result.schema.json",
+    "./schema/likec4-generated-project": "./schema/yarramate-likec4-generated-project.schema.json",
+    "./schema/likec4-generated-project-v2": "./schema/yarramate-likec4-generated-project-v2.schema.json",
+    "./schema/likec4-project": "./schema/yarramate-likec4-project.schema.json",
+    "./schema/likec4-kind-mapping": "./schema/yarramate-likec4-kind-mapping.schema.json",
+    "./schema/likec4-check-result": "./schema/yarramate-likec4-check-result.schema.json",
+    "./schema/state-comparison": "./schema/yarramate-state-comparison.schema.json",
+    "./schema/graph-v2": "./schema/yarramate-graph-v2.schema.json",
+    "./schema/workspace": "./schema/yarramate-workspace.schema.json",
+    "./schema/evidence": "./schema/yarramate-evidence.schema.json",
+    "./schema/evidence-report": "./schema/yarramate-evidence-report.schema.json",
+    "./schema/reconciliation-report": "./schema/yarramate-reconciliation-report.schema.json",
+    "./schema/core-contract": "./schema/yarramate-core-contract.schema.json",
+    "./skill/yarramate-architecture": "./skills/yarramate-architecture/SKILL.md"
+  },
+  "bin": {
+    "yarramate": "dist/cli.js",
+    "yarramate-likec4": "dist/adapters/likec4-cli.js",
+    "yarramate-graphify": "dist/adapters/graphify-cli.js"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "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",
+    "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",
+    "self:context": "pnpm build && node dist/cli.js context .yarramate/projections/current-engine.yaml .yarramate/workspace.yaml",
+    "self:view": "pnpm build && node dist/cli.js view .yarramate/projections/current-engine.yaml .yarramate/workspace.yaml",
+    "self:compare": "pnpm build && node dist/cli.js compare yarramate-evolution#native-foundation yarramate-evolution#state-foundation .yarramate/workspace.yaml",
+    "self:compare:contract": "pnpm build && node dist/cli.js compare yarramate-evolution#state-foundation yarramate-evolution#core-contract-foundation .yarramate/workspace.yaml",
+    "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",
+    "validate": "pnpm self:export:likec4 && likec4 validate --no-layout .yarramate-out/likec4",
+    "verify": "pnpm typecheck && pnpm test && pnpm self:check && pnpm validate",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "likec4": "^1.59.2",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.10"
+  }
+}

package/schema/yarramate-adapter-mapping.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/adapter-mapping/v1",
+  "title": "YarraMate adapter mapping",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "id", "version", "adapter", "mappings"],
+  "properties": {
+    "format": {
+      "const": "yarramate/adapter-mapping/v1"
+    },
+    "id": {
+      "$ref": "#/$defs/id"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "adapter": {
+      "$ref": "#/$defs/id"
+    },
+    "mappings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/mapping"
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "qualifiedSubject": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*#[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "nonEmptyText": {
+      "type": "string",
+      "minLength": 1
+    },
+    "mapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["native", "external", "type"],
+      "properties": {
+        "native": {
+          "$ref": "#/$defs/qualifiedSubject"
+        },
+        "external": {
+          "$ref": "#/$defs/nonEmptyText"
+        },
+        "type": {
+          "enum": ["concept", "relationship"]
+        }
+      }
+    }
+  }
+}

package/schema/yarramate-check-result.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/check-result/v1",
+  "title": "YarraMate check result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "ok", "diagnostics"],
+  "properties": {
+    "format": {
+      "const": "yarramate/check-result/v1"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/diagnostic"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "ok": {
+            "const": true
+          }
+        },
+        "required": ["ok"]
+      },
+      "then": {
+        "properties": {
+          "diagnostics": {
+            "maxItems": 0
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "diagnostics": {
+            "minItems": 1
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "severity",
+        "code",
+        "message",
+        "path",
+        "pointer",
+        "line",
+        "column"
+      ],
+      "properties": {
+        "severity": {
+          "const": "error"
+        },
+        "code": {
+          "type": "string",
+          "pattern": "^YM[0-9]{3}$"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pointer": {
+          "type": "string",
+          "pattern": "^/"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/core-contract/v1",
+  "title": "YarraMate Core contract manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "id",
+    "version",
+    "packageManifest",
+    "formats",
+    "commands",
+    "guarantees",
+    "exclusions"
+  ],
+  "properties": {
+    "format": {
+      "const": "yarramate/core-contract/v1"
+    },
+    "id": {
+      "$ref": "#/$defs/id"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "packageManifest": {
+      "$ref": "#/$defs/repositoryPath"
+    },
+    "formats": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "schema", "packageExport"],
+        "properties": {
+          "id": {
+            "$ref": "#/$defs/formatIdentity"
+          },
+          "schema": {
+            "$ref": "#/$defs/repositoryPath"
+          },
+          "packageExport": {
+            "type": "string",
+            "pattern": "^\\./schema/[a-z][a-z0-9-]*$"
+          }
+        }
+      }
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "binary"],
+        "properties": {
+          "name": {
+            "enum": [
+              "init",
+              "add",
+              "connect",
+              "check",
+              "compile",
+              "view",
+              "context",
+              "compare",
+              "evidence",
+              "reconcile"
+            ]
+          },
+          "binary": {
+            "const": "yarramate"
+          },
+          "machineFormat": {
+            "$ref": "#/$defs/formatIdentity"
+          }
+        }
+      }
+    },
+    "guarantees": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "adapter-independent-core",
+          "canonical-graph-serialization",
+          "correctness-not-completeness",
+          "deterministic-diagnostic-order",
+          "git-native-governance",
+          "globally-qualified-compiled-identities",
+          "no-partial-graph-on-error",
+          "portable-projection-selectors",
+          "source-located-diagnostics"
+        ]
+      }
+    },
+    "exclusions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "adapter-runtime-dependency",
+          "approval-workflow",
+          "architectural-completeness",
+          "architectural-quality",
+          "automatic-discovery",
+          "external-language-conformance",
+          "state-scoped-claim-values"
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "formatIdentity": {
+      "type": "string",
+      "pattern": "^yarramate/[a-z][a-z0-9-]*(?:/[a-z0-9]+)?$"
+    },
+    "repositoryPath": {
+      "type": "string",
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+    }
+  }
+}