yarramate 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

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
@@ -26,7 +26,10 @@ automatically.
   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.
 
@@ -52,19 +55,35 @@ document, projection, evidence, or architecture-state syntax is needed.
    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:
+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`.
+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:
 
 ```sh
 yarramate check .yarramate/workspace.yaml --json
+yarramate compile .yarramate/workspace.yaml
 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
 ```
 
-9. Present observations, reconciliation findings, interpretive proposals,
+9. Audit rendering coverage before handoff. Answer these as reporting
+   questions, not Core correctness rules:
+   - Which concepts appear in no projection?
+   - Which ordered relationship chains have no dynamic view?
+   - Which projections are absent from the LikeC4 project?
+   Inspect compiled subjects, projection results, and the project definition;
+   state intentional omissions explicitly. A green check does not answer
+   these questions.
+10. 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.
 
@@ -84,24 +103,93 @@ yarramate view .yarramate/projections/<projection>.yaml .yarramate/workspace.yam
 5. Create:
    - an alternatives projection for the decision;
    - a bounded target projection for implementation agents.
-6. Run:
+   - one focused projection per ordered flow that needs a dynamic view.
+   Include every intended view in
+   `.yarramate/integrations/likec4/project.yaml`.
+6. Synchronize the project mapping before every export, then run:
 
 ```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 compare <baseline-state> <target-state> .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
 ```
 
-7. Present alternatives, selected intent, unresolved decisions, and bounded
+   Skip the two adapter commands only when the user requested semantic-only
+   output, and report that no visual project was produced.
+7. Audit rendering coverage using the same three reporting questions from
+   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.
 
+## 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.
 - Use globally qualified identities at CLI and projection boundaries.
 - Preserve source-located diagnostics verbatim when asking the author to fix
@@ -119,7 +207,9 @@ Report:
 - journey used and question answered;
 - canonical files proposed or changed;
 - observations and evidence results;
-- projections produced;
+- projections and views produced, including the LikeC4 project and generated
+  output path;
+- rendering coverage gaps and whether the generated output is current;
 - validation commands and outcomes;
 - unresolved architectural decisions;
 - whether changes are merely proposed or already accepted in Git.

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

@@ -46,6 +46,9 @@ Discovery is minimally useful when:
 - significant proposed subjects have traceable observations or are explicitly
   identified as interpretation;
 - a focused projection gives an agent useful repository context;
+- intended projections are rendered through a current LikeC4 project;
+- concepts outside all projections, ordered flows without dynamic views, and
+  projections absent from the project are reported as coverage gaps;
 - evidence has not been promoted automatically.
 
 Design is minimally useful when:
@@ -54,4 +57,14 @@ Design is minimally useful when:
 - material alternatives remain reviewable;
 - the selected target has explicit boundaries and relationships;
 - a bounded target projection can guide implementation;
+- 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
 
@@ -172,6 +174,50 @@ Evidence evaluates an existing subject or stable claim ID. Results are
 observed subject directly through evidence or mutate declared intent from an
 evidence result.
 
+## LikeC4 project
+
+Keep visualization configuration outside native documents:
+
+```yaml
+format: yarramate/likec4-project/v1
+id: delivery
+version: "1.0"
+title: Delivery architecture
+mapping: .yarramate/integrations/likec4/subject-mapping.yaml
+views:
+  - projection: .yarramate/projections/delivery-target.yaml
+  - id: submit-order
+    projection: .yarramate/projections/submit-order.yaml
+    dynamic:
+      steps:
+        - relationship: delivery#customer-triggers-submit
+        - relationship: delivery#submit-triggers-confirmation
+```
+
+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:
+
+```yaml
+format: yarramate/adapter-mapping/v1
+id: delivery-likec4
+version: "1.0"
+adapter: likec4
+mappings: []
+```
+
+`export-project` writes `.yarramate-out/likec4/yarramate.generated.json` with
+digests for generated files. It refuses to replace a generated file that was
+hand-edited. Treat that refusal as drift to inspect; do not delete the marker
+or overwrite the output manually.
+
 ## Stable commands
 
 ```sh
@@ -190,11 +236,25 @@ 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
+yarramate-likec4 export-project \
+  .yarramate/integrations/likec4/project.yaml \
+  .yarramate-out/likec4 \
+  .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: