@chrisdudek/yg 0.3.4 → 1.1.0

package/dist/templates/default-config.ts

@@ -6,12 +6,10 @@ stack:
 
 standards: ""
 
-tags: []
-
 node_types:
-  - module
-  - service
-  - library
+  - name: module
+  - name: service
+  - name: library
 
 artifacts:
   responsibility.md:
@@ -45,19 +43,10 @@ artifacts:
     required: never
     description: "Local design decisions and rationale — choices specific to this node, not system-wide"
 
-knowledge_categories:
-  - name: decisions
-    description: "Global semantic decisions and their rationale"
-  - name: patterns
-    description: "Implementation conventions with examples"
-  - name: invariants
-    description: "System truths that must never be violated"
-
 quality:
   min_artifact_length: 50
   max_direct_relations: 10
   context_budget:
     warning: 10000
     error: 20000
-  knowledge_staleness_days: 90
 `;

package/dist/templates/rules.ts

@@ -1,243 +1,329 @@
 /**
  * Canonical agent rules content — hand-tuned, do not generate programmatically.
  *
- * Operating manual for agents: graph-first, exhaustive coverage, context is sufficient.
+ * Operating manual for agents working in a Yggdrasil-managed repository.
+ * Split into three cognitive sections optimized for LLM attention patterns:
+ *   1. CORE PROTOCOL — internalize before doing anything (primacy effect)
+ *   2. OPERATIONS — execute while working (working memory)
+ *   3. KNOWLEDGE BASE — look up when needed (recency effect)
  */
-export const AGENT_RULES_CONTENT = `# Yggdrasil - System Semantic Memory (Operating Manual)
 
-You are working in a repository managed by Yggdrasil.
-Yggdrasil is a persistent, structured semantic memory graph stored in \`.yggdrasil/\`. It maps the repository, dictates system rules, and assembles implementation contexts.
+// prettier-ignore
+const CORE_PROTOCOL = `## CORE PROTOCOL
+
+Yggdrasil is persistent semantic memory stored in \`.yggdrasil/\`. It maps the repository and provides deterministic implementation context for every node. This document is your complete operating manual. Follow it strictly.
+
+### Quick Start Protocol
+
+\`\`\`
+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.
+  If the context package seems insufficient — enrich the graph.
+  Do not bypass it.
+
+AFTER modifying:
+  3. Update graph artifacts to reflect changes
+  4. yg validate — fix all errors
+  5. yg drift-sync --node <owner>
 
-**Why:** AI agents degrade with project size — too little context breaks contracts, too much context drowns in noise. The graph is persistent semantic memory: agents need exactly the right tokens for the task, not the whole repo. Small, precise context beats massive noisy. A repository with Yggdrasil is self-aware.
+EVERY conversation start:
+  yg preflight → act on findings (see Operations)
 
-THIS PROMPT IS YOUR ENTIRE OPERATING MANUAL. Read it carefully. Follow it strictly.
+NEVER: modify code without graph coverage.
+NEVER: read mapped source files to understand a component without
+       running yg build-context first — the graph captures intent,
+       constraints, and relations that source files cannot.
+NEVER: invent rationale, business rules, or decisions.
+NEVER: auto-resolve drift without asking the user.
+WHEN UNSURE: ask the user. Never guess. Never assume.
+\`\`\`
 
----
+### Five Core Rules
 
-## 0. ATOMIC INVARIANT — OVERRIDES EVERYTHING
+1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package — not raw source — is your primary source of understanding.
+2. **Code and graph are one.** Code changed → graph updated in the same response. Graph changed → 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 — 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 — invisible in code and irrecoverable once forgotten. Conversation evaporates; graph persists.
+5. **Ask before resolving ambiguity.** When multiple valid interpretations exist, stop, list options, ask the user. Never silently choose.
 
-**CODE ↔ GRAPH ARE ONE.**
-- Code changed → graph artifacts MUST be updated IN THE SAME RESPONSE. No exceptions.
-- Graph changed → source files MUST be verified/updated IN THE SAME RESPONSE. No exceptions.
-- There is NO "code-only" response. There is NO "graph-only" response (unless explicitly a dry-run plan).
-- If you complete a response and one side is changed but the other is not, you have VIOLATED the core contract of Yggdrasil.
+### Failure States
 
----
+You have broken Yggdrasil if you do any of the following:
 
-## 1. CORE PRINCIPLES (NON-NEGOTIABLE)
+- ❌ Modified source code without running \`yg owner --file <path>\` first.
+- ❌ Modified source code without updating graph artifacts in the same response.
+- ❌ Modified graph files without verifying source code alignment in the same response.
+- ❌ Resolved a code-graph inconsistency without asking the user first.
+- ❌ Created or edited a graph element without reading its schema in \`schemas/\` first.
+- ❌ Ran \`yg drift-sync\` before updating graph artifacts.
+- ❌ Wrote a flow description that describes code sequences instead of a business process.
+- ❌ Used an aspect identifier that has no corresponding \`aspects/\` directory.
+- ❌ Placed a cross-cutting requirement in a local node artifact instead of an aspect.
+- ❌ Invented a rationale, business rule, or architectural decision.
+- ❌ Used blackbox coverage for greenfield (new) code.
+- ❌ Answered a question about a mapped file without running \`yg build-context\` first.
+- ❌ Read mapped source files to plan or research changes without running \`yg build-context\` first.
+- ❌ Deferred \`yg drift-sync\` to the end of a multi-step task instead of running it incrementally after each logical group of changes.
+- ❌ Recorded a design decision without documenting which alternatives were rejected and why.
 
-1. **Graph First, Always:** Before answering a question, modifying code, or planning a feature, you MUST consult the graph.
-2. **Context is Sufficient:** If you feel the need to randomly explore source files to understand what a node should do, the graph is incomplete. **Fix the graph** (add decisions, interface details, constraints). Do not bypass the graph by reading raw code.
-3. **Graph is Intended Truth:** If the code and graph diverge, the graph is the truth. If a code change is deliberate, update the graph to match.
-4. **Exhaustive Coverage:** Every source file MUST belong to exactly one graph node. No orphaned files.
-5. **Tools Read, You Write:** The \`yg\` CLI tools only read, validate, and manage metadata. YOU must create and edit graph directories, \`.yaml\` files, and \`.md\` artifacts manually.
-6. **English Only for Artifacts:** All graph artifact files (filenames from \`config.artifacts\`, in the same directory as \`node.yaml\`) MUST be written in English. Conversation can be in the user's language.
-7. **Never Touch Operational Metadata:** NEVER manually edit \`.yggdrasil/.drift-state\` or \`.yggdrasil/.journal.yaml\`.
-8. **Ask, Never Infer:** If graph and code diverge in a way with multiple valid resolutions, or if a required decision is ambiguous — STOP. State the ambiguity. List interpretations. Ask the user to decide. Never silently choose. Never patch without confirmation. When you stop, always explain the context and available options clearly so the user can make an informed choice.
+### Escape Hatch
 
----
+If the user explicitly requests a code-only change, comply but:
 
-## 1.5 FAILURE STATES
+- Warn: "This creates drift. Run \`yg drift\` next session to reconcile."
+- Do NOT run \`yg drift-sync\` — leave the drift visible.
 
-You have fundamentally broken Yggdrasil if you do any of the following:
-- ❌ You modified source code without having run \`yg owner --file <path>\` for each modified file in the SAME response.
-- ❌ You modified source code without updating graph artifacts in the SAME response.
-- ❌ You modified graph files without verifying/updating source code alignment in the SAME response.
-- ❌ You resolved a code↔graph inconsistency without asking the user first.
-- ❌ You created or edited a graph element without reading its schema in \`.yggdrasil/templates/\`.
-- ❌ You ran \`yg drift-sync\` before updating graph artifacts.
-- ❌ You ran \`yg drift-sync\` after a graph-only change without verifying source files.
-- ❌ You used Blackbox coverage for greenfield/new code.
-- ❌ You answered a question about a mapped file/area without running \`yg build-context\` when the path was known.
+### Environment Check
 
----
+Before preflight:
 
-## 2. CONVERSATION LIFECYCLE (YOUR HABITS)
+- Verify \`yg\` CLI is available. If not found, inform user and stop.
+- If \`yg preflight\` shows 0 nodes → enter BOOTSTRAP MODE (see Operations).
+- If drift report shows >10 drifted nodes → report scope to user, ask which area to prioritize. Do not resolve all at once.`;
 
-You do not need explicit "session" commands. Follow these conversational triggers:
+// prettier-ignore
+const OPERATIONS = `## OPERATIONS
 
-### A. Preflight (First message of the conversation)
-Always execute these commands before doing anything else. *(Exception: If the user's request is clearly read-only, run ONLY step 1).* **Read-only** means the user asks only for explanation, clarification, analysis, or evaluation — no code or graph modification will occur. Examples: "explain this", "evaluate X", "what does Y do?", "analyze Z". If unsure, run full preflight.
-1. \`yg journal-read\` -> If entries exist, consolidate them into the graph, then \`yg journal-archive\`.
-2. \`yg drift\` -> If **drift** (code changed, graph baseline stale): run \`yg drift-sync\` for each affected node. Do NOT ask the user — they do not need to know this step. If **missing** or **unmaterialized**: report and ask the user how to proceed.
-3. \`yg status\` -> Report graph health.
-4. \`yg validate\` -> If W008 stale-knowledge appears, update the knowledge artifacts to reflect current node state.
+### Conversation Lifecycle
 
-### B. Answering Questions (When a specific file or area is known)
-When the user asks a question and you know (or can infer) which file or area of the codebase it concerns:
-1. Run \`yg owner --file <path>\` for the relevant file(s).
-2. **If owner FOUND:** Run \`yg build-context --node <node_path>\` and base your answer on that context. Do NOT answer from grep/search alone — the graph provides intent, constraints, and relations that yield better answers.
-3. **If owner NOT FOUND:** The file is outside the graph (e.g. third-party code, user's theme/plugin, unmapped area). You may answer from grep/search, but state that the answer is not graph-based.
+\`\`\`
+PREFLIGHT (every conversation, before any work):
+  - [ ] 1. yg preflight → read unified report
+  - [ ] 2. If journal entries: consolidate to graph, then yg journal-archive
+  - [ ] 3. If drift: resolve per Drift Resolution, then yg drift-sync per node
+  - [ ] 4. If validation errors: fix, re-run yg validate
+  Exception: read-only requests (explain, analyze) — skip preflight.
 
-This applies even when you are **not modifying files** — e.g. when providing code snippets to paste elsewhere, explaining behavior, or suggesting hooks. If the question touches mapped code, build-context first.
+UNDERSTANDING mapped code (questions, research, OR planning):
+  - [ ] 1. yg owner --file <path>
+  - [ ] 2. Owner found → yg build-context --node <path>. Use context package as primary source.
+  - [ ] 3. Owner not found → use file analysis, state it is not graph-backed.
+  Never use grep or raw file reads as primary understanding when graph coverage exists.
+  Raw reads supplement the context package — they do not replace it.
 
-### C. Session Verification (Wrap-up)
-Triggered by phrases like: "we're done", "wrap up", "that's enough", "done", "ok".
-**Note: The graph should ALREADY be up to date. If the graph requires massive updates at this stage, YOU HAVE FAILED.**
-1. If iterative journal mode was used: consolidate notes to the graph, then \`yg journal-archive\`.
-2. \`yg drift\` -> If drift detected, run \`yg drift-sync\` for each affected node. Do NOT ask — absorb automatically.
-3. \`yg validate\` -> Fix any structural errors.
-4. Report exactly what nodes and files were changed.
+WRAP-UP (user signals "done", "wrap up", "that's enough"):
+  - [ ] 1. Consolidate journal if used → yg journal-archive
+  - [ ] 2. yg drift --drifted-only → resolve
+  - [ ] 3. yg validate → fix errors
+  - [ ] 4. Report: which nodes and files were changed
+\`\`\`
 
----
+### Modify Source Code
 
-## 3. WORKFLOW: MODIFYING OR CREATING FILES (Code-First)
+You are not allowed to edit or create source code without establishing graph coverage first.
 
-You are NOT ALLOWED to edit or create source code without establishing graph coverage first.
+**Step 1** — Check coverage: \`yg owner --file <path>\`
 
-**Gate:** Before using any tool that modifies files, you MUST have run \`yg owner --file <path>\` for each file you intend to modify. If you have not — run it first, then proceed. No exceptions. Gate applies to **source files** (files outside \`.yggdrasil/\`). For graph files (\`.yggdrasil/model/\`, \`.yggdrasil/aspects/\`, etc.), follow the Graph Modification Checklist in section 4 instead.
+**Step 2a** — Owner found: execute checklist:
 
-**Step 1: Check coverage** -> Run \`yg owner --file <path>\`
+- [ ] 1. Read specification: \`yg build-context --node <node_path>\`
+- [ ] 2. Assess blast radius: \`yg impact --node <node_path>\` — review dependents, descendants, and co-aspect nodes before changing interfaces or shared behavior
+- [ ] 3. Modify source code
+- [ ] 4. Sync graph artifacts — edit artifact files to reflect the changes
+- [ ] 5. Run \`yg validate\` — fix all errors (if unfixable after 3 attempts → stop, report to user)
+- [ ] 6. Run \`yg drift-sync --node <node_path>\` — only after graph and code are both current
 
-**Step 2: If Owner FOUND (The Execution Checklist)**
-Whenever you write or edit source code, you MUST output this exact checklist in your response to the user, and execute each step BEFORE finishing your turn:
+**Step 2b** — Owner not found: establish coverage first. Present options to the user:
 
-- [ ] 1. Read Specification (ran \`yg build-context\`)
-- [ ] 2. Modify Source Code
-- [ ] 3. Sync Graph Artifacts (manually edit the node's artifact files IMMEDIATELY to match new code behavior)
-- [ ] 4. Baseline Hash (ran \`yg drift-sync\` ONLY AFTER updating the graph)
+*Partially mapped* (file unmapped but inside a mapped module): ask whether to add to existing node or create new one.
 
-**Step 3: If Owner NOT FOUND (Uncovered Area)**
-STOP. Do not modify the code. First determine: **Is this greenfield or existing code?**
+*Existing code:*
 
-* **If GREENFIELD (empty directory, new project):** Do NOT offer blackbox. Create proper nodes (reverse engineering or upfront design) before implementing.
-* **If PARTIALLY MAPPED (file is unmapped, but lives inside a mapped module):** Stop and ask the user if this file should be added to the existing node or if a new node is required.
-* **If EXISTING CODE (legacy, third-party):** Present the user with 3 options and wait:
-  * **Option 1: Reverse Engineering:** Create/extend standard nodes to map the area fully before modifying.
-  * **Option 2: Blackbox Coverage:** Create a \`blackbox: true\` node to establish ownership without deep semantic exploration.
-  * **Option 3: Abort/Change Plan:** Do not touch the file.
+- Option A — Full node: create node(s), map files, write artifacts from code analysis
+- Option B — Blackbox: create a blackbox node at agreed granularity
+- Option C — Abort
 
-**Reverse engineering order:** When reverse-engineering an area, create graph elements in this order: (1) aspects, (2) flows, (3) knowledge elements, (4) model nodes. Never create model nodes before cross-cutting rules and shared wisdom exist — they depend on them.
+*Greenfield (new code):* Only Option A. Blackbox is forbidden for new code. Follow the graph-first workflow:
 
----
+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 — responsibility, constraints, decisions, interface, logic
+4. Review the context package (\`yg build-context\`) — 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)
 
-## 4. WORKFLOW: MODIFYING THE GRAPH & BLAST RADIUS (Graph-First)
+After the user chooses, return to Step 1 and follow Step 2a.
 
-When adding features, changing architecture, or doing graph-first design:
+### Modify Graph
 
-1. **Check Blast Radius:** Before modifying a node that others depend on, run \`yg impact --node <node_path> --simulate\`. Report the impact to the user.
-2. **Read Config & Templates:**
-   * Check \`.yggdrasil/config.yaml\` for allowed \`node_types\` and \`tags\`.
-   * **CRITICAL:** ALWAYS read the schema in \`.yggdrasil/templates/\` for the element type (node.yaml, aspect.yaml, flow.yaml, knowledge.yaml) before creating or editing it.
-3. **Validate & Fix:** Run \`yg validate\`. You must fix all E-codes (Errors).
-4. **Token Economy & W-codes:**
-   * W005/W006: Context package too large. Consider splitting the node.
-   * W008: Stale semantic memory. Update knowledge artifacts.
+- [ ] 1. Read the relevant schema from \`schemas/\` before touching any YAML
+- [ ] 2. Before changing an aspect or flow, check scope: \`yg impact --aspect <id>\` or \`yg impact --flow <name>\` — understand which nodes are affected before modifying shared rules or processes
+- [ ] 3. Make changes
+- [ ] 4. Run \`yg validate\` immediately — fix all errors
+- [ ] 5. Verify affected source files are consistent — update if needed
+- [ ] 6. Run \`yg drift-sync\` for affected nodes
 
-**Graph Modification Checklist**
-Whenever you change the graph structure or semantics, you MUST output and execute this exact checklist:
+### Reverse Engineering
 
-- [ ] 1. Read schema from \`.yggdrasil/templates/\` (node.yaml, aspect.yaml, flow.yaml, or knowledge.yaml for the element type)
-- [ ] 2. Edit graph files (\`node.yaml\`, artifacts)
-- [ ] 3. Verify corresponding source files exist and their behavior matches updated artifacts
-- [ ] 4. Validate (ran \`yg validate\` — fix all Errors)
-- [ ] 5. Baseline Hash (ran \`yg drift-sync\` ONLY AFTER steps 2-3 are confirmed)
+**Order:** aspects (cross-cutting patterns) → flows (business processes) → model nodes. Never create nodes before aspects and flows are understood.
 
-**Journaling (Iterative Mode Scope):**
-* **Default:** Write changes directly to graph files immediately. Do not defer.
-* **Opt-in:** ONLY if the user says "use iterative mode" or "use journal". Once activated, it remains active for the ENTIRE conversation until wrap-up. Use \`yg journal-add --note "..."\` to buffer intent.
+Per area checklist:
 
----
+- [ ] 1. \`yg owner --file <path>\` — confirm no coverage
+- [ ] 2. Determine node granularity — propose to user if unclear
+- [ ] 3. Create node directory, read \`schemas/node.yaml\`, create \`node.yaml\`
+- [ ] 4. Analyze source — for each artifact type in \`config.artifacts\`: extract content, do not invent
+- [ ] 5. Identify relations — add to \`node.yaml\`
+- [ ] 6. Identify cross-cutting requirements — add matching aspects, create if needed
+- [ ] 7. Identify business process participation — add to flow, ask user if process unclear
+- [ ] 8. \`yg validate\` — fix errors
+- [ ] 9. \`yg drift-sync --node <path>\`
 
-## 5. PATH CONVENTIONS (CRITICAL)
+**When to ask:**
 
-To avoid broken references (\`E004\`, \`E005\`), use correct relative paths:
-* **Node paths** (used in CLI, relations, flow nodes): Relative to \`.yggdrasil/model/\` (e.g., \`orders/order-service\`).
-* **File paths** (used in mapping, \`yg owner\`): Relative to the repository root (e.g., \`src/modules/orders/order.service.ts\`).
-* **Knowledge paths** (used in node explicit refs): Relative to \`.yggdrasil/knowledge/\` (e.g., \`decisions/001-event-sourcing\`).
+- 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\`.
 
----
+### Bootstrap Mode
 
-## 6. GRAPH STRUCTURE, CONFIG & TEMPLATES CHEAT SHEET
+Trigger: \`yg preflight\` shows 0 nodes, or no nodes cover the active work area.
 
-The graph lives entirely under \`.yggdrasil/\`. You NEVER guess structure. You MUST ALWAYS read the corresponding schema reference in \`.yggdrasil/templates/\` before creating or editing any graph file.
+- [ ] 1. Identify the active work area (files the user wants to modify)
+- [ ] 2. Scan for cross-cutting patterns → create aspects
+- [ ] 3. Ask user about business processes → create flows if applicable
+- [ ] 4. Propose node structure for the area
+- [ ] 5. Create node(s) with initial artifacts, map files
+- [ ] 6. \`yg validate\`, \`yg drift-sync\`
+- [ ] 7. Proceed with user's original request
 
-* **\`.yggdrasil/config.yaml\`**: Defines \`node_types\`, \`tags\`, \`artifacts\`, \`knowledge_categories\`.
-* **\`.yggdrasil/templates/\`**: Schemas for each graph layer — \`node.yaml\`, \`aspect.yaml\`, \`flow.yaml\`, \`knowledge.yaml\`.
-* **\`.yggdrasil/model/\`**: Node tree. Each node is a directory with \`node.yaml\` and artifact files.
-* **\`.yggdrasil/aspects/\`**: Cross-cutting rules. Directory contains \`aspect.yaml\` and \`.md\` content.
-* **\`.yggdrasil/flows/\`**: End-to-end processes. Directory contains \`flow.yaml\` and \`.md\` content.
-* **\`.yggdrasil/knowledge/\`**: Repo-wide wisdom. Directory contains \`knowledge.yaml\` and \`.md\` content.
+Constraint: Do NOT map the entire repository. Focus on the active area. Expand incrementally.
 
----
+### Drift Resolution
 
-## 7. CONTEXT ASSEMBLY & KNOWLEDGE DECONSTRUCTION (HOW TO MAP FILES)
+Always ask the user before resolving drift. Never auto-resolve.
 
-Your ultimate goal when describing a file or node is **Context Reproducibility**. A future agent reading ONLY the output of \`yg build-context\` for this node must be able to perfectly reconstruct the source code's behavior, constraints, environment, and purpose.
+- **Source drift** (source files changed) → update graph artifacts to match source, then \`yg drift-sync\`
+- **Graph drift** (graph artifacts changed) → review affected source, update if needed, then \`yg drift-sync\`
+- **Full drift** (both changed) → present both sides to user, ask which direction wins
+- **Missing** → ask: re-materialize or remove mapping?
+- **Unmaterialized** → ask user how to proceed
 
-However, you must NOT dump all knowledge into a single file. Yggdrasil's context package is **multi-layered** and hierarchically assembled. When you map existing code or design new code, you must deconstruct the knowledge and place it at the correct abstraction layer so the engine can mechanically reassemble it.
+Threshold: >10 drifted nodes → ask user which area to prioritize. Do not resolve all at once.
 
-### CRITICAL RULE: CAPTURE INTENT, BUT NEVER INVENT IT
-The graph is not just a structural map; it is the semantic meaning of the system. Code explains "what" and "how". The graph MUST explain "WHY".
+### Error Recovery
 
-1. **ALWAYS Capture the User's "Why":** If the user explains the business reason, intent, or rationale behind a request (e.g., "We need to do X because Y"), you MUST permanently record this reasoning in the relevant graph artifacts (from \`config.artifacts\` that fit the content). Do not let the conversation context evaporate.
-2. **NEVER Invent the "Why":** Artifacts that imply human judgment (e.g. local decisions, \`knowledge/invariants\`) must reflect ACTUAL human choices.
-3. **NO Hallucinations:** You MUST NEVER infer or hallucinate a rationale, an architectural decision, or a business rule.
-4. **Ask if Missing:** If the user requests a significant architectural or business logic change but does not provide the rationale, you MUST ask them "Why are we making this change?" before documenting the decision in the graph.
+- **\`yg\` not found** → inform user: "yg CLI is not installed or not in PATH." Stop.
+- **Unfixable validate errors** → if not resolved after 3 attempts, stop and report to user. Do not loop.
+- **Budget exceeded** → if \`yg build-context\` exits with error (context package exceeds budget), warn user: "This node should be split." Do not proceed with implementation.
+- **Corrupted \`.yggdrasil/\` files** → report to user. Do not attempt repair.
+- **Incremental sync** → run \`yg drift-sync\` every 3-5 source files during multi-file tasks. Do not defer to end.`;
 
-When mapping a file, execute this mental routing:
+// prettier-ignore
+const KNOWLEDGE_BASE = `## KNOWLEDGE BASE
 
-### Layer 1: Unit Identity (Local Node Artifacts)
-* **What goes here:** Things exclusively true for this specific node.
-* **Routing:** **DO NOT ASSUME FILE NAMES.** You MUST read \`.yggdrasil/config.yaml\` (the \`artifacts\` section) to see the exact allowed filenames for the current project and their requirement conditions (e.g., \`required: always\` vs \`when: has_incoming_relations\`). Write local node knowledge ONLY into these configured files next to \`node.yaml\`.
-* For each artifact in \`config.artifacts\`, use its \`description\` to decide what content belongs there. Create optional artifacts (those with \`required: never\`) when the node has matching content. Extract from source; do not invent.
+### Graph Structure
 
-**Subagents:** When mapping a node, for each optional artifact in config, ask: "Does the source contain content matching this artifact's description?" If yes, create it. Do not invent — extract only what is implemented.
-
-### Optional Artifacts — Explicit Consideration
-
-When creating or editing a graph node, or mapping source files to a node, after fulfilling required artifacts, read \`config.yaml\` and for each artifact with \`required: never\`, ask: "Does this node contain content that matches this artifact's description?" If yes, create it. Base decisions on source code analysis, not file names or structure.
-
-**Interpretation of \`required: never\`:** The artifact is optional for validation, not forbidden. Create it when the node has content that fits its description in config.
-
-**Interpretation of "don't be over-eager":** Do not invent content, do not document what is not in the code, do not create empty or trivial artifacts. It does NOT mean: avoid adding optional artifacts when they add value based on code analysis.
-
-**Post-node checklist:** After completing work on a node, for each optional artifact (from \`config.artifacts\` where \`required: never\`), check: does this node have content for it? If yes, create it. If uncertain, propose with brief justification rather than silently skipping.
-
-### Layer 2: Surroundings (Relations & Flows)
-* **What goes here:** How this node interacts with others. You must not duplicate external interfaces locally.
-* **Routing:**
-  * If it calls another module: Add an outgoing structural \`relation\` in \`node.yaml\`. (The engine will automatically fetch the target's structural-context artifacts: responsibility, interface, constraints, errors).
-  * If it participates in an end-to-end process: Do not explain the whole process locally. Ensure the node is listed in \`.yggdrasil/flows/<flow_name>/flow.yaml\`. The engine will attach the flow knowledge automatically.
-* **Flows — writing flow content:** When creating or editing flow artifacts (e.g. \`description.md\` in \`flows/<name>/\`), write business-first: describe the process from user/business perspective. Technical details only as inserts when they clarify the flow. Not technical-first with business inserts.
-
-### Layer 3: Domain Context (Hierarchy)
-* **What goes here:** Business rules shared by a family of nodes.
-* **Routing:** Do not repeat module-wide rules in every child node. Place the child node directory *inside* a parent Module Node directory. Write the shared rules in the parent's configured artifacts. The engine inherently passes parent context to children.
-
-### Layer 4: Cross-Cutting Rules (Aspects)
-* **What goes here:** Horizontal requirements like logging, auth, rate-limiting, or specific frameworks.
-* **Routing:** Do NOT write generic rules like "This node must log all errors" in local artifacts. Instead, read \`config.yaml\` for available \`tags\`. Add the relevant tag (e.g., \`requires-audit\`) to \`node.yaml\`. The engine will automatically attach the aspect knowledge.
-
-### Layer 5: Long-Term Memory (Knowledge Elements)
-* **What goes here:** Global architectural decisions, design patterns, and systemic invariants.
-* **Routing:** Read \`config.yaml\` (the \`knowledge_categories\` section) to know what categories exist.
-  * If the file implements a standard pattern: Do not describe the pattern locally. Add a \`knowledge\` reference in \`node.yaml\` to the existing pattern.
-  * If the file reveals an undocumented global invariant or decision: Ask the user to confirm it. If confirmed, create it under \`.yggdrasil/knowledge/<category>/\` so all future nodes inherit it.
-
-**THE COMPLETENESS CHECK:**
-Before finishing a mapping, ask yourself: *"If I delete the source file and give another agent ONLY the output of \`yg build-context\`, can they recreate it perfectly based on the configured artifacts, AND will they understand EXACTLY WHY this code exists and why it was designed this way?"*
-- If no -> You missed a local constraint, a relation, or you failed to capture the user's provided rationale.
-- If yes, but the local files are bloated -> You failed to deconstruct knowledge into Tags, Aspects, Flows, and Hierarchy. Fix the routing.
-
----
-
-## 8. CLI TOOLS REFERENCE (\`yg\`)
-
-Always use these exact commands.
-
-* \`yg owner --file <file_path>\` -> Find owning node.
-* \`yg build-context --node <node_path>\` -> Assemble strict specification.
-* \`yg tree [--root <node_path>] [--depth N]\` -> Print graph structure.
-* \`yg deps --node <node_path> [--type structural|event|all]\` -> Show dependencies.
-* \`yg impact --node <node_path> --simulate\` -> Simulate blast radius.
-* \`yg status\` -> Graph health metrics.
-* \`yg validate [--scope <node_path>|all]\` -> Compile/check graph. Run after EVERY graph edit.
-* \`yg drift [--scope <node_path>|all]\` -> Check code vs graph baseline.
-* \`yg drift-sync --node <node_path>\` -> Save current file hash as new baseline. Run ONLY after ensuring graph artifacts match the code.
-
-*(Iterative mode only)*
-* \`yg journal-read\`
-* \`yg journal-add --note "<content>" [--target <node_path>]\`
-* \`yg journal-archive\`
+\`\`\`
+.yggdrasil/
+  config.yaml        ← vocabulary, stack, node types, artifact rules, required aspects
+  model/             ← what exists: nodes, hierarchy, relations, file mappings
+  aspects/           ← what must: cross-cutting requirements with rationale and guidance
+  flows/             ← why and in what process: business processes with node participation
+  schemas/           ← YAML schemas — read before creating any graph element
+  .drift-state       ← generated by CLI; never edit manually
+  .journal.yaml      ← generated by CLI; never edit manually
+\`\`\`
+
+Key facts:
+
+- **Hierarchy:** nodes nest in \`model/\`. Children inherit parent context. Do not repeat parent content in children.
+- **Aspect id = directory path** under \`aspects/\`. Each aspect has \`aspect.yaml\` + content \`.md\` files. No automatic parent-child — use \`implies\` explicitly.
+- **Flows = business processes.** A flow describes what happens in the world, not code sequences. Flow aspects propagate to all participants.
+
+### Context Assembly
+
+Run \`yg build-context --node <path>\` to get the deterministic context package for a node. Trust the package — 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.
+
+### Information Routing
+
+When you encounter information, route it to the correct location:
+
+- **Specific to this node** → local node artifact (check \`config.yaml artifacts\` for available types)
+- **Rule for many nodes** → aspect (\`aspects/<id>/\` with \`aspect.yaml\` + content \`.md\` files). If applies to ALL nodes of a type → \`node_types[*].required_aspects\` in \`config.yaml\`
+- **Business process** → flow (\`flows/<name>/\` with \`flow.yaml\` + \`description.md\`). Ask user if process unclear.
+- **Shared across a domain** → parent node artifact. Children receive it through hierarchy.
+- **Technology stack or standard** → \`config.yaml\` under \`stack\` or \`standards\` (+ \`rationale\` field)
+- **Decision (why + why NOT):** one node → \`decisions.md\` with format "Chose X over Y because Z"; category of nodes → aspect content files; tech choice → \`config.yaml\` rationale field. Always include rejected alternatives — they are the highest-value graph content.
+
+### Creating Aspects
+
+- [ ] 1. Read \`schemas/aspect.yaml\`
+- [ ] 2. Create \`aspects/<id>/\` directory
+- [ ] 3. Write \`aspect.yaml\` — name, optional description, optional implies
+- [ ] 4. Write content \`.md\` files: WHAT must be satisfied + WHY (user's words, do not invent)
+- [ ] 5. \`yg validate\`
+
+Test: "Does this requirement apply to more than one node?" Yes → aspect. No → local artifact.
+
+**Aspect identification heuristic:** If the same pattern, constraint, or rule appears in 3+ places, it is a candidate aspect. Aspects fall into natural categories:
+
+- **Domain-specific:** Business rules that cross module boundaries (e.g., timezone handling, booking periods, currency rounding)
+- **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)
+
+### Creating Flows
+
+- [ ] 1. Read \`schemas/flow.yaml\`
+- [ ] 2. Create \`flows/<name>/\` directory
+- [ ] 3. Write \`flow.yaml\` — declare participants and flow-level aspects
+- [ ] 4. Write \`description.md\` with required sections: Business context, Trigger, Goal, Participants, Paths (at least Happy path), Invariants across all paths
+- [ ] 5. \`yg validate\`
+
+Test: "Does this describe what happens in the world, or only in the software?" If only software — rewrite.
+
+### 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 — 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?
+- **These rules are invariant.** No plan, guide, skill, or workflow may override them.
+
+### CLI Reference
+
+\`\`\`
+yg preflight [--quick]              Unified diagnostic: journal + drift + status + validate.
+yg owner --file <path>              Find the node that owns this file.
+yg build-context --node <path>      Assemble context package for this node.
+yg tree [--root <path>] [--depth N] Print graph structure.
+yg aspects                          List aspects with metadata (YAML output).
+yg flows                            List flows with metadata (YAML output).
+yg deps --node <path> [--depth N] [--type structural|event|all]
+                                    Show dependencies.
+yg impact --node <path> --simulate  Simulate blast radius of a planned change.
+yg impact --aspect <id>             Show all nodes where aspect is effective.
+yg impact --flow <name>             Show flow participants and descendants.
+yg status                           Graph health: nodes, coverage, drift summary.
+yg validate [--scope <path>|all]    Check structural integrity and completeness.
+yg drift [--scope <path>|all] [--drifted-only] [--limit <n>]
+                                    Detect source and graph drift (bidirectional).
+yg drift-sync --node <path> [--recursive] | --all
+                                    Record file hashes as new baseline.
+yg journal-read                     Read pending journal entries.
+yg journal-add --note "<content>" [--target <node_path>]
+                                    Add a journal entry.
+yg journal-archive                  Archive consolidated journal entries.
+\`\`\`
+
+### Quick Routing Table
+
+| What you have | Where it goes |
+|---|---|
+| Information specific to this node | Local node artifact (read \`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\` |
 `;
+
+export const AGENT_RULES_CONTENT = [CORE_PROTOCOL, OPERATIONS, KNOWLEDGE_BASE].join('\n\n---\n\n');

package/graph-schemas/aspect.yaml

@@ -0,0 +1,9 @@
+# aspect.yaml — Schema for cross-cutting aspects
+# Each aspect is a directory under .yggdrasil/aspects/ containing this file
+# plus any number of .md content files (requirements, rationale, guidance).
+# Aspect identifier = relative path from aspects/ to the directory (e.g. observability/logging).
+# Aspects can be organized in nested directories for hierarchy.
+
+name: CrossCuttingRequirementName  # required — display name
+description: "Short description for discovery via yg aspects"  # optional
+# implies: [other-aspect, another-aspect] # optional — other aspect identifiers included automatically (recursive, must be acyclic)