yarramate 0.3.3 → 0.5.0

package/skills/yarramate-architecture/SKILL.md

@@ -22,6 +22,15 @@ 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
@@ -58,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:
@@ -70,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
@@ -105,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
@@ -116,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
@@ -160,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,
@@ -172,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
 ```