yarramate 0.1.0

package/schema/yarramate-projection.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/projection/v1",
+  "title": "YarraMate semantic projection",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "id", "version", "query"],
+  "properties": {
+    "format": {
+      "const": "yarramate/projection/v1"
+    },
+    "id": {
+      "$ref": "#/$defs/id"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "query": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "subjects": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/subjectIdentity"
+          }
+        },
+        "documents": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "kinds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/qualifiedKind"
+          }
+        },
+        "statuses": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": ["planned", "current", "retired"]
+          }
+        },
+        "states": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/subjectIdentity"
+          }
+        },
+        "owners": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/subjectIdentity"
+          }
+        },
+        "constraints": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/subjectIdentity"
+          }
+        },
+        "relationshipKinds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/qualifiedKind"
+          }
+        },
+        "kindMatching": {
+          "enum": ["exact", "descendants"]
+        },
+        "relationships": {
+          "enum": ["between", "connected", "none"]
+        },
+        "isolatedConcepts": {
+          "enum": ["include", "exclude"]
+        }
+      }
+    },
+    "presentation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "$ref": "#/$defs/nonEmptyText"
+        },
+        "description": {
+          "$ref": "#/$defs/nonEmptyText"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "qualifiedKind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*(?:/[a-z][a-z0-9-]*)+@[0-9]+\\.[0-9]+#[a-z][A-Za-z0-9-]*$"
+    },
+    "subjectIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*#[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "nonEmptyText": {
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}

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

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/reconciliation-report/v1",
+  "title": "YarraMate reconciliation report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "workspace", "summary", "findings"],
+  "properties": {
+    "format": { "const": "yarramate/reconciliation-report/v1" },
+    "workspace": { "$ref": "#/$defs/id" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "evidenceDocuments",
+        "observations",
+        "confirmed",
+        "findings",
+        "contradicted",
+        "unknown",
+        "notObserved"
+      ],
+      "properties": {
+        "evidenceDocuments": { "type": "integer", "minimum": 0 },
+        "observations": { "type": "integer", "minimum": 0 },
+        "confirmed": { "type": "integer", "minimum": 0 },
+        "findings": { "type": "integer", "minimum": 0 },
+        "contradicted": { "type": "integer", "minimum": 0 },
+        "unknown": { "type": "integer", "minimum": 0 },
+        "notObserved": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "qualifiedIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*#[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:~[a-z][a-z0-9-]*)?$"
+    },
+    "evidenceIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*@[0-9]+\\.[0-9]+$"
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": { "enum": ["subject", "claim"] },
+        "id": { "$ref": "#/$defs/qualifiedIdentity" }
+      }
+    },
+    "evidenceLocator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uri"],
+      "properties": {
+        "uri": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target",
+        "result",
+        "provider",
+        "evidenceDocument",
+        "evidence"
+      ],
+      "properties": {
+        "target": { "$ref": "#/$defs/target" },
+        "result": {
+          "enum": ["contradicted", "unknown", "not-observed"]
+        },
+        "provider": { "$ref": "#/$defs/id" },
+        "evidenceDocument": { "$ref": "#/$defs/evidenceIdentity" },
+        "evidence": { "$ref": "#/$defs/evidenceLocator" }
+      }
+    }
+  }
+}

package/schema/yarramate-state-comparison.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/state-comparison/v1",
+  "title": "YarraMate architecture-state comparison",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "from",
+    "to",
+    "added",
+    "removed",
+    "retained"
+  ],
+  "properties": {
+    "format": {
+      "const": "yarramate/state-comparison/v1"
+    },
+    "from": {
+      "$ref": "#/$defs/subjectIdentity"
+    },
+    "to": {
+      "$ref": "#/$defs/subjectIdentity"
+    },
+    "added": {
+      "$ref": "#/$defs/subjects"
+    },
+    "removed": {
+      "$ref": "#/$defs/subjects"
+    },
+    "retained": {
+      "$ref": "#/$defs/subjects"
+    }
+  },
+  "$defs": {
+    "subjectIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*#[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/subjectIdentity"
+        },
+        "type": {
+          "enum": ["concept", "relationship"]
+        }
+      }
+    },
+    "subjects": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/subject"
+      }
+    }
+  }
+}

package/schema/yarramate-workspace.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/workspace/v1",
+  "title": "YarraMate workspace manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "id",
+    "documents",
+    "profiles",
+    "projections",
+    "adapterMappings"
+  ],
+  "properties": {
+    "format": {
+      "const": "yarramate/workspace/v1"
+    },
+    "id": {
+      "$ref": "#/$defs/id"
+    },
+    "documents": {
+      "$ref": "#/$defs/patterns"
+    },
+    "profiles": {
+      "$ref": "#/$defs/patterns"
+    },
+    "projections": {
+      "$ref": "#/$defs/patterns"
+    },
+    "adapterMappings": {
+      "$ref": "#/$defs/patterns"
+    },
+    "evidence": {
+      "$ref": "#/$defs/patterns"
+    },
+    "contracts": {
+      "$ref": "#/$defs/patterns"
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "patterns": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}

package/skills/yarramate-architecture/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: yarramate-architecture
+description: Discover architecture in an existing repository or design a new solution before implementation using native YarraMate documents and the stable CLI. Use when an agent needs to map a codebase, propose an evidence-backed architecture model, brainstorm solution alternatives, define current/transition/target architecture, reconcile intent with evidence, or provide bounded architecture context to implementation work.
+---
+
+# YarraMate architecture
+
+Use one repository-native lifecycle for discovery and design:
+
+```text
+evidence or design conversation
+  -> native-document proposal
+  -> deterministic CLI checks and projections
+  -> Git review
+  -> declared architectural intent
+  -> later evidence and reconciliation
+```
+
+Native YarraMate documents are canonical. Generated graphs, Markdown, JSON
+context, and diagrams are derived. Never promote evidence into declared intent
+automatically.
+
+## Choose the journey
+
+- Existing implementation is the starting point: follow **Discover an
+  existing project**.
+- Intent and a not-yet-built solution are the starting point: follow **Design
+  a new solution**.
+- Declared architecture and implementation both exist: begin with discovery,
+  preserve the declared model, then report supported, contradicted, unknown,
+  and unobserved claims without silently rewriting it.
+
+Read [references/journey-checklists.md](references/journey-checklists.md) for
+the minimum evidence and design questions. Read
+[references/native-authoring.md](references/native-authoring.md) when native
+document, projection, evidence, or architecture-state syntax is needed.
+
+## Discover an existing project
+
+1. Inspect repository instructions, structure, manifests, dependencies,
+   entrypoints, tests, deployment files, and existing architecture sources.
+2. If no workspace exists, run `yarramate init .`. Do not overwrite an
+   existing `.yarramate/`.
+3. Separate direct observations from architectural interpretation. Record the
+   inspected repository locations before proposing semantic concepts.
+4. Propose the smallest useful native model:
+   - stable responsibilities and externally meaningful services;
+   - principal information and dependencies;
+   - significant actors, constraints, and ownership only when supported;
+   - current state by default; do not infer target intent from code.
+5. Prefer `yarramate add` and `yarramate connect` for simple additions. Edit
+   YAML directly when states or several related declarations make that clearer.
+6. Add an evidence overlay only for existing subjects or stable claim IDs.
+   Evidence supports or challenges the proposal; it is not a second model.
+7. Add one focused projection that answers the repository-orientation
+   question.
+8. 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 view .yarramate/projections/<projection>.yaml .yarramate/workspace.yaml
+```
+
+9. Present observations, reconciliation findings, interpretive proposals,
+   evidence gaps, and Git diff separately. Do not claim completeness from a
+   green check and do not automatically turn findings into edits.
+
+## Design a new solution
+
+1. Capture the decision context before components:
+   - drivers, stakeholders, desired outcomes, and constraints;
+   - material assumptions and unresolved questions;
+   - boundaries and responsibilities.
+2. Model only materially different alternatives. Use stable concepts and
+   relationships; do not hide an alternative in free-form metadata.
+3. Record the selected approach through explicit relationships and focused
+   projections. Use architecture states when baseline, transition, or target
+   presence matters; do not misuse lifecycle status as a decision verdict.
+4. Add the principal services, components, information, responsibilities, and
+   dependencies required to begin implementation. Partial detail is valid.
+5. Create:
+   - an alternatives projection for the decision;
+   - a bounded target projection for implementation agents.
+6. Run:
+
+```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 view .yarramate/projections/<target>.yaml .yarramate/workspace.yaml
+yarramate compare <baseline-state> <target-state> .yarramate/workspace.yaml
+```
+
+7. Present alternatives, selected intent, unresolved decisions, and bounded
+   implementation context. Do not generate code until the requested design
+   decision is reviewable.
+
+## Correctness and authority
+
+- Treat `check` as deterministic correctness, never as architecture approval,
+  completeness, or quality scoring.
+- Keep adapter fields outside native documents.
+- Use globally qualified identities at CLI and projection boundaries.
+- Preserve source-located diagnostics verbatim when asking the author to fix
+  input.
+- Let Git provide authorship, review, history, and acceptance.
+- Stop for user direction when a choice changes the solution boundary,
+  selected alternative, authoritative constraint, or product contract.
+- Do not introduce a database, server, approval workflow, or harness-specific
+  canonical format.
+
+## Handoff
+
+Report:
+
+- journey used and question answered;
+- canonical files proposed or changed;
+- observations and evidence results;
+- projections produced;
+- validation commands and outcomes;
+- unresolved architectural decisions;
+- whether changes are merely proposed or already accepted in Git.
+
+If YarraMate itself produced confusing behaviour, blocked adoption, lacked a
+needed capability, or required an awkward workaround, identify that separately
+as product feedback and direct the user to:
+
+`https://github.com/yarrasys/yarramate/issues/new`
+
+Issues may contain incomplete ideas or early observations; a proposed fix is
+not required. Do not create an external issue automatically unless the user
+asks you to.

package/skills/yarramate-architecture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YarraMate Architecture"
+  short_description: "Discover and design repository architecture"
+  default_prompt: "Use $yarramate-architecture to discover or design this project architecture with native YarraMate documents."

package/skills/yarramate-architecture/references/journey-checklists.md

@@ -0,0 +1,57 @@
+# Journey checklists
+
+## Discovery evidence
+
+Inspect only what materially supports the proposed architecture:
+
+- repository instructions and package/workspace manifests;
+- executable entrypoints and public interfaces;
+- stable modules and responsibility boundaries;
+- persisted or exchanged information;
+- external services and runtime/deployment configuration;
+- tests that demonstrate significant behavior;
+- ownership or constraints explicitly present in repository sources.
+
+Distinguish:
+
+- **observed** — directly supported by a locator;
+- **proposed interpretation** — semantic meaning inferred for review;
+- **unknown** — evidence is insufficient;
+- **declared intent** — already accepted in native documents.
+
+Do not infer organizational ownership from Git authorship, target intent from
+unfinished code, or architectural importance from file size.
+
+## Design questions
+
+Ask only questions that can materially change the architecture:
+
+- What outcome and driver justify the solution?
+- Which constraints are non-negotiable?
+- Who or what consumes the solution?
+- What responsibility belongs inside versus outside the boundary?
+- Which information must be owned, persisted, or exchanged?
+- Which alternatives differ in boundaries, responsibility, dependency, or
+  operational characteristics?
+- What makes an alternative selected, rejected, or still unresolved?
+- What must exist in the initial target for implementation to begin?
+
+Avoid demanding a complete catalogue before a useful target can be reviewed.
+
+## Completion signals
+
+Discovery is minimally useful when:
+
+- native documents pass `yarramate check`;
+- significant proposed subjects have traceable observations or are explicitly
+  identified as interpretation;
+- a focused projection gives an agent useful repository context;
+- evidence has not been promoted automatically.
+
+Design is minimally useful when:
+
+- drivers and constraints are visible;
+- material alternatives remain reviewable;
+- the selected target has explicit boundaries and relationships;
+- a bounded target projection can guide implementation;
+- missing detail is visible without becoming a Core correctness error.