yarramate 0.6.0 → 0.7.0

package/schema/yarramate-question-catalogue.schema.json

@@ -0,0 +1,431 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/question-catalogue/v1",
+  "title": "YarraMate question catalogue",
+  "description": "A versioned, opinionated catalogue of enrichment questions. Each question binds a deterministic trigger evaluated against a compiled graph-v2 workspace: the question is open wherever its trigger matches and closed when it no longer matches. Interview state is recomputed, never stored.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "id",
+    "version",
+    "profile",
+    "waves",
+    "questions"
+  ],
+  "properties": {
+    "format": {
+      "const": "yarramate/question-catalogue/v1"
+    },
+    "id": {
+      "$ref": "#/$defs/id"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "profile": {
+      "description": "Profile identity whose vocabulary the triggers are expressed against.",
+      "$ref": "#/$defs/profileIdentity"
+    },
+    "presentation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title"
+      ],
+      "properties": {
+        "title": {
+          "$ref": "#/$defs/nonEmptyText"
+        },
+        "description": {
+          "$ref": "#/$defs/nonEmptyText"
+        }
+      }
+    },
+    "waves": {
+      "description": "Ordered interview phases. Array order is interview order. The wave taxonomy is catalogue opinion, not engine semantics.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "name"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "#/$defs/id"
+          },
+          "name": {
+            "$ref": "#/$defs/nonEmptyText"
+          },
+          "description": {
+            "$ref": "#/$defs/nonEmptyText"
+          }
+        }
+      }
+    },
+    "questions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/question"
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "nonEmptyText": {
+      "type": "string",
+      "minLength": 1
+    },
+    "profileIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9/-]*@[0-9][0-9A-Za-z.-]*$"
+    },
+    "catalogueIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9/-]*@[0-9][0-9A-Za-z.-]*$"
+    },
+    "qualifiedKind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9/-]*@[0-9][0-9A-Za-z.-]*#[A-Za-z][A-Za-z0-9-]*$"
+    },
+    "claimPredicate": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9/@.#-]*$"
+    },
+    "subjectSelector": {
+      "description": "Which subjects a subject-scope question applies to. Field vocabulary mirrors the projection query selector (ADR 0017).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kinds"
+      ],
+      "properties": {
+        "kinds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/qualifiedKind"
+          }
+        },
+        "kindMatching": {
+          "enum": [
+            "exact",
+            "descendants"
+          ],
+          "default": "descendants"
+        },
+        "statuses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "planned",
+              "current",
+              "retired"
+            ]
+          }
+        },
+        "documents": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        }
+      }
+    },
+    "condition": {
+      "description": "One deterministic trigger condition. All conditions in a trigger must hold (AND) for the question to be open.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "predicate"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-claim"
+            },
+            "predicate": {
+              "$ref": "#/$defs/claimPredicate"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds",
+            "direction"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-relationship"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "direction": {
+              "enum": [
+                "incoming",
+                "outgoing",
+                "any"
+              ]
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "isolated"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "no-subject-of-kind"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ],
+              "default": "descendants"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "no-state-defined"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "kinds",
+            "direction",
+            "counterpartKinds"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-linkage"
+            },
+            "kinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "direction": {
+              "enum": [
+                "outgoing",
+                "incoming"
+              ]
+            },
+            "counterpartKinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/qualifiedKind"
+              }
+            },
+            "kindMatching": {
+              "enum": [
+                "exact",
+                "descendants"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "predicate",
+            "direction"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-reference"
+            },
+            "predicate": {
+              "$ref": "#/$defs/claimPredicate"
+            },
+            "direction": {
+              "enum": [
+                "outgoing",
+                "incoming"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "condition",
+            "topic"
+          ],
+          "properties": {
+            "condition": {
+              "const": "missing-attestation"
+            },
+            "topic": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$"
+            }
+          }
+        }
+      ]
+    },
+    "question": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "wave",
+        "scope",
+        "trigger",
+        "question",
+        "materiality",
+        "authority"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "wave": {
+          "description": "Wave id declared in this catalogue (or an extended one).",
+          "$ref": "#/$defs/id"
+        },
+        "scope": {
+          "description": "subject: evaluated once per matching subject. workspace: evaluated once per workspace.",
+          "enum": [
+            "subject",
+            "workspace"
+          ]
+        },
+        "subjects": {
+          "$ref": "#/$defs/subjectSelector"
+        },
+        "trigger": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/condition"
+          }
+        },
+        "question": {
+          "description": "Human-facing phrasing. Subject-scope questions may interpolate {subject.id} and {subject.name}.",
+          "$ref": "#/$defs/nonEmptyText"
+        },
+        "materiality": {
+          "description": "Which architectural decision the answer changes. A question that cannot state this does not belong in the catalogue.",
+          "$ref": "#/$defs/nonEmptyText"
+        },
+        "authority": {
+          "description": "Who may answer. evidence: an agent may propose the answer from repository evidence (still lands as a reviewable diff). human: a genuine design decision that must be escalated. either: evidence may propose, human confirms.",
+          "enum": [
+            "evidence",
+            "human",
+            "either"
+          ]
+        },
+        "resolution": {
+          "description": "Guidance for how an accepted answer should land as native authoring (which claim, relationship, or state to add).",
+          "$ref": "#/$defs/nonEmptyText"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "scope": {
+                "const": "subject"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "subjects"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "scope": {
+                "const": "workspace"
+              }
+            }
+          },
+          "then": {
+            "not": {
+              "required": [
+                "subjects"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/yarramate-architecture/SKILL.md

@@ -25,11 +25,15 @@ automatically.
 When a workspace already exists, orient first with one call before choosing:
 
 ```sh
-yarramate status <workspace.yaml> --json
+yarramate ask <workspace.yaml>
 ```
 
-It reports the check verdict, the reconciliation summary, and a titled
-inventory of documents, states, projections, evidence, and contracts.
+It reports the check verdict, the reconciliation summary, the open
+design questions, and the backlog — planned subjects in dependency
+order. `ask <workspace.yaml> --subjects` lists every concept;
+`ask <workspace.yaml> --kinds` lists the declarable vocabulary;
+`ask <workspace.yaml> "<free text>"` returns the model slice matching
+your words.
 
 - Existing implementation is the starting point: follow **Discover an
   existing project**.
@@ -60,8 +64,10 @@ document, projection, evidence, or architecture-state syntax is needed.
    - 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.
+5. Land additions as one atomic `yarramate apply` batch
+   (`yarramate/operations/v1`): any invalid operation rejects the whole
+   batch, so the model never holds a partial edit. 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 the focused projections needed to answer the
@@ -74,11 +80,10 @@ document, projection, evidence, or architecture-state syntax is needed.
 
 ```sh
 yarramate check .yarramate/workspace.yaml --json
-yarramate compile .yarramate/workspace.yaml
-yarramate evidence .yarramate/evidence/<evidence>.yaml .yarramate/workspace.yaml
+yarramate export graph .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 ask .yarramate/workspace.yaml .yarramate/projections/<projection>.yaml
+yarramate export markdown .yarramate/projections/<projection>.yaml .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/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
@@ -109,6 +114,22 @@ yarramate-likec4 export-project .yarramate/likec4-project.yaml .yarramate-out/li
    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.
+   After structuring what is stated, run the interview loop for what is not:
+
+```sh
+yarramate design .yarramate/workspace.yaml
+```
+
+   Each invocation serves exactly the top open question with its subject
+   slice, materiality, and progress — the catalogue is internal; never pass
+   or read catalogue files. Answer one question at a time: questions the
+   model or evidence can answer, answer from your authority; questions
+   marked `human`, relay verbatim with their materiality. Land each answer
+   as one atomic batch (`yarramate apply <operations.yaml>
+   .yarramate/workspace.yaml`), then re-run `design` — the next question is
+   recomputed from the model, so the loop is resumable across sessions and
+   agents with no handover. Use `--subject <id>` to focus the interview on
+   one element. The interview is complete when `design` says so.
 5. Create:
    - an alternatives projection for the decision;
    - a bounded target projection for implementation agents.
@@ -119,12 +140,13 @@ yarramate-likec4 export-project .yarramate/likec4-project.yaml .yarramate-out/li
 
 ```sh
 yarramate check .yarramate/workspace.yaml --json
-yarramate compile .yarramate/workspace.yaml
-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 view .yarramate/projections/<flow>.yaml .yarramate/workspace.yaml
-yarramate compare <document-id>#<baseline-state> <document-id>#<target-state> .yarramate/workspace.yaml
+yarramate export graph .yarramate/workspace.yaml
+yarramate ask .yarramate/workspace.yaml .yarramate/projections/<alternatives>.yaml
+yarramate ask .yarramate/workspace.yaml .yarramate/projections/<target>.yaml
+yarramate export markdown .yarramate/projections/<target>.yaml .yarramate/workspace.yaml
+yarramate export markdown .yarramate/projections/<flow>.yaml .yarramate/workspace.yaml
+yarramate export briefs .yarramate/projections/<target>.yaml .yarramate/workspace.yaml --out <handoff-dir>
+yarramate ask .yarramate/workspace.yaml --compare <document-id>#<baseline-state> <document-id>#<target-state>
 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/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml
@@ -136,8 +158,11 @@ yarramate-likec4 export-project .yarramate/likec4-project.yaml .yarramate-out/li
    discovery. State which omissions are intentional; do not convert partial
    coverage into a validation failure.
 8. Present alternatives, selected intent, unresolved decisions, and bounded
-   implementation context. Do not generate code until the requested design
-   decision is reviewable.
+   implementation context. Hand implementation work the brief rendering of
+   its target slice (`yarramate ask <workspace.yaml> <projection.yaml>`,
+   or the `export briefs` bundle for several implementers) — deterministic
+   prose composed from the checked model — rather than raw YAML. Do not
+   generate code until the requested design decision is reviewable.
 
 ## Maintain an existing model
 

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

@@ -120,18 +120,57 @@ 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`:
 
+```yaml
+format: yarramate/operations/v1
+operations:
+  - op: add-relationship
+    document: .yarramate/architecture/main.yaml
+    relationship:
+      id: cli-invokes-engine
+      kind: flow
+      from: cli
+      to: engine
+      name: invokes
+      description: The CLI invokes the engine once per check run
+```
+
 ```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"
+yarramate apply operations.yaml .yarramate/workspace.yaml
 ```
 
 Both fields compile to claims, so evidence can later confirm or contradict
 the recorded invocation semantics; the degradation loses no reviewable
 information.
 
+## Batched writes
+
+Prefer `yarramate apply` when an answer or enrichment touches several
+subjects: one atomic validated batch instead of repeated single calls.
+
+```yaml
+format: yarramate/operations/v1
+operations:
+  - op: add-concept
+    document: architecture/main.yaml
+    concept: {id: audit-log, kind: applicationService, name: Audit log, status: planned}
+  - op: add-relationship
+    document: architecture/main.yaml
+    relationship: {id: api-serves-audit, kind: serving, from: audit-log, to: user}
+  - op: update-concept
+    document: architecture/main.yaml
+    concept:
+      id: user
+      description: The person whose actions are audited.
+```
+
+```sh
+yarramate apply operations.yaml workspace.yaml
+```
+
+The whole candidate workspace must compile or nothing is written.
+Update operations enrich only — scalars replace, lists append; removals
+stay Git edits.
+
 ## Ownership and constraints
 
 ```yaml
@@ -147,6 +186,25 @@ information.
 Ownership is one accountable reference, not approval workflow. Constraints are
 identified references, not a policy engine or free-form metadata bag.
 
+## Attestations
+
+```yaml
+- id: shared-context
+  kind: goal
+  name: Shared architecture context
+  attestations:
+    - topic: adequacy
+      by: reviewer-name
+      on: "2026-08-01"
+```
+
+An attestation records that an authority accepted the subject as adequate
+for a topic (the interrogation catalogue asks for `adequacy` on motivation
+subjects and `design-review` on planned elements). The judgment stays
+outside the engine — only the claim's existence is checked. Revoke by
+deleting the entry; both signing and revoking are reviewed at the Git
+boundary (ADR 0056).
+
 ## Rationale and citations
 
 Use `description` on either a concept or relationship for decided narrative
@@ -290,20 +348,18 @@ or overwrite the output manually.
 
 ```sh
 yarramate init .
-yarramate add .yarramate/architecture/main.yaml \
-  --id delivery-api --kind applicationComponent --name "Delivery API"
-yarramate connect .yarramate/architecture/main.yaml \
-  --id api-realizes-service --kind realization \
-  --from delivery-api --to delivery-service \
-  --description "The API implements the agreed delivery boundary" \
-  --reference decision-source=delivery-service
+yarramate design .yarramate/workspace.yaml
+yarramate apply operations.yaml .yarramate/workspace.yaml
+yarramate ask .yarramate/workspace.yaml
+yarramate ask .yarramate/workspace.yaml <projection.yaml>
+yarramate ask .yarramate/workspace.yaml <document-id>#<local-id>
+yarramate ask .yarramate/workspace.yaml --next
+yarramate ask .yarramate/workspace.yaml --open
+yarramate ask .yarramate/workspace.yaml --compare <from-state> <to-state>
 yarramate check .yarramate/workspace.yaml --json
-yarramate compile .yarramate/workspace.yaml
-yarramate context <projection.yaml> .yarramate/workspace.yaml
-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 export graph .yarramate/workspace.yaml
+yarramate export markdown <projection.yaml> .yarramate/workspace.yaml
 yarramate-likec4 check \
   .yarramate/likec4-project.yaml \
   --json \