yarramate 0.6.0 → 0.7.0

package/docs/CONSUMING-YARRAMATE.md

@@ -63,7 +63,19 @@ self-model, source, tests, and fixtures.
 
 ## Install the agent skill
 
-After the repository is public, use the agent-skills installer:
+For Claude Code, the repository is its own plugin marketplace:
+
+```sh
+/plugin marketplace add yarrasys/yarramate
+/plugin install yarramate-architecture@yarramate
+```
+
+The marketplace entry points at `skills/yarramate-architecture` in this
+repository, so the installed plugin is the canonical skill rather than a
+copy. It declares no version, taking its version from the commit it was
+installed from.
+
+For other harnesses, use the agent-skills installer:
 
 ```sh
 npx skills add yarrasys/yarramate --skill yarramate-architecture
@@ -91,15 +103,13 @@ 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
+yarramate ask .yarramate/workspace.yaml \
+  .yarramate/projections/<projection>.yaml
 ```
 
+Evidence overlays declared in the manifest are evaluated by `reconcile`
+(and gated by `check --strict`) rather than through a separate command.
 Evidence remains distinct from declared intent. A generated proposal becomes
 canonical only through the consuming repository's normal Git review.
 
@@ -111,15 +121,12 @@ 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
+yarramate ask .yarramate/workspace.yaml \
+  .yarramate/projections/<alternatives>.yaml
+yarramate ask .yarramate/workspace.yaml \
+  .yarramate/projections/<target>.yaml
+yarramate ask .yarramate/workspace.yaml \
+  --compare <baseline-state> <target-state>
 ```
 
 The CLI verifies deterministic correctness. It does not approve the design or
@@ -158,11 +165,11 @@ Harnesses that load MCP servers can connect the bundled read-only adapter:
 }
 ```
 
-It exposes `yarramate_status`, `yarramate_check`, `yarramate_reconcile`,
-and `yarramate_context` (projection path or ad-hoc subjects, with an
-optional token budget). Every tool call executes the same stable CLI in
-the server's working directory; nothing mutates native documents, and
-authoring stays with the CLI and Git review.
+It exposes `yarramate_ask` (orientation, free text, subject ids, or a
+projection path, with an optional token budget), `yarramate_design`,
+`yarramate_check`, and `yarramate_reconcile`. Every tool call executes the
+same stable CLI in the server's working directory; nothing mutates native
+documents, and authoring stays with the CLI and Git review.
 
 ## Continuous drift signal in CI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,7 @@
     "dist",
     "assets/likec4",
     "schema",
+    "catalogues",
     "skills/yarramate-architecture",
     "docs/CONSUMING-YARRAMATE.md"
   ],
@@ -58,15 +59,19 @@
     "./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/status-result": "./schema/yarramate-status-result.schema.json",
-    "./schema/next-result": "./schema/yarramate-next-result.schema.json",
+    "./schema/question-catalogue": "./schema/yarramate-question-catalogue.schema.json",
+    "./schema/interrogation-report": "./schema/yarramate-interrogation-report.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"
+    "./skill/yarramate-architecture": "./skills/yarramate-architecture/SKILL.md",
+    "./schema/operations": "./schema/yarramate-operations.schema.json",
+    "./schema/apply-result": "./schema/yarramate-apply-result.schema.json",
+    "./schema/design-step": "./schema/yarramate-design-step.schema.json",
+    "./schema/ask-result": "./schema/yarramate-ask-result.schema.json"
   },
   "bin": {
     "yarramate": "dist/cli.js",
@@ -85,13 +90,10 @@
     "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",
-    "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:ask": "pnpm build && node dist/cli.js ask .yarramate/workspace.yaml",
+    "self:export:graph": "pnpm build && node dist/cli.js export graph .yarramate/workspace.yaml",
+    "self:export:markdown": "pnpm build && node dist/cli.js export markdown .yarramate/projections/current-engine.yaml .yarramate/workspace.yaml",
+    "self:compare": "pnpm build && node dist/cli.js ask .yarramate/workspace.yaml --compare yarramate-evolution#native-foundation yarramate-evolution#state-foundation",
     "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/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",

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

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarrasys.dev/schema/yarramate-apply-result.schema.json",
+  "title": "YarraMate apply result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "workspace", "applied", "documents"],
+  "properties": {
+    "format": { "const": "yarramate/apply-result/v1" },
+    "workspace": { "type": "string", "minLength": 1 },
+    "applied": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "addedConcepts",
+        "addedRelationships",
+        "updatedConcepts",
+        "updatedRelationships"
+      ],
+      "properties": {
+        "addedConcepts": { "type": "integer", "minimum": 0 },
+        "addedRelationships": { "type": "integer", "minimum": 0 },
+        "updatedConcepts": { "type": "integer", "minimum": 0 },
+        "updatedRelationships": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "documents": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

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

@@ -0,0 +1,391 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarrasys.dev/schema/yarramate-ask-result.schema.json",
+  "title": "YarraMate ask result",
+  "description": "One envelope for every consumed-now read: orientation, roster, slice, advice, next, open questions, and state comparison, discriminated by mode.",
+  "type": "object",
+  "required": ["format", "workspace", "mode"],
+  "properties": {
+    "format": {
+      "const": "yarramate/ask-result/v1"
+    },
+    "workspace": {
+      "type": "string",
+      "minLength": 1
+    },
+    "mode": {
+      "enum": [
+        "orientation",
+        "roster",
+        "slice",
+        "advice",
+        "next",
+        "open",
+        "compare",
+        "kinds"
+      ]
+    }
+  },
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["mode", "ok", "check", "backlog"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "orientation" },
+        "ok": { "type": "boolean" },
+        "check": {
+          "type": "object",
+          "required": ["ok", "diagnostics"],
+          "properties": {
+            "ok": { "type": "boolean" },
+            "diagnostics": { "type": "array" },
+            "counted": {
+              "type": "object",
+              "required": [
+                "documents",
+                "concepts",
+                "relationships",
+                "states"
+              ],
+              "properties": {
+                "documents": { "type": "integer" },
+                "concepts": { "type": "integer" },
+                "relationships": { "type": "integer" },
+                "states": { "type": "integer" }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "reconciliation": {
+          "$ref": "#/$defs/reconciliationSummary"
+        },
+        "design": {
+          "type": "object",
+          "required": ["catalogue", "open"],
+          "properties": {
+            "catalogue": { "type": "string", "minLength": 1 },
+            "open": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "backlog": {
+          "type": "object",
+          "required": ["planned", "current", "retired"],
+          "properties": {
+            "planned": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/nextSubject" }
+            },
+            "current": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/conceptEntry" }
+            },
+            "retired": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/conceptEntry" }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["mode", "total", "subjects"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "roster" },
+        "total": { "type": "integer", "minimum": 0 },
+        "subjects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/conceptEntry" }
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["mode", "addressing", "result"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "slice" },
+        "addressing": {
+          "enum": ["free-text", "subjects", "projection"]
+        },
+        "topic": { "type": "string", "minLength": 1 },
+        "seeds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "matched": { "type": "integer", "minimum": 0 },
+        "result": { "$ref": "#/$defs/projectionResult" }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": [
+        "mode",
+        "topic",
+        "seeds",
+        "matched",
+        "slice",
+        "openQuestions"
+      ],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "advice" },
+        "topic": { "type": "string", "minLength": 1 },
+        "seeds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "matched": { "type": "integer", "minimum": 0 },
+        "slice": { "type": "string", "minLength": 1 },
+        "openQuestions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["wave", "id", "authority", "question", "materiality"],
+            "properties": {
+              "wave": { "type": "string", "minLength": 1 },
+              "id": { "type": "string", "minLength": 1 },
+              "authority": { "enum": ["human", "agent", "either"] },
+              "question": { "type": "string", "minLength": 1 },
+              "materiality": { "type": "string", "minLength": 1 },
+              "subject": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          }
+        },
+        "reconciliation": {
+          "type": "object",
+          "required": ["summary", "findings"],
+          "properties": {
+            "summary": { "$ref": "#/$defs/reconciliationSummary" },
+            "findings": { "type": "array" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["mode", "subjects"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "next" },
+        "subjects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/nextSubject" }
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["mode", "report"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "open" },
+        "report": {
+          "type": "object",
+          "required": ["format", "workspace", "catalogue", "summary", "waves"],
+          "properties": {
+            "format": { "const": "yarramate/interrogation-report/v1" },
+            "workspace": { "type": "string" },
+            "catalogue": { "type": "string" },
+            "summary": { "type": "object" },
+            "waves": { "type": "array" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["mode", "conceptKinds", "relationshipKinds", "extensions"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "kinds" },
+        "conceptKinds": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "layer", "aspect"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "name": { "type": "string", "minLength": 1 },
+              "layer": { "type": "string", "minLength": 1 },
+              "aspect": { "type": "string", "minLength": 1 },
+              "inspiredBy": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "relationshipKinds": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "intent"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "intent": { "type": "string", "minLength": 1 },
+              "sourceAspects": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "targetAspects": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "repair": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "extensions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "type", "lineage"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "type": { "enum": ["concept", "relationship"] },
+              "lineage": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["mode", "comparison"],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": { "const": "compare" },
+        "comparison": {
+          "type": "object",
+          "required": ["format", "from", "to", "added", "removed", "retained"],
+          "properties": {
+            "format": { "const": "yarramate/state-comparison/v1" },
+            "from": { "type": "string" },
+            "to": { "type": "string" },
+            "added": { "type": "array" },
+            "removed": { "type": "array" },
+            "retained": { "type": "array" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  ],
+  "$defs": {
+    "conceptEntry": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "status": { "enum": ["planned", "current", "retired"] },
+        "description": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "nextSubject": {
+      "type": "object",
+      "required": ["id", "kind", "dependsOn", "requiredBy", "evidence"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "dependsOn": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "requiredBy": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "evidence": {
+          "type": "object",
+          "required": [
+            "observations",
+            "confirmed",
+            "contradicted",
+            "unknown",
+            "notObserved"
+          ],
+          "properties": {
+            "observations": { "type": "integer" },
+            "confirmed": { "type": "integer" },
+            "contradicted": { "type": "integer" },
+            "unknown": { "type": "integer" },
+            "notObserved": { "type": "integer" }
+          },
+          "additionalProperties": false
+        },
+        "cycle": { "const": true }
+      },
+      "additionalProperties": false
+    },
+    "projectionResult": {
+      "type": "object",
+      "required": ["format", "projection", "documents", "subjects", "claims"],
+      "properties": {
+        "format": { "const": "yarramate/projection-result/v1" },
+        "projection": { "type": "string" },
+        "presentation": { "type": "object" },
+        "documents": { "type": "array" },
+        "subjects": { "type": "array" },
+        "claims": { "type": "array" }
+      },
+      "additionalProperties": false
+    },
+    "reconciliationSummary": {
+      "type": "object",
+      "required": [
+        "evidenceDocuments",
+        "observations",
+        "confirmed",
+        "findings",
+        "contradicted",
+        "unknown",
+        "notObserved",
+        "subjectsWithoutEvidence"
+      ],
+      "properties": {
+        "evidenceDocuments": { "type": "integer" },
+        "observations": { "type": "integer" },
+        "confirmed": { "type": "integer" },
+        "findings": { "type": "integer" },
+        "contradicted": { "type": "integer" },
+        "unknown": { "type": "integer" },
+        "notObserved": { "type": "integer" },
+        "subjectsWithoutEvidence": { "type": "integer" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -67,18 +67,12 @@
           "name": {
             "enum": [
               "init",
-              "add",
-              "connect",
-              "new",
-              "next",
+              "design",
+              "apply",
+              "ask",
               "check",
-              "status",
-              "compile",
-              "view",
-              "context",
-              "compare",
-              "evidence",
-              "reconcile"
+              "reconcile",
+              "export"
             ]
           },
           "binary": {