@chrisdudek/yg 1.1.0 → 1.3.0

package/dist/bin.js

@@ -21,6 +21,7 @@ node_types:
   - name: module
   - name: service
   - name: library
+  - name: infrastructure
 
 artifacts:
   responsibility.md:
@@ -30,29 +31,11 @@ artifacts:
   interface.md:
     required:
       when: has_incoming_relations
-    description: "Public API \u2014 methods, parameters, return types, contracts"
+    description: "Public API \u2014 methods, parameters, return types, contracts, failure modes, exposed data structures"
     structural_context: true
-  logic.md:
+  internals.md:
     required: never
-    description: "Algorithmic flow, control flow, branching logic, decision trees \u2014 the 'how' of execution"
-  constraints.md:
-    required: never
-    description: "Validation rules, business rules, invariants"
-    structural_context: true
-  errors.md:
-    required:
-      when: has_incoming_relations
-    description: "Failure modes, edge cases, error conditions, recovery behavior"
-    structural_context: true
-  model.md:
-    required: never
-    description: "Data structures, schemas, entities, type definitions \u2014 the shape of data this node owns or manages"
-  state.md:
-    required: never
-    description: "State machines, lifecycle, transitions"
-  decisions.md:
-    required: never
-    description: "Local design decisions and rationale \u2014 choices specific to this node, not system-wide"
+    description: "How the node works and why \u2014 algorithms, business rules, state machines, design decisions with rejected alternatives"
 
 quality:
   min_artifact_length: 50
@@ -77,11 +60,12 @@ Yggdrasil is persistent semantic memory stored in \`.yggdrasil/\`. It maps the r
 BEFORE reading, researching, planning, OR modifying ANY mapped file:
   1. yg owner --file <path>
   2. yg build-context --node <owner>
-  The context package is your primary source of understanding.
-  Raw file reads are for implementation details WITHIN a node you
-  already understand from its context package.
+  The context package is your primary source of ARCHITECTURAL understanding:
+  intent, constraints, relations, rationale. For IMPLEMENTATION precision
+  (exact behavior, error handling, await patterns, edge cases) \u2014 verify
+  against source code. Aspects describe intended patterns; individual
+  implementations may deviate.
   If the context package seems insufficient \u2014 enrich the graph.
-  Do not bypass it.
 
 AFTER modifying:
   3. Update graph artifacts to reflect changes
@@ -102,7 +86,7 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 
 ### Five Core Rules
 
-1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package \u2014 not raw source \u2014 is your primary source of understanding.
+1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) \u2014 verify against source code after loading the context package.
 2. **Code and graph are one.** Code changed \u2192 graph updated in the same response. Graph changed \u2192 source verified in the same response. No exceptions.
 3. **Never invent why.** The graph captures human intent. If you don't know why something was decided, ask. Never hallucinate rationale.
 4. **Always capture why \u2014 especially why NOT.** When the user explains a reason, record it in the graph immediately. When a design choice is made, also record rejected alternatives: "Chose X over Y because Z." Rejected alternatives are the highest-value information \u2014 invisible in code and irrecoverable once forgotten. Conversation evaporates; graph persists.
@@ -112,21 +96,14 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 
 You have broken Yggdrasil if you do any of the following:
 
-- \u274C Modified source code without running \`yg owner --file <path>\` first.
-- \u274C Modified source code without updating graph artifacts in the same response.
-- \u274C Modified graph files without verifying source code alignment in the same response.
-- \u274C Resolved a code-graph inconsistency without asking the user first.
+- \u274C Worked on a mapped file without running \`yg owner\` + \`yg build-context\` first \u2014 whether reading to understand, planning, or modifying.
+- \u274C Modified source code without updating graph artifacts in the same response, or vice versa.
+- \u274C Resolved a code-graph inconsistency or ambiguity without asking the user first.
 - \u274C Created or edited a graph element without reading its schema in \`schemas/\` first.
-- \u274C Ran \`yg drift-sync\` before updating graph artifacts.
-- \u274C Wrote a flow description that describes code sequences instead of a business process.
-- \u274C Used an aspect identifier that has no corresponding \`aspects/\` directory.
-- \u274C Placed a cross-cutting requirement in a local node artifact instead of an aspect.
-- \u274C Invented a rationale, business rule, or architectural decision.
+- \u274C Ran \`yg drift-sync\` before both graph artifacts and source code are current.
+- \u274C Placed a cross-cutting requirement in a local artifact instead of an aspect, or used an aspect id with no \`aspects/\` directory.
+- \u274C Invented a rationale, business rule, or decision \u2014 or recorded a decision without documenting rejected alternatives and rationale (use "rationale: unknown" if unknown).
 - \u274C Used blackbox coverage for greenfield (new) code.
-- \u274C Answered a question about a mapped file without running \`yg build-context\` first.
-- \u274C Read mapped source files to plan or research changes without running \`yg build-context\` first.
-- \u274C Deferred \`yg drift-sync\` to the end of a multi-step task instead of running it incrementally after each logical group of changes.
-- \u274C Recorded a design decision without documenting which alternatives were rejected and why.
 
 ### Escape Hatch
 
@@ -166,6 +143,10 @@ WRAP-UP (user signals "done", "wrap up", "that's enough"):
   - [ ] 2. yg drift --drifted-only \u2192 resolve
   - [ ] 3. yg validate \u2192 fix errors
   - [ ] 4. Report: which nodes and files were changed
+
+BEFORE ENDING ANY RESPONSE (self-audit):
+  - [ ] Did I modify source code? If yes \u2192 did I update graph artifacts in this same response?
+  - [ ] If you changed code and did not sync the graph, you have broken the protocol. Do not finish until both are done.
 \`\`\`
 
 ### Modify Source Code
@@ -197,7 +178,7 @@ You are not allowed to edit or create source code without establishing graph cov
 
 1. Create aspects first (cross-cutting requirements the new code must satisfy)
 2. Create flows if the code participates in a business process
-3. Create nodes with full artifacts \u2014 responsibility, constraints, decisions, interface, logic
+3. Create nodes with full artifacts \u2014 responsibility, interface, internals
 4. Review the context package (\`yg build-context\`) \u2014 it is now the behavioral specification
 5. Implement code that satisfies the specification
 6. The graph specifies WHAT and WHY; the code implements HOW (framework APIs, library choices)
@@ -234,7 +215,8 @@ Per area checklist:
 - Business process unclear: "This code appears to be part of a larger process. Can you describe what it means from a business perspective?"
 - Constraint without rationale: "I see [constraint X]. Do you know why this exists? I want to record the reason, not just the rule."
 - Unexplained architectural choice: "I see [approach X]. What was the reason for this choice?"
-- Decision without alternatives: "You chose [X]. What alternatives did you consider, and why did you reject them?" Record the answer in \`decisions.md\`.
+- Decision without alternatives: "You chose [X]. What alternatives did you consider, and why did you reject them?" Record the answer in the Decisions section of \`internals.md\`.
+- Decision without known rationale: Record the decision in \`internals.md\` with "rationale: unknown \u2014 inferred from code, not confirmed by developer." A recorded decision with unknown rationale is infinitely more valuable than no record at all, and safer than an invented rationale.
 
 ### Bootstrap Mode
 
@@ -262,6 +244,27 @@ Always ask the user before resolving drift. Never auto-resolve.
 
 Threshold: >10 drifted nodes \u2192 ask user which area to prioritize. Do not resolve all at once.
 
+**Drift triage:** Prioritize aspects and \`internals.md\` (highest decay rate), then \`responsibility.md\` and \`interface.md\` (most stable).
+
+### Graph Audit
+
+When reviewing graph quality (triggered by user or quality improvement):
+
+**Step 1 \u2014 Consistency** (catches WRONG information):
+
+- [ ] 1. \`yg build-context --node <path>\`
+- [ ] 2. Read mapped source files
+- [ ] 3. For each claim in graph: verify against source code
+- [ ] 4. For each aspect: verify the pattern holds in THIS node. If it deviates, add \`aspect_exceptions\` in \`node.yaml\`
+- [ ] 5. Report inconsistencies
+
+**Step 2 \u2014 Completeness** (catches MISSING information):
+
+- [ ] 1. For each public method: is it in \`interface.md\`?
+- [ ] 2. For each error path: is it in \`interface.md\` (Failure Modes section)?
+- [ ] 3. For each behavioral invariant: is it in the graph?
+- [ ] 4. Report omissions separately from inconsistencies
+
 ### Error Recovery
 
 - **\`yg\` not found** \u2192 inform user: "yg CLI is not installed or not in PATH." Stop.
@@ -290,9 +293,24 @@ Key facts:
 - **Aspect id = directory path** under \`aspects/\`. Each aspect has \`aspect.yaml\` + content \`.md\` files. No automatic parent-child \u2014 use \`implies\` explicitly.
 - **Flows = business processes.** A flow describes what happens in the world, not code sequences. Flow aspects propagate to all participants.
 
+**Node type guidance:**
+
+- \`module\` \u2014 business logic unit with clear domain responsibility
+- \`service\` \u2014 component providing functionality to other nodes
+- \`library\` \u2014 shared utility code with no domain knowledge
+- \`infrastructure\` \u2014 guards, resolvers, middleware, interceptors, validators that intercept or modify request flow. These affect blast radius of changes but are invisible in call graphs. Map them to make blast radius analysis accurate. Key signal: code that runs WITHOUT being explicitly called by business logic (e.g., NestJS guards, Express middleware, GraphQL resolvers).
+
+### Artifact Structure
+
+Three artifacts capture node knowledge at three levels:
+
+- **responsibility.md** (always required) \u2014 WHAT: identity, boundaries, what the node is NOT responsible for.
+- **interface.md** (required when node has consumers) \u2014 HOW TO USE: public methods, parameters, return types, contracts, failure modes, exposed data structures. Everything another node needs to interact with this one.
+- **internals.md** (optional, highest value for cross-module nodes) \u2014 HOW IT WORKS + WHY: algorithms, control flow, business rules, invariants, state machines, lifecycle, and design decisions with rejected alternatives. Use sections within the file: ## Logic, ## Constraints, ## State, ## Decisions (with "Chose X over Y because Z" format).
+
 ### Context Assembly
 
-Run \`yg build-context --node <path>\` to get the deterministic context package for a node. Trust the package \u2014 it assembles global config, hierarchy, own artifacts, aspects, and relational context. If the package is insufficient, enrich the graph. Do not bypass it with raw file exploration.
+Run \`yg build-context --node <path>\` to get the deterministic context package for a node. The package assembles global config, hierarchy, own artifacts, aspects, and relational context. It is your architectural map. For implementation-level claims (exact call patterns, error handling, await vs fire-and-forget) \u2014 verify against source code. If the package is insufficient, enrich the graph.
 
 ### Information Routing
 
@@ -303,7 +321,7 @@ When you encounter information, route it to the correct location:
 - **Business process** \u2192 flow (\`flows/<name>/\` with \`flow.yaml\` + \`description.md\`). Ask user if process unclear.
 - **Shared across a domain** \u2192 parent node artifact. Children receive it through hierarchy.
 - **Technology stack or standard** \u2192 \`config.yaml\` under \`stack\` or \`standards\` (+ \`rationale\` field)
-- **Decision (why + why NOT):** one node \u2192 \`decisions.md\` with format "Chose X over Y because Z"; category of nodes \u2192 aspect content files; tech choice \u2192 \`config.yaml\` rationale field. Always include rejected alternatives \u2014 they are the highest-value graph content.
+- **Decision (why + why NOT):** one node \u2192 Decisions section of \`internals.md\` with format "Chose X over Y because Z"; category of nodes \u2192 aspect content files; tech choice \u2192 \`config.yaml\` rationale field. Always include rejected alternatives \u2014 they are the highest-value graph content. If the rationale is unknown: record the decision with "rationale: unknown" and note what CAN be observed from the code. Never invent a plausible-sounding rationale.
 
 ### Creating Aspects
 
@@ -321,6 +339,10 @@ Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. No
 - **Architectural:** Structural patterns with rationale (e.g., dual-rollback on provider failure, idempotency via key generation, fire-and-forget dispatch)
 - **Concurrency:** Shared concurrency strategies (e.g., pessimistic locking, retry-on-deadlock, optimistic versioning)
 
+When a node follows an aspect's pattern with exceptions, record exceptions in \`node.yaml\` under \`aspect_exceptions\`. Example: aspect says "fire-and-forget" but this node awaits the publish call. The exception appears in the context package next to the aspect content, preventing abstractions from masking implementation details.
+
+**Aspect lifecycle warning.** Aspects decay CATASTROPHICALLY \u2014 a pattern either exists or it doesn't. When a pattern changes, ALL aspect claims become wrong at once. This differs from other artifacts: \`interface.md\` and \`responsibility.md\` are most stable (~9-year half-life); \`internals.md\` has moderate stability (~2.5-year half-life); aspects are least stable (~2.4-year half-life, binary decay). After any significant feature addition, review ALL aspects touching the affected area. Don't wait for drift \u2014 aspects can be 100% wrong without any mapped file changing.
+
 ### Creating Flows
 
 - [ ] 1. Read \`schemas/flow.yaml\`
@@ -331,13 +353,18 @@ Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. No
 
 Test: "Does this describe what happens in the world, or only in the software?" If only software \u2014 rewrite.
 
+**Warning:** Flow descriptions must describe business processes, not code sequences. "The OrderService calls PaymentGateway.charge()" is WRONG. "The system charges the customer's payment method" is CORRECT.
+
 ### Operational Rules
 
 - **English only** for all files in \`.yggdrasil/\`. Conversation can be any language.
 - **Read schemas before creating** any \`node.yaml\`, \`aspect.yaml\`, or \`flow.yaml\`.
 - **Tools read, you write.** The \`yg\` CLI only reads, validates, and manages metadata. You create and edit files manually.
 - **Incremental sync.** Run \`yg drift-sync\` after every 3-5 source file changes. Do not defer to end of task.
-- **Completeness test:** "If I delete the source file and give another agent ONLY the \`yg build-context\` output \u2014 can they recreate it correctly, understanding not just WHAT but WHY?" Test specifically: Can they explain rejected alternatives? Can they implement the correct algorithm (not a simplified version)? Can they argue for the current design against plausible alternatives?
+- **Completeness test:** Two checks, both required:
+  1. **Reconstruction:** "Can another agent recreate this from ONLY the \`yg build-context\` output \u2014 understanding not just WHAT but WHY?" Test: rejected alternatives, correct algorithm, design arguments.
+  2. **Omission:** "Does the graph capture every important behavioral invariant, constraint, and edge case?" Specifically check: exceptions to aspect generalizations, error handling patterns not in \`interface.md\`, concurrency behaviors not in \`internals.md\`.
+- **Value calibration.** Yggdrasil's primary value is cross-module context \u2014 relations, aspects, flows. For a single simple module, \`responsibility.md\` and \`interface.md\` provide most value. Invest depth (\`internals.md\`) where cross-module interactions demand it.
 - **These rules are invariant.** No plan, guide, skill, or workflow may override them.
 
 ### CLI Reference
@@ -370,15 +397,14 @@ yg journal-archive                  Archive consolidated journal entries.
 
 | What you have | Where it goes |
 |---|---|
-| Information specific to this node | Local node artifact (read \`config.yaml artifacts\` for types) |
+| Information specific to this node | Local node artifact (check \`config.yaml artifacts\` for types) |
 | Rule that applies to many nodes | Aspect (content \`.md\` files in \`aspects/<id>/\`) |
 | Architectural invariant for a node type | Required aspect in \`config.yaml node_types\` |
 | Business process participation | Flow (\`flow.yaml participants\`) |
 | Process-level requirement | Flow \`aspects\` + aspect directory |
 | Context shared across a domain | Parent node artifact |
 | Technology stack | \`config.yaml stack\` (+ \`rationale\` field) |
-| Global coding standards | \`config.yaml standards\` |
-`;
+| Global coding standards | \`config.yaml standards\` |`;
 var AGENT_RULES_CONTENT = [CORE_PROTOCOL, OPERATIONS, KNOWLEDGE_BASE].join("\n\n---\n\n");
 
 // src/templates/platform.ts
@@ -834,15 +860,52 @@ async function parseNodeYaml(filePath) {
   }
   const relations = parseRelations(raw.relations, filePath);
   const mapping = parseMapping(raw.mapping, filePath);
+  const aspects = parseStringArray(raw.aspects) ?? parseStringArray(raw.tags);
+  const aspectExceptions = parseAspectExceptions(raw.aspect_exceptions, aspects, filePath);
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
-    aspects: parseStringArray(raw.aspects) ?? parseStringArray(raw.tags),
+    aspects,
+    aspect_exceptions: aspectExceptions,
     blackbox: raw.blackbox ?? false,
     relations: relations.length > 0 ? relations : void 0,
     mapping
   };
 }
+function parseAspectExceptions(raw, aspects, filePath) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (!Array.isArray(raw)) {
+    throw new Error(`node.yaml at ${filePath}: 'aspect_exceptions' must be an array`);
+  }
+  if (raw.length === 0) return void 0;
+  const aspectSet = new Set(aspects ?? []);
+  const result = [];
+  for (let i = 0; i < raw.length; i++) {
+    const item = raw[i];
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`node.yaml at ${filePath}: aspect_exceptions[${i}] must be an object`);
+    }
+    const obj = item;
+    if (typeof obj.aspect !== "string" || obj.aspect.trim() === "") {
+      throw new Error(
+        `node.yaml at ${filePath}: aspect_exceptions[${i}].aspect must be a non-empty string`
+      );
+    }
+    if (typeof obj.note !== "string" || obj.note.trim() === "") {
+      throw new Error(
+        `node.yaml at ${filePath}: aspect_exceptions[${i}].note must be a non-empty string`
+      );
+    }
+    const aspectId = obj.aspect.trim();
+    if (!aspectSet.has(aspectId)) {
+      throw new Error(
+        `node.yaml at ${filePath}: aspect_exceptions[${i}].aspect "${aspectId}" is not in this node's aspects list`
+      );
+    }
+    result.push({ aspect: aspectId, note: obj.note.trim() });
+  }
+  return result.length > 0 ? result : void 0;
+}
 function parseStringArray(val) {
   if (!Array.isArray(val)) return void 0;
   const arr = val.filter((v) => typeof v === "string");
@@ -1288,7 +1351,8 @@ async function buildContext(graph, nodePath) {
   }
   const aspectsToInclude = resolveAspects(allAspectIds, graph.aspects);
   for (const aspect of aspectsToInclude) {
-    layers.push(buildAspectLayer(aspect));
+    const exception = node.meta.aspect_exceptions?.find((e) => e.aspect === aspect.id);
+    layers.push(buildAspectLayer(aspect, exception?.note));
   }
   const fullText = layers.map((l) => l.content).join("\n\n");
   const tokenCount = estimateTokens(fullText);
@@ -1471,9 +1535,14 @@ Consumes: ${relation.consumes.join(", ")}`;
     attrs
   };
 }
-function buildAspectLayer(aspect) {
-  const content = aspect.artifacts.map((a) => `### ${a.filename}
+function buildAspectLayer(aspect, exceptionNote) {
+  let content = aspect.artifacts.map((a) => `### ${a.filename}
 ${a.content}`).join("\n\n");
+  if (exceptionNote) {
+    content += `
+
+\u26A0 **Exception for this node:** ${exceptionNote}`;
+  }
   return {
     type: "aspects",
     label: `${aspect.name} (aspect: ${aspect.id})`,
@@ -1574,6 +1643,7 @@ async function validate(graph, scope = "all") {
     issues.push(...checkImpliedAspectsExist(graph));
     issues.push(...checkImpliesNoCycles(graph));
     issues.push(...checkRequiredAspectsCoverage(graph));
+    issues.push(...checkAspectExceptions(graph));
     issues.push(...checkRequiredArtifacts(graph));
     issues.push(...checkInvalidArtifactConditions(graph));
     issues.push(...await checkContextBudget(graph));
@@ -1820,6 +1890,24 @@ function checkRequiredAspectsCoverage(graph) {
   }
   return issues;
 }
+function checkAspectExceptions(graph) {
+  const issues = [];
+  for (const [nodePath, node] of graph.nodes) {
+    for (const exception of node.meta.aspect_exceptions ?? []) {
+      const nodeAspects = node.meta.aspects ?? [];
+      if (!nodeAspects.includes(exception.aspect)) {
+        issues.push({
+          severity: "error",
+          code: "E018",
+          rule: "invalid-aspect-exception",
+          message: `aspect_exceptions references aspect '${exception.aspect}' which is not in this node's aspects list (${nodeAspects.join(", ") || "none"})`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
 function checkNoCycles(graph) {
   const WHITE = 0;
   const GRAY = 1;
@@ -3155,7 +3243,7 @@ function findOwner(graph, projectRoot, rawPath) {
     const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizeForMatch).filter((mappingPath) => mappingPath.length > 0);
     for (const mappingPath of mappingPaths) {
       if (file === mappingPath) {
-        return { file, nodePath, mappingPath };
+        return { file, nodePath, mappingPath, direct: true };
       }
       if (file.startsWith(mappingPath + "/")) {
         if (!best || best && mappingPath.length > best.mappingPath.length) {
@@ -3164,7 +3252,7 @@ function findOwner(graph, projectRoot, rawPath) {
       }
     }
   }
-  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath } : { file, nodePath: null };
+  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath, direct: false } : { file, nodePath: null };
 }
 function registerOwnerCommand(program2) {
   program2.command("owner").description("Find which graph node owns a source file").requiredOption("--file <path>", "File path (relative to repository root)").action(async (options) => {
@@ -3194,6 +3282,12 @@ function registerOwnerCommand(program2) {
       } else {
         process.stdout.write(`${result.file} -> ${result.nodePath}
 `);
+        if (result.direct === false && result.mappingPath) {
+          process.stdout.write(
+            `  Plik nie ma w\u0142asnego mapowania; kontekst pochodzi z nadrz\u0119dnego katalogu ${result.mappingPath}. U\u017Cyj: yg build-context --node ${result.nodePath}
+`
+          );
+        }
       }
     } catch (error) {
       process.stderr.write(`Error: ${error.message}