yarramate 0.3.2 → 0.4.0

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

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/status-result/v1",
+  "title": "YarraMate workspace status result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "workspace",
+    "ok",
+    "check",
+    "inventory"
+  ],
+  "properties": {
+    "format": {
+      "const": "yarramate/status-result/v1"
+    },
+    "workspace": {
+      "type": "string",
+      "minLength": 1
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ok",
+        "diagnostics"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/diagnostic"
+          }
+        },
+        "counted": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "documents",
+            "concepts",
+            "relationships",
+            "states"
+          ],
+          "properties": {
+            "documents": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "concepts": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "relationships": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "states": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "reconciliation": {
+      "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
+        }
+      }
+    },
+    "inventory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "documents",
+        "profiles",
+        "states",
+        "projections",
+        "evidence",
+        "adapterMappings",
+        "contracts"
+      ],
+      "properties": {
+        "documents": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "path"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "profiles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "states": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "type"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "type": {
+                "enum": [
+                  "baseline",
+                  "transition",
+                  "target"
+                ]
+              }
+            }
+          }
+        },
+        "projections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "path"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "adapterMappings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "contracts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 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/skills/yarramate-architecture/SKILL.md

@@ -1,11 +1,11 @@
 ---
 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.
+description: Discover, design, or maintain repository architecture 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, evolve a model that already validates, rename or replace semantic subjects safely, 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:
+Use one repository-native lifecycle for discovery, design, and maintenance:
 
 ```text
 evidence or design conversation
@@ -22,11 +22,23 @@ automatically.
 
 ## Choose the journey
 
+When a workspace already exists, orient first with one call before choosing:
+
+```sh
+yarramate status <workspace.yaml> --json
+```
+
+It reports the check verdict, the reconciliation summary, and a titled
+inventory of documents, states, projections, evidence, and contracts.
+
 - 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,
+- A validating native model must change: follow **Maintain an existing
+  model**.
+- Declared architecture and implementation both exist but no model change is
+  requested: begin with discovery,
   preserve the declared model, then report supported, contradicted, unknown,
   and unobserved claims without silently rewriting it.
 
@@ -67,6 +79,7 @@ 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 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
 ```
@@ -112,6 +125,7 @@ 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 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
 ```
@@ -125,10 +139,64 @@ yarramate-likec4 export-project .yarramate/integrations/likec4/project.yaml .yar
    implementation context. Do not generate code until the requested design
    decision is reviewable.
 
+## Maintain an existing model
+
+Use this journey for a deliberate change to a model that already passes its
+checks, including a renamed subject, resolved gap, changed relationship, or
+retired concept.
+
+1. Discover the authored layout before assuming paths:
+   - read the workspace `documents`, `projections`, `adapterMappings`, and
+     `evidence` entries;
+   - locate any `yarramate/likec4-project/v1` document and follow its `mapping`
+     field;
+   - treat paths shown below as examples, not required repository layout.
+   Discover the repository’s authored paths instead of assuming these examples.
+2. Establish a passing baseline with Core and every configured read-only
+   adapter check. If the baseline already fails, separate those pre-existing
+   diagnostics from the requested maintenance change.
+3. Before changing an identity, search its local and globally qualified forms
+   across every workspace input. Account for:
+   - `references[].ref` citations;
+   - relationship `from` and `to` endpoints;
+   - evidence `subject` entries and stable claim targets;
+   - adapter mapping `native` entries;
+   - projection selectors, architecture states, ownership, and constraints.
+4. Make the smallest coherent edit and update all referring authored inputs.
+   Do not rewrite unrelated architectural intent.
+5. Run the read-only checks before any repair command so drift remains
+   observable:
+
+```sh
+yarramate check .yarramate/workspace.yaml --json
+yarramate-likec4 check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml
+```
+
+6. If the adapter check reports intended mapping drift, repair it locally,
+   inspect the tracked diff, then verify again. Use `--prune` only after
+   confirming that stale native subjects were intentionally renamed or
+   removed:
+
+```sh
+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
+```
+
+7. Require both configured read-only checks to exit successfully after the
+   edit. The maintained model must pass before handoff. Report changed
+   identities, updated dependants, mapping repairs, generated output, and any
+   intentionally deferred architecture work.
+
 ## Correctness and authority
 
 - Treat `check` as deterministic correctness, never as architecture approval,
   completeness, or quality scoring.
+- A repair command cannot serve as verification. Run read-only adapter checks
+  before `map --sync`, use sync only while authoring, and never put sync in a
+  CI verification gate.
 - Keep LikeC4 optional. Default to visual output for these guided journeys,
   but respect an explicit request for tool-neutral semantic output only.
 - Keep adapter fields outside native documents.

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

@@ -1,4 +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."
+  short_description: "Discover, design, and maintain architecture"
+  default_prompt: "Use $yarramate-architecture to discover, design, or safely maintain this project architecture."

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

@@ -60,3 +60,11 @@ Design is minimally useful when:
 - intended projections are rendered through a current LikeC4 project;
 - rendering coverage gaps are stated, including intentional omissions;
 - missing detail is visible without becoming a Core correctness error.
+
+Maintenance is complete only when:
+
+- all references to a changed identity were found before editing;
+- native documents and configured adapters pass their read-only checks;
+- any mapping sync or prune was reviewed as an authored Git change;
+- generated views are current;
+- changed identities and updated dependants are reported at handoff.

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

@@ -15,8 +15,10 @@ adapterMappings: []
 evidence: [evidence/*.yaml]
 ```
 
-Paths are relative to the manifest. Keep canonical inputs under `.yarramate/`
-and generated artifacts under `.yarramate-out/`.
+Paths are relative to the manifest. `.yarramate/` for canonical inputs and
+`.yarramate-out/` for generated artifacts are recommended examples, not fixed
+CLI paths. In an existing repository, read its workspace and project documents
+and preserve the authored layout.
 
 ## Native document
 
@@ -196,6 +198,9 @@ Give every ordered flow its own focused projection and dynamic view. A dynamic
 view takes its title and description from its projection; reusing one broad
 projection for several flows makes their rendered identities ambiguous.
 Ensure every intended projection is listed in the project.
+In an existing repository, locate the project by its
+`yarramate/likec4-project/v1` format and follow its `mapping` field instead of
+assuming the example paths below.
 
 Start the referenced mapping as a valid empty mapping, then let sync populate
 it:
@@ -231,6 +236,10 @@ yarramate view <projection.yaml> .yarramate/workspace.yaml
 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 \
+  --json \
+  .yarramate/workspace.yaml
 yarramate-likec4 map --sync \
   .yarramate/integrations/likec4/subject-mapping.yaml \
   .yarramate/workspace.yaml
@@ -240,6 +249,12 @@ yarramate-likec4 export-project \
   .yarramate/workspace.yaml
 ```
 
+`yarramate-likec4 check` is read-only verification and belongs in CI.
+Run it before sync when checking an existing mapping so missing or stale
+entries remain observable. `map --sync [--prune]` is an authoring repair: it
+mutates a tracked mapping, so review and commit its diff. Never use a repair
+command as a CI gate.
+
 Sync preserves and reports mappings for native subjects that no longer exist.
 After confirming that those subjects were intentionally removed or renamed,
 delete the stale entries while adding missing mappings with: