yarramate 0.3.0 → 0.3.2

package/dist/adapters/likec4-cli.js

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
-import { isSeq, parseDocument } from 'yaml';
+import { isMap, isSeq, parseDocument } from 'yaml';
 import { isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
 import { compileWorkspace } from '../compiler.js';
 import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
@@ -73,7 +73,7 @@ const publishFiles = (files) => {
     }
 };
 const usage = 'Usage:\n' +
-    '  yarramate-likec4 map --sync <mapping.yaml> <workspace-or-source...>\n' +
+    '  yarramate-likec4 map --sync [--prune] <mapping.yaml> <workspace-or-source...>\n' +
     '  yarramate-likec4 check <projection.yaml> <mapping.yaml> [--json] [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
     '  yarramate-likec4 check <likec4-project.yaml> [--json] <workspace-or-source...>\n' +
     '  yarramate-likec4 export <projection.yaml> <mapping.yaml> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
@@ -91,7 +91,10 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
 const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
-    const [sync, mappingPath, ...sourcePaths] = args;
+    const sync = args[0];
+    const prune = args[1] === '--prune';
+    const mappingPath = args[prune ? 2 : 1];
+    const sourcePaths = args.slice(prune ? 3 : 2);
     if (sync !== '--sync' ||
         mappingPath === undefined ||
         mappingPath.startsWith('-') ||
@@ -145,16 +148,23 @@ const runLikeC4MapSync = (args, cwd) => {
                 stderr: '',
             };
         }
+        const graphSubjects = new Set(compilation.graph.subjects.map(({ id }) => id));
+        const staleCount = loaded.mapping.mappings.filter(({ native }) => !graphSubjects.has(native)).length;
         const validation = validateAdapterMapping(compilation.graph, loaded.mapping);
-        if (!validation.ok) {
+        const blockingDiagnostics = validation.ok
+            ? []
+            : validation.diagnostics.filter(({ code }) => code !== 'YM601');
+        if (blockingDiagnostics.length > 0) {
             return {
                 exitCode: 1,
-                stdout: diagnosticJson(validation.diagnostics),
+                stdout: diagnosticJson(blockingDiagnostics),
                 stderr: '',
             };
         }
         const mapped = new Set(loaded.mapping.mappings.map(({ native }) => native));
-        const claimedExternal = new Set(loaded.mapping.mappings.map(({ external }) => external));
+        const claimedExternal = new Set(loaded.mapping.mappings
+            .filter(({ native }) => !prune || graphSubjects.has(native))
+            .map(({ external }) => external));
         const architectureStates = new Set(compilation.graph.claims
             .filter(({ predicate }) => predicate === 'yarramate/state/type')
             .map(({ subject }) => subject));
@@ -180,18 +190,29 @@ const runLikeC4MapSync = (args, cwd) => {
                 type: subject.type,
             };
         });
-        if (additions.length === 0) {
+        if (additions.length === 0 && (!prune || staleCount === 0)) {
             return {
                 exitCode: 0,
-                stdout: `LikeC4 mapping ${mappingPath} is already synchronized\n`,
+                stdout: staleCount === 0
+                    ? `LikeC4 mapping ${mappingPath} is already synchronized\n`
+                    : `LikeC4 mapping ${mappingPath} has ${staleCount} stale ${staleCount === 1 ? 'mapping' : 'mappings'} (use --prune)\n`,
                 stderr: '',
             };
         }
         const document = parseDocument(original);
+        const mappings = document.getIn(['mappings'], true);
+        if (prune && isSeq(mappings)) {
+            const firstMappingWasPruned = mappings.items.length > 0 &&
+                isMap(mappings.items[0]) &&
+                !graphSubjects.has(String(mappings.items[0].get('native')));
+            mappings.items = mappings.items.filter((item) => !isMap(item) ||
+                graphSubjects.has(String(item.get('native'))));
+            if (firstMappingWasPruned)
+                mappings.commentBefore = undefined;
+        }
         for (const addition of additions) {
             document.addIn(['mappings'], addition);
         }
-        const mappings = document.getIn(['mappings'], true);
         if (isSeq(mappings))
             mappings.flow = false;
         const candidate = document.toString({ lineWidth: 0 });
@@ -207,10 +228,13 @@ const runLikeC4MapSync = (args, cwd) => {
             };
         }
         const candidateValidation = validateAdapterMapping(compilation.graph, candidateMapping.mapping);
-        if (!candidateValidation.ok) {
+        const candidateBlockingDiagnostics = candidateValidation.ok
+            ? []
+            : candidateValidation.diagnostics.filter(({ code }) => prune || code !== 'YM601');
+        if (candidateBlockingDiagnostics.length > 0) {
             return {
                 exitCode: 1,
-                stdout: diagnosticJson(candidateValidation.diagnostics),
+                stdout: diagnosticJson(candidateBlockingDiagnostics),
                 stderr: '',
             };
         }
@@ -223,7 +247,14 @@ const runLikeC4MapSync = (args, cwd) => {
         }
         return {
             exitCode: 0,
-            stdout: `Added ${additions.length} LikeC4 mappings to ${mappingPath}\n`,
+            stdout: prune
+                ? additions.length > 0
+                    ? `Added ${additions.length} and pruned ${staleCount} stale LikeC4 ${staleCount === 1 ? 'mapping' : 'mappings'} in ${mappingPath}\n`
+                    : `Pruned ${staleCount} stale LikeC4 ${staleCount === 1 ? 'mapping' : 'mappings'} from ${mappingPath}\n`
+                : `Added ${additions.length} LikeC4 ${additions.length === 1 ? 'mapping' : 'mappings'} to ${mappingPath}` +
+                    (staleCount === 0
+                        ? '\n'
+                        : `; left ${staleCount} stale ${staleCount === 1 ? 'mapping' : 'mappings'} (use --prune)\n`),
             stderr: '',
         };
     }

package/package.json

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

package/skills/yarramate-architecture/SKILL.md

@@ -52,19 +52,34 @@ 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 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,17 +99,29 @@ 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 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.
 
@@ -102,6 +129,8 @@ yarramate compare <baseline-state> <target-state> .yarramate/workspace.yaml
 
 - Treat `check` as deterministic correctness, never as architecture approval,
   completeness, or quality scoring.
+- 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 +148,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/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,6 @@ 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.

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

@@ -172,6 +172,47 @@ 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.
+
+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
@@ -193,6 +234,20 @@ yarramate reconcile .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
+```
+
+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:
+
+```sh
+yarramate-likec4 map --sync --prune \
+  .yarramate/integrations/likec4/subject-mapping.yaml \
+  .yarramate/workspace.yaml
 ```
 
 Treat exit `0` as successful execution, `1` as correctness diagnostics, and