@chrisdudek/yg 4.0.2 → 4.1.0

package/dist/bin.js

@@ -28,6 +28,13 @@ You verify whether source code satisfies a requirement.
 Below is a node (component) with its source files and one aspect (rule set).
 Check every rule in the aspect against the source code.
 
+If source code contains a comment with the marker yg-suppress(<aspect-id>) where
+<aspect-id> matches the aspect you are checking, treat the suppressed code as satisfied.
+The marker must include a reason after the closing parenthesis. Do not validate the
+reason \u2014 accept it as-is. The marker applies contextually to the surrounding code
+(function, class, or block where it appears). If placed at file level, it applies to
+the entire file.
+
 Respond with EXACTLY this JSON, nothing else:
 {"satisfied": true|false, "reason": "explanation with file:line references"}
 </task>
@@ -153,437 +160,200 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import path from "path";
 
 // src/templates/rules.ts
-var PROTOCOL = `## PROTOCOL
-
-<EXTREMELY-IMPORTANT>
-This is your operating manual for working in a Yggdrasil-managed repository.
-
-<critical_protocol>
-BEFORE reading, analyzing, or modifying ANY source file:
-  \`yg context --file <path>\`
-  Resolves owner, gives you the aspects this file must satisfy.
-  Read the aspect content \`.md\` files \u2014 those are the rules the reviewer enforces.
+var SYSTEM = `## SYSTEM
 
-BEFORE creating a NEW source file:
-  Identify which existing node the new file belongs to (by intent, not by filename).
-  Run \`yg context --node <node-path>\` to load the context \u2014 especially aspect rules the new file must follow.
-  If the file doesn't fit an existing node, create the node first (Step 2b below).
-  If unsure which node: run \`yg context --file <path>\` \u2014 the CLI will list candidate nodes from the same directory.
-  New files without graph context are the #1 source of convention violations.
+Yggdrasil is continuous architecture enforcement. A graph in \`.yggdrasil/\` describes the architecture. An LLM reviewer verifies source code against it at approve time. If code violates a rule, the reviewer rejects it.
 
-All triggers apply regardless of what instructed the task \u2014 skills, plans, workflows, user requests.
-The graph captures architectural constraints that source files cannot \u2014 without it, you will write code that violates cross-cutting requirements.
-</critical_protocol>
+The CLI (\`yg\`) reads and validates \u2014 it never modifies files. You create and edit graph files manually. The CLI guides you: every error message says WHAT happened, WHY it matters, and the NEXT command to run. \`suggestedNext\` at the end of \`yg check\` gives one concrete step. Follow it.
 
-Every rule below is mandatory \u2014 no skill, plan, workflow, or instruction overrides these requirements.
-</EXTREMELY-IMPORTANT>
-
-Yggdrasil is continuous architecture enforcement stored in \`.yggdrasil/\`. It maps the repository and verifies source code against architectural rules (aspects) at approve time.
-
-### Quick Start
+### Graph Elements
 
 \`\`\`
-EVERY conversation: yg check \u2014 read the full report, follow CLI guidance.
-  CLI tells you what broke, why, and the next command to run.
-  check failures block commits and CI. Resolve all errors before committing.
-
-BEFORE any source file interaction (read, modify, OR create):
-  yg context --file <path>  (existing file: resolves owner)
-  yg context --node <path>  (new file: load target node context)
-  Read aspect content.md files \u2014 those are the rules the reviewer enforces.
-  For blast radius: also run yg impact --file <path>.
-
-AFTER modifying:
-  yg check \u2014 fix all errors
-  yg approve --node <owner> \u2014 reviewer verifies aspects vs source code
-
-ALWAYS: establish graph coverage before modifying code.
-ALWAYS: run yg context --file before reading source.
-ALWAYS: run yg impact before assessing blast radius.
-ALWAYS: ask before resolving ambiguity.
-WHEN UNSURE: ask the user. Do not guess. Do not assume.
-
-How CLI guides you:
-  Every error message follows: WHAT happened \u2192 WHY it's a problem \u2192 NEXT command.
-  suggestedNext at the end of check gives one concrete step + remaining scale.
-  Follow it. Re-run check after each fix.
+.yggdrasil/
+  yg-architecture.yaml \u2190 node type definitions, default aspects per type, allowed relations
+  yg-config.yaml       \u2190 reviewer config, quality thresholds, parallelism
+  model/               \u2190 nodes: what exists \u2014 hierarchy, relations, file mappings
+  aspects/             \u2190 aspects: what must be satisfied \u2014 enforceable rules
+  flows/               \u2190 flows: business processes with node participation
+  schemas/             \u2190 YAML schemas \u2014 read before creating any graph element
+  .drift-state/        \u2190 generated by CLI; never edit manually
 \`\`\`
 
-### Modify Source Code
-
-You are not allowed to edit or create source code without establishing graph coverage first.
-
-**Step 1** \u2014 Get context: \`yg context --file <path>\` (resolves owner automatically)
-
-**Step 2a** \u2014 Owner found: execute checklist:
-
-- [ ] 1. \`yg context --file <path>\` \u2014 note all aspects in "Must satisfy"
-- [ ] 2. **Read aspect content files.** For every aspect in "Must satisfy": open and read its content \`.md\` files. The aspect description is not sufficient \u2014 the content files contain the actual enforcement rules. \`yg approve\` (step 6) delegates to a reviewer that checks source code against these rules and rejects non-compliant code.
-- [ ] 3. Assess blast radius: \`yg impact --node <node_path>\`
-- [ ] 4. Modify source code \u2014 satisfy the aspect rules
-- [ ] 5. Run \`yg check\` \u2014 follow CLI's suggested next command (if unfixable after 3 attempts \u2192 stop, report to user)
-- [ ] 5b. If you split, merged, or renamed a node: run \`yg flows\` and update any flow \`nodes\` lists that referenced the old node path.
-- [ ] 5c. **Aspect check** \u2014 did you just apply a pattern that also exists in other files? If the node has no aspect for it and you saw the same pattern in 3+ files, create the aspect now.
-- [ ] 6. Run \`yg approve --node <node_path>\` \u2014 reviewer verifies aspects vs source code
-
-**Step 2b** \u2014 Owner not found: establish coverage first. Present options to the user:
+**Nodes** \u2014 components. \`model/<path>/yg-node.yaml\` with name, type, description, mapping (source files), relations, aspects, ports. Nodes nest by directory \u2014 children inherit parent aspects.
 
-*Partially mapped* (file unmapped but inside a mapped module): ask whether to add to existing node or create new one.
+**Aspects** \u2014 enforceable rules. \`aspects/<id>/yg-aspect.yaml\` + content \`.md\` files. The content files are what the reviewer checks against source code. An aspect can declare \`implies: [other-aspect]\` \u2014 implied aspects are included recursively (must be acyclic).
 
-*Existing code:*
+**Flows** \u2014 business processes. \`flows/<name>/yg-flow.yaml\` with name, description, nodes (participants), aspects. Flow-level aspects propagate to all participants. Descendants of a declared participant are automatically included \u2014 adding a parent node to a flow covers all its children.
 
-- Option A \u2014 Proper node: create node(s), map files, write description in \`yg-node.yaml\`
-- Option B \u2014 Abort
+**Relations** \u2014 typed dependencies between nodes. Six types: \`calls\`, \`uses\`, \`extends\`, \`implements\` (structural) and \`emits\`, \`listens\` (event-based). Event relations must be paired \u2014 if A emits to B, B must have a listens from A. Architecture controls which relation types are allowed between which node types.
 
-*Greenfield (new code):* Only Option A. Follow the graph-first workflow:
+**Ports** \u2014 named entry points on a node with required aspects. A node declares ports to say "consumers of this endpoint must satisfy these aspects." Consumers reference ports via \`consumes\` on their relation. The consumed port's aspects become effective on the consumer (channel 6). If a target has ports, the consumer must declare which it consumes \u2014 otherwise check warns about missing port contracts.
 
-1. Create aspects first (cross-cutting requirements the new code must satisfy)
-2. Create flows if the code participates in a business process (with flow-level aspects)
-3. Create nodes: \`yg-node.yaml\` with description, mapping, relations, aspects
-4. Review the context package (\`yg context\`) \u2014 aspects are the specification
-5. Implement code that satisfies aspect rules. Every source file must be mapped.
-6. \`yg check\`, \`yg approve\`
+**Architecture** \u2014 \`yg-architecture.yaml\` defines the vocabulary: node types, default aspects per type, allowed parent types, allowed relation targets per type. This is the foundation \u2014 read it when starting work on a new repo. Changes require user confirmation. Structure details in \`schemas/yg-architecture.yaml\`.
 
-**Node sizing rule:** One node per cohesive feature area, NOT per directory. If a node would map >10 source files or cover >3 distinct user workflows, split it into child nodes.
+### How Aspects Reach a Node \u2014 7 Channels
 
-**Why sizing matters for enforcement:** The reviewer verifies aspects against ALL source files in a node. A node with too many files forces the reviewer to evaluate aspects across too much code \u2014 it may reject compliant code because it lacks focused context. Smaller nodes (2-5 source files) give the reviewer enough context to verify accurately. Design nodes so that every mapped file is relevant to every aspect on that node.
-
-**\`wide-node\` warning:** \`yg check\` emits a \`wide-node\` warning when a node with aspects maps more source files than \`quality.max_mapping_source_files\` (default: 10). This warning means: the reviewer WILL struggle with this node. Split it before running \`yg approve\` \u2014 otherwise expect false rejections.
-
-After the user chooses, return to Step 1 and follow Step 2a.
-
-### Working from External Specifications
-
-When the user provides external documents (specs, PRDs, design docs, reference docs) as input for implementation:
-
-1. **Read ALL spec documents BEFORE writing any code.** Understand the full scope.
-2. **Extract enforceable requirements as aspects FIRST** \u2014 these are the rules the reviewer will check.
-3. **The graph enforces architecture; external docs are INPUT to the graph, not a parallel source of truth.**
-4. **Non-enforceable knowledge** (business strategy, personas, pricing) is not captured in the graph. Enforceable rules go to aspects.
-
-### Conversation Lifecycle
+Aspects accumulate from multiple sources simultaneously. The reviewer checks ALL of them \u2014 the node must satisfy every aspect regardless of origin.
 
 \`\`\`
-START (every conversation, before any work):
-  - [ ] 1. yg check \u2192 read full report
-  - [ ] 2. Fix any errors before starting work
-  No exceptions. You cannot know if a file is mapped without running yg.
-
-UNDERSTANDING any source file (questions, research, OR planning):
-  - [ ] 1. yg context --file <path>
-         Mapped \u2192 read structured text output. Aspect content files are listed with "read:" prefix \u2014 read them.
-         Unmapped \u2192 use file analysis, state it is not graph-backed.
-  Never use grep or raw file reads as primary understanding when graph coverage exists.
-
-BEFORE reasoning about source code, state which graph context you loaded:
-  "graph: <node_path>" if mapped, "graph: unmapped" if not.
-
-WRAP-UP (user signals "done", "wrap up", "that's enough"):
-  - [ ] 1. yg check \u2192 fix all errors
-  - [ ] 2. Report: which nodes and files were changed
+EXAMPLE: node "orders/handler" (type: command, child of "orders")
+
+Channel 1: OWN         \u2014 node.aspects: [input-validation]
+Channel 2: ANCESTOR    \u2014 parent "orders" has aspects: [audit-logging]
+Channel 3: OWN TYPE    \u2014 architecture says type "command" \u2192 [cli-command-contract]
+Channel 4: ANCESTOR TYPE \u2014 parent "orders" type "module" \u2192 [] (no defaults here)
+Channel 5: FLOWS       \u2014 flow "order-processing" includes "orders" \u2192 flow aspects: [deterministic]
+Channel 6: PORTS       \u2014 relation to "payments/service" consumes port "charge" \u2192 [correlation-tracking]
+Channel 7: IMPLIED     \u2014 aspect "audit-logging" implies: [diagnostic-logging]
+
+EFFECTIVE ASPECTS for "orders/handler":
+  input-validation      \u2190 own
+  audit-logging         \u2190 parent "orders"
+  cli-command-contract  \u2190 architecture type "command"
+  deterministic         \u2190 flow "order-processing" (via parent "orders")
+  correlation-tracking  \u2190 port "charge" on "payments/service"
+  diagnostic-logging    \u2190 implied by "audit-logging"
 \`\`\`
 
-### Modify Graph
-
-- [ ] 1. Read the relevant schema from \`schemas/\` before touching any YAML
-- [ ] 2. Before changing an aspect or flow, check blast radius: \`yg impact --aspect <id>\` or \`yg impact --flow <name>\` \u2014 understand which nodes are affected before modifying shared rules or processes
-- [ ] 3. Make changes
-- [ ] 4. Run \`yg check\` immediately \u2014 fix all errors
-- [ ] 5. Verify affected source files are consistent \u2014 update if needed
-- [ ] 6. Run \`yg approve\` for affected nodes
-
-### Architecture Ownership
-
-\`yg-architecture.yaml\` defines which node types exist, what each type means, and which relations are allowed between types. **Every change to this file requires user confirmation** \u2014 it defines the vocabulary and constraints for the entire graph.
-
-**On a new or empty repo:** Do NOT accept the defaults silently. Read \`yg-architecture.yaml\`, present the current types and relation rules to the user, and ask: "Does this type system fit your project, or should we adjust it?" The default types are starting points, not answers.
-
-**Before creating nodes with relations:** Read \`yg-architecture.yaml\` to check which relation types are allowed between the source and target node types. Do not guess \u2014 if the architecture does not allow \`service\` to call \`data\`, you cannot create that relation. The options are:
-1. Use an allowed relation type
-2. Ask the user whether to update the architecture (explain the constraint)
-3. Change the node type to one that allows the needed relation
+Consequences of this cascade:
+- Adding an aspect to a parent applies it to ALL children. Check impact first: \`yg impact --aspect <id>\`.
+- Adding a node to a flow with aspects means that node must satisfy flow aspects.
+- Architecture default aspects apply to every node of that type automatically.
+- Implies chains expand recursively. Cycles are forbidden \u2014 CLI detects them.
 
-**Never silently modify \`yg-architecture.yaml\`.** If a relation is forbidden, do NOT add the target type to the allowed list without asking the user first. Present the constraint, explain the options, let the user decide.
+### Reviewer
 
-### Delegating to Subagents
-
-When you delegate work to a subagent (any subprocess, tool agent, or spawned assistant), the subagent does NOT inherit your Yggdrasil knowledge. Before any other instruction, the subagent MUST:
-
-1. Read \`.yggdrasil/agent-rules.md\` \u2014 this is the complete operating manual
-2. Follow the Quick Start Protocol from that file before touching any mapped code
+The reviewer is an LLM invoked by \`yg approve\`. It receives: the aspect's content.md + all source files of the node. It checks every rule from content.md against the code.
 
-Include this as the FIRST instruction in every subagent prompt:
-
-\`\`\`
-BEFORE doing anything else: read .yggdrasil/agent-rules.md and follow its protocol.
-DELIVERABLES \u2014 all required, incomplete work will be rejected:
-  1. Working source code
-  2. Graph nodes for every new/modified source file
-  3. \`yg check\` passing
-\`\`\`
+- **Approved** \u2192 baseline recorded, drift cleared.
+- **Refused** \u2192 violation report with what and where. Fix the code, re-run approve.
 
-A subagent that delivers code without corresponding graph updates has not completed its task.`;
-var REFERENCE = `## REFERENCE
+Three approve modes: \`--node <path>\` (one or more nodes), \`--aspect <id>\` (batch all nodes affected by this aspect change), \`--flow <name>\` (batch all nodes in this flow). Batch at most 3-5 nodes per invocation \u2014 the reviewer loses accuracy with too many. Use \`--dry-run\` to preview the reviewer prompt without making an LLM call.
 
-### Graph Structure
+### Drift and Cascade
 
-\`\`\`
-.yggdrasil/
-  yg-config.yaml     \u2190 project config: reviewer, quality thresholds, parallel
-  yg-architecture.yaml \u2190 node type definitions, default aspects per type
-  model/             \u2190 what exists: nodes, hierarchy, relations, file mappings
-  aspects/           \u2190 what must: cross-cutting requirements \u2014 the ONLY enforcement rules
-  flows/             \u2190 why and in what process: business processes with node participation
-  schemas/           \u2190 YAML schemas \u2014 read before creating any graph element
-  .drift-state/      \u2190 generated by CLI; never edit manually
-\`\`\`
+Drift = source code or upstream context changed since the last approve. The reviewer must verify again. \`yg check\` detects two kinds:
 
-Key facts:
+- **Source drift** \u2014 mapped source files were modified. Fix: \`yg approve --node <path>\`.
+- **Upstream drift (cascade)** \u2014 an aspect, parent node, flow, or dependency changed. This cascades: one aspect change can cause drift in every node that uses it. Fix: \`yg approve --aspect <id>\` or approve affected nodes individually.
 
-- **Hierarchy:** nodes nest in \`model/\`. Children inherit parent aspects. Parent aspects flow to children automatically. **Consequence:** before nesting nodes under a parent, check which aspects the parent has \u2014 every child must satisfy ALL of them. If an aspect applies to the parent but not to a specific child, either move the aspect to the children that need it, or make the child a top-level node instead.
-- **Aspect id = directory path** under \`aspects/\`. Each aspect has \`yg-aspect.yaml\` + content \`.md\` files. Content files contain enforcement rules checked by the reviewer. 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.
-- **Nodes = \`yg-node.yaml\` only.** Name, type, description, mapping, relations, aspects, ports. No \`.md\` files in nodes.
+Cascade is the cost multiplier. Before changing a widely-used aspect, run \`yg impact --aspect <id>\` to see how many nodes will need re-approval. Each is a separate LLM call.
 
-**Node type guidance:** Each type in \`yg-architecture.yaml node_types\` has a \`description\` that tells you when to use it. Check the project's architecture file for the full list and descriptions. Common types: \`module\` (business logic), \`service\` (providing functionality), \`library\` (shared utilities), \`infrastructure\` (guards, middleware, interceptors \u2014 invisible in call graphs but affect blast radius).
+If you modify code without reading the aspect content files (\`yg context --file\` \u2192 follow the \`read:\` paths), you will likely write code that violates rules you didn't know about. The reviewer will reject it. You will have to read the aspects anyway, then rewrite. Double cost.
 
-### Aspect Distribution Channels
+Do not interrupt \`yg approve\` \u2014 it processes each aspect across all source files. Interrupting leaves drift state unrecorded. Always read the full raw output \u2014 no \`| grep\`, \`| head\`, \`| tail\`. The reviewer already ran; the output is the return on that cost.
 
-Every graph dimension is a distribution channel for aspects to nodes:
+### CLI Commands
 
-| Channel | How aspects reach nodes |
+| Command | Purpose |
 |---|---|
-| Direct | \`node.aspects\` in yg-node.yaml |
-| Type | Architecture defines default aspects per node type |
-| Hierarchy | Parent aspects inherited by children |
-| Port | Consumer must satisfy port-required aspects |
-| Flow | Participants inherit flow-level aspects |
-
-### Context Assembly
+| \`yg check\` | Unified gate \u2014 drift, validation, coverage, completeness. Blocks CI. |
+| \`yg context --file <path>\` | Show owning node, effective aspects (\`read:\` paths), dependencies |
+| \`yg context --node <path>\` | Show node overview \u2014 aspects, flows, dependents, source files |
+| \`yg approve --node <path> [<path2>...]\` | Run reviewer on one or more nodes |
+| \`yg approve --aspect <id>\` | Batch approve all nodes affected by this aspect change |
+| \`yg approve --flow <name>\` | Batch approve all nodes in this flow |
+| \`yg approve --dry-run --node <path>\` | Preview reviewer prompt without LLM call |
+| \`yg impact --node <path>\` | Blast radius \u2014 dependents, flows, cascade scope |
+| \`yg impact --file <path>\` | Blast radius for a specific file |
+| \`yg impact --aspect <id>\` | All nodes affected by this aspect |
+| \`yg impact --flow <name>\` | All nodes in this flow |
+| \`yg tree [--root <path>] [--depth <n>]\` | Browse graph structure \u2014 all nodes with type and description |
+| \`yg aspects\` | List all aspects with usage counts and sources |
+| \`yg flows\` | List all flows with participants and aspects |
+| \`yg owner --file <path>\` | Find which node owns a source file |
+| \`yg init\` | Bootstrap or refresh \`.yggdrasil/\` setup |
 
-Two context commands serve different purposes:
+### Impact and Cost
 
-- **\`yg context --node <path>\`** \u2014 node overview: aspects, flows, dependents
-- **\`yg context --file <path>\`** \u2014 per-file: aspects to satisfy, consumed dependencies
+Every graph change has blast radius. \`yg impact\` shows how many nodes are affected. Each affected node is a separate reviewer call (LLM request) during approve. An aspect touching 20 nodes = 20 LLM calls = real cost.
 
-**Reading context:** Both commands output structured text. Aspect content file paths appear with a \`read:\` prefix \u2014 read each one to get the enforcement rules.
+When code doesn't match an aspect, three options:
 
-\`yg context --node <path>\` outputs:
-- **Header** \u2014 node path, description, type
-- **Source files** \u2014 files owned by this node
-- **Must satisfy** \u2014 aspects with paths to content.md files
-- **Participates in** \u2014 flows
-- **Dependencies** \u2014 nodes this node depends on
-- **Dependents** \u2014 count of nodes that depend on this one (consequence framing for blast radius)
-- **Parent** \u2014 parent node
+| Option | When | Cost |
+|---|---|---|
+| **Change code** \u2014 conform to aspect | Aspect is correct, code violates it | Proportional to files needing fixes |
+| **Change aspect** \u2014 conform to code | Aspect is too narrow or wrong, code is correct | \`yg impact --aspect\` \u2192 re-approve ALL nodes with this aspect |
+| **Suppress** \u2014 \`yg-suppress\` waiver | Known tech debt, refactor not now | Zero approve cost, consciously accepted risk |
 
-\`yg context --file <path>\` outputs:
-- **Owner** \u2014 node path and type (or "unmapped" with candidate nodes)
-- **Must satisfy** \u2014 aspects with paths to content.md files
-- **Dependencies consumed** \u2014 what this file uses from each dependency
-- **Node context** \u2014 back-pointer: run \`yg context --node\` for full node overview
+This is a cost/impact trade-off. Assess, propose the option to the user, let them decide. Never choose silently \u2014 especially for options 2 and 3.`;
+var DECISIONS = `## DECISIONS
 
-Read ALL aspect content files listed \u2014 the cost is low, the risk of skipping is high.
+### Workflow
 
-### Information Routing
+**Start of conversation:** \`yg check\`. If errors \u2014 fix before any other work. \`yg check\` failures block commits and CI. Nothing passes until check is clean.
 
-When you encounter information, route it to the correct location:
+**Before touching a source file:** \`yg context --file <path>\`. Read the aspect content files listed under \`read:\`. These are the rules the reviewer will check your code against. For blast radius: \`yg impact --file <path>\`.
 
-- **Enforceable cross-cutting rule** \u2192 aspect (\`aspects/<id>/\` with \`yg-aspect.yaml\` + content \`.md\` files). If applies to ALL nodes of a type \u2192 architecture default aspects.
-- **Business process with participants** \u2192 flow (\`flows/<name>/\` with \`yg-flow.yaml\`). Process-level requirements \u2192 flow aspects.
-- **Node identity** \u2192 \`description\` field in \`yg-node.yaml\` (1-2 sentences).
-- **Already visible in source code** \u2192 not captured in the graph.
-- **Non-enforceable knowledge** (business strategy, personas, design decisions) \u2192 not captured in the graph. If it can be made enforceable, write it as an aspect.
+**After modifying code:** \`yg check\` \u2192 fix errors \u2192 \`yg approve --node <path>\`. Approve is part of the change \u2014 the change is not done until approve passes. Do not defer approval.
 
-### Quick Routing Table
+**End of conversation:** \`yg check\` \u2014 resolve all drift. \`yg check\` failures block CI. If drift remains, the build breaks.
 
-| What you have | Where it goes |
-|---|---|
-| Cross-cutting rule (3+ nodes) | Aspect content.md |
-| Architectural invariant for a node type | Architecture default aspect |
-| Business process participation | Flow (\`yg-flow.yaml nodes\`) |
-| Process-level requirement | Flow \`aspects\` + aspect directory |
-| Node identity (brief) | \`description\` in yg-node.yaml |
-| Already visible in source code or config files | Not captured |
-| Non-enforceable knowledge | Not captured |
+**Unmapped files:** \`yg context --file\` will say if a file has no owner and suggest candidates. Either add it to an existing node's mapping or create a new node. Code without graph coverage works but is not verified \u2014 inform the user and propose options.
 
-### Creating Aspects
+**Greenfield (no nodes yet):** Graph before code. Create architecture types, aspects, and nodes first \u2014 they are the specification. Then implement code that satisfies the aspects. \`yg check\` will guide you through coverage gaps.
 
-- [ ] 1. Read \`schemas/yg-aspect.yaml\`
-- [ ] 2. Create \`aspects/<id>/\` directory
-- [ ] 3. Write \`yg-aspect.yaml\` \u2014 name, description, optional implies
-- [ ] 4. Write content \`.md\` files: WHAT must be satisfied + WHY (user's words, do not invent)
-- [ ] 5. \`yg check\`
+### When to Create Graph Elements
 
-Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. "Can the reviewer check it against source code?" Yes \u2192 aspect. Both must be true.
+**Aspect** \u2014 when the same pattern appears in 3+ files AND the reviewer can verify it against source code. Both conditions. "Every handler logs audit trail" \u2014 pattern + verifiable = aspect. "Code should be readable" \u2014 not verifiable, not an aspect. Read \`schemas/yg-aspect.yaml\` before creating. Content \`.md\` files state WHAT must be satisfied and WHY \u2014 use the user's words, never invent rationale. Things that do NOT become aspects: knowledge already visible in source code (imports, config), non-enforceable knowledge (business strategy, personas, pricing), and conventions the reviewer cannot check against code.
 
-### Creating Flows
+**Flow** \u2014 when you see a sequence of steps toward a business goal. Not code call sequences \u2014 real-world processes. "User places an order" = flow. "Handler calls service" = relation between nodes. Read \`schemas/yg-flow.yaml\` before creating.
 
-- [ ] 1. Read \`schemas/yg-flow.yaml\`
-- [ ] 2. Create \`flows/<name>/\` directory
-- [ ] 3. Write \`yg-flow.yaml\` \u2014 name, description, nodes (participant list), and flow-level aspects
-- [ ] 4. \`yg check\`
+**Node** \u2014 one per cohesive feature area. Not per directory, not per file. If a node would map >10 source files or cover >3 distinct workflows, split into children. Why: the reviewer sees ALL files in a node. Too many files = reviewer loses context and produces false rejections. Aim for 2-5 source files per node with aspects. Read \`schemas/yg-node.yaml\` before creating.
 
-Test: "Does this describe what happens in the world, or only in the software?" If only software \u2014 rewrite.
+**Architecture change** \u2014 when existing types don't fit the project structure. Always confirm with the user. Never silently modify \`yg-architecture.yaml\`. If a relation between types is forbidden, present the constraint and let the user decide: use an allowed relation type, change the node type, or update the architecture.
 
-**Flow identification heuristic:** If a spec, conversation, or code reveals a sequence of steps toward a business goal \u2014 it IS a flow. This applies to multi-actor processes AND single-actor workflows.
+### Aspect Discovery
 
-### Ports
+Aspects emerge from patterns \u2014 greenfield and brownfield:
 
-Nodes can declare typed ports \u2014 named entry points with required aspects:
+- After working on 3+ files in the same area: are you applying the same pattern? If yes, create an aspect.
+- Watch for "invisible" aspects: audit logging, webhook dispatch, auth guards, job dispatch \u2014 cross-cutting but easy to miss.
+- Brownfield: same utility called in 3+ files = aspect waiting to be created.
 
-\`\`\`yaml
-ports:
-  charge:
-    description: "Charge payment"
-    aspects: [correlation-tracking]
-\`\`\`
+### Delegating to Subagents
 
-Consumers reference ports via consumes on relations:
+Subagents don't inherit Yggdrasil knowledge. First instruction in every subagent prompt:
 
-\`\`\`yaml
-relations:
-  - target: payments/service
-    type: calls
-    consumes: [charge]
+\`\`\`
+BEFORE doing anything else: read .yggdrasil/agent-rules.md and follow its protocol.
+DELIVERABLES \u2014 all required, incomplete work will be rejected:
+  1. Working source code
+  2. Graph nodes for every new/modified source file
+  3. \`yg check\` passing
 \`\`\`
 
-At check time: \`port-missing-consumes\` fires if target has ports but consumer has no consumes. \`port-undefined\` fires if consumes references undefined port. \`consumes-without-ports\` fires if consumes is declared but target has no ports.
-At approve time: Reviewer verifies consumer satisfies port-required aspects.
-
-### CLI Commands
-
-Core: \`yg check\`, \`yg context --node/--file\`, \`yg impact --node/--file/--aspect/--flow\`, \`yg approve --node/--aspect/--flow\`
-Navigation: \`yg tree [--root <path>] [--depth <n>]\`, \`yg aspects\`, \`yg flows\`, \`yg owner --file\`
-Setup: \`yg init\`
-Debug: \`yg approve --dry-run --node <path>\` \u2014 preview reviewer prompt without LLM call
-
-### Error Categories
-
-CLI groups errors into categories. Each message tells you what happened, why,
-and what command to run next.
-
-- **Drift (\`source-drift\`, \`upstream-drift\`):** source files or upstream context changed since last approve. Run approve workflow.
-- **Structural (\`yaml-invalid\`, \`config-invalid\`, \`relation-broken\`, etc.):** YAML broken or graph inconsistent. Fix the YAML.
-- **Coverage (\`unmapped-files\`, \`mapping-path-missing\`):** source files not mapped. Bootstrap workflow.
-- **Completeness (\`description-missing\`):** required fields missing. Add them.
-- **Architecture (\`aspect-undefined\`, \`relation-target-forbidden\`, \`port-*\`, etc.):** references broken or contracts violated. Fix references.
-- **Semantic (\`aspect-violation\`, approve only):** Reviewer found aspects not satisfied in source code.
-
-Follow the CLI's suggested next command.
-
-### Approve Enforcement
-
-Approve is the architecture enforcement gate. Binary \u2014 no flags, no negotiation.
-
-**How it works:**
-1. Source or upstream context changed \u2192 run reviewer \u2192 reviewer checks each aspect's content.md against source code
-2. Reviewer satisfied \u2192 \`approved\`, new baseline recorded
-3. Reviewer not satisfied \u2192 \`refused\` with \`aspect-violation\` \u2014 fix source code and re-run
-
-**Three modes:**
-
-- \`yg approve --node <path> [<path2> ...]\` \u2014 one or more node paths. Multiple paths run as a batch.
-- \`yg approve --aspect <id>\` \u2014 batch approve all cascade nodes caused by this aspect change.
-- \`yg approve --flow <name>\` \u2014 batch approve all cascade nodes caused by this flow change.
-
-Batch mode runs approvals in parallel (up to \`parallel\` config limit). Use batch when \`yg check\` suggests it in \`suggestedNext\`.
-
-**Do NOT interrupt \`yg approve\`.** When reviewer is configured, approve calls the reviewer for every aspect across every source file \u2014 this takes time and is intentional. Interrupting it leaves drift state unrecorded and forces a re-run.
-
-**Always read the FULL raw output of \`yg approve\`.** Every aspect result, every error message \u2014 read it all. The reviewer already ran and the cost is paid; the output is the return on that investment.
-
-Always run the command without \`| grep\`, \`| head\`, \`| tail\`, or any filter that discards lines. Saving to a file and reading it (\`tee\`) is fine \u2014 that preserves all data. The rule is: all reviewer output must reach you unmodified.
-
-Always batch at most 3-5 nodes per approve invocation. This is a maximum, not a suggestion.
-
-**When reviewer rejects \u2014 decision tree:**
-
-1. **Code violates aspect** \u2192 fix the code. This is the common case.
-2. **Code is compliant but aspect wording is ambiguous** \u2192 fix the aspect content.md to be clearer. The escape hatch is improving the rule, not bypassing enforcement.
-3. **Reviewer cannot verify because node has too many files** \u2192 the reviewer sees all source files in the node. If the node is too large, the reviewer lacks focused context. Split the node into smaller nodes so each has 2-5 source files with the relevant aspects. Never remove aspects to make approve pass \u2014 that disables enforcement.
-4. **Aspect applies to this node but not to all its files** \u2192 the aspect may be too broad for this node. Either split the node (files that need the aspect vs. files that don't), or refine the aspect content.md to scope which files it applies to.
-
-**Never remove an aspect from a node to bypass a rejection.** If approve fails, the fix is in the code, the aspect wording, or the node structure \u2014 not in removing enforcement.`;
-var GUARD_RAILS = `## GUARD RAILS
-
-### Core Rules
-
-1. **Graph first.** Before reading, researching, planning, or modifying ANY source file, run \`yg context --file <path>\`. For blast radius, also run \`yg impact\`. The graph is your primary source of architectural understanding.
-2. **Aspects are the specification; code implements; approve verifies.** Aspects define enforceable rules. Code must satisfy them. Approve checks compliance. This is the enforcement loop.
-3. **Check blocks commits and CI.** \`yg check\` must pass before every commit. Treat this as fact. All errors (drift, structural, coverage, completeness) must be resolved.
-4. **Never invent rationale.** If you don't know why a requirement exists, ask the user. Never hallucinate the reason behind an aspect.
-5. **Ask before resolving ambiguity.** When multiple valid interpretations exist, stop, list options, ask the user. Never silently choose.
-6. **Yggdrasil is invisible to the user.** Never mention the graph, aspects, flows, nodes, \`yg\` commands, or \`.yggdrasil/\` in conversation with the user. Present graph knowledge as your understanding \u2014 "this module handles X" not "the graph says this module handles X."
-
-### Recognizing Graph-Required Actions
-
-What matters is the ACTION you are performing, not what instructed it. If the action involves reading, understanding, or modifying mapped code, the graph protocol applies \u2014 whether the instruction came from a skill, a plan, a user message, a brainstorming session, a debugging workflow, or your own initiative.
-
-**Actions that require \`yg context --file\`:**
-
-- Reading or exploring source files to understand a component
-- Proposing approaches, designs, or plans for changing code
-- Reviewing or debugging code
-- Any form of reasoning about how mapped code works or should change
-
-**Actions that also require \`yg impact\`:**
-
-- Assessing blast radius before changing or removing a component
-- Finding all dependents of a component
-- Planning cross-cutting refactors or feature removals
-
-**Actions that do NOT require yg:**
-
-- Git operations (log, diff, status, blame)
-- Reading documentation, READMEs, or config files outside \`.yggdrasil/\`
-- Running tests, builds, or linters
-- Working with files that \`yg context --file\` reports as unmapped
-
-### Operational Rules
-
-- **English only** for all files in \`.yggdrasil/\`. Conversation can be any language.
-- **Read schemas before creating** any \`yg-node.yaml\`, \`yg-aspect.yaml\`, or \`yg-flow.yaml\`.
-- **Tools read, you write.** The \`yg\` CLI only reads, validates, and manages metadata. You create and edit files manually.
-- **Incremental approval.** Run \`yg approve\` per node after every 3-5 source file changes. Do not defer to end of task.
-- **Never defer approval.** When you finish modifying code, approve immediately. Do not say "I'll approve later" or leave drift for the next session. Approval is part of the change \u2014 the change is not done until approve passes.
-- **Description maintenance.** Every \`yg-node.yaml\`, \`yg-aspect.yaml\`, and \`yg-flow.yaml\` has a \`description\` field. Write it when creating new elements. Update it when the element's identity or purpose changes.
-
-### Aspect Discovery During Implementation
-
-Aspects emerge from patterns \u2014 in greenfield AND brownfield:
-
-- **After working on 3+ files in the same area, pause and check:** Are you applying the same pattern repeatedly? If YES, stop and create an aspect NOW.
-- **Watch for "invisible" aspects:** Patterns that don't feel "architectural" but ARE cross-cutting: audit logging on every mutation, webhook dispatch after state changes, job dispatch for async operations, authorization guards on every endpoint.
-- **Brownfield trigger:** When you read existing code and see the same utility called in 3+ files, that IS an aspect waiting to be created.
+Code without graph updates = incomplete work.
 
-### Bootstrap Mode
+### \`yg-suppress\` \u2014 Inline Aspect Waiver
 
-Trigger: \`yg check\` shows \`unmapped-files\` with high uncovered file count, or 0 nodes.
+Source code comments with \`yg-suppress(<aspect-path>) <reason>\` waive a specific aspect. The reviewer honors these unconditionally.
 
-- [ ] 1. Identify the active work area (files the user wants to modify)
-- [ ] 2. Create nodes for areas you will work on (with aspects for enforcement)
-- [ ] 3. Create minimal nodes (no aspects) for areas you will NOT work on \u2014 provides coverage without enforcement
-- [ ] 4. Scan for cross-cutting patterns \u2192 create aspects
-- [ ] 5. Ask user about business processes \u2192 create flows if applicable
-- [ ] 6. \`yg check\`, \`yg approve\` per node
-- [ ] 7. Proceed with user's original request
+\`\`\`
+// yg-suppress(cqrs/single-responsibility) brownfield handler, refactor planned
+# yg-suppress(security/input-validation) static config, no user input
+<!-- yg-suppress(accessibility/aria-labels) generated markup, tracked in JIRA-456 -->
+\`\`\`
 
-Constraint: Focus on the active area. Expand incrementally.
+- You may propose a suppress when you see brownfield code or known tech debt violating an aspect
+- You MUST NEVER write a suppress without explicit user confirmation \u2014 no exceptions
+- Provide the correct aspect-path from graph context, ask the user for the reason
+- You do not invent reasons \u2014 the user provides or approves them
+- The marker applies contextually to surrounding code (function, class, block). At file level, it applies to the entire file.
 
 ### Escape Hatch
 
-If the user explicitly requests a code-only change, comply but:
+If the user explicitly requests a code-only change without graph updates: comply, but warn that this creates drift. \`yg check\` will catch it \u2014 and CI will block until it's resolved. Do not run \`yg approve\` \u2014 leave the drift visible.
 
-- Warn: "This creates drift. Run \`yg check\` next session to reconcile."
-- Do NOT run \`yg approve\` \u2014 leave the drift visible.
+### Operational Notes
 
-<critical_protocol>
-BEFORE reading, analyzing, or modifying ANY source file:
-  \`yg context --file <path>\`
-One command. No exceptions. No "I'll do it later." No "this is just analysis."
-</critical_protocol>`;
-var AGENT_RULES_CONTENT = [PROTOCOL, REFERENCE, GUARD_RAILS].join("\n\n---\n\n") + "\n";
+- English only for all files in \`.yggdrasil/\`. Conversation can be any language.
+- Read the relevant schema from \`schemas/\` before creating any YAML file.
+- Every \`yg-node.yaml\`, \`yg-aspect.yaml\`, and \`yg-flow.yaml\` needs a \`description\`. Write it when creating, update it when purpose changes.
+- When renaming or splitting a node: run \`yg flows\` and update any flow \`nodes\` lists that reference the old path. \`yg check\` will catch broken references but it's faster to fix them proactively.
+- When unsure about anything: ask the user. Do not guess. Do not assume.
+- Never invent rationale for aspects. If you don't know why a requirement exists, ask.`;
+var AGENT_RULES_CONTENT = [SYSTEM, DECISIONS].join("\n\n---\n\n") + "\n";
 
 // src/templates/platform.ts
 var AGENT_RULES_IMPORT = "@.yggdrasil/agent-rules.md";
@@ -1364,10 +1134,17 @@ var MIGRATIONS = [
 ];
 
 // src/cli/init.ts
-function getGraphSchemasDir() {
+function getPackageRoot() {
   const currentDir = path5.dirname(fileURLToPath(import.meta.url));
-  const packageRoot = path5.join(currentDir, "..");
-  return path5.join(packageRoot, "graph-schemas");
+  return path5.join(currentDir, "..");
+}
+function getGraphSchemasDir() {
+  return path5.join(getPackageRoot(), "graph-schemas");
+}
+async function getCliVersion() {
+  const pkgPath = path5.join(getPackageRoot(), "package.json");
+  const pkg2 = JSON.parse(await readFile4(pkgPath, "utf-8"));
+  return pkg2.version;
 }
 async function refreshSchemas(yggRoot) {
   const schemasDir = path5.join(yggRoot, "schemas");
@@ -1669,7 +1446,7 @@ async function existingInit(projectRoot) {
   }
   p.intro(chalk.bold("Yggdrasil Configuration"));
   const currentVersion = await detectVersion(yggRoot);
-  const cliVersion = "4.0.0";
+  const cliVersion = await getCliVersion();
   if (currentVersion && currentVersion !== cliVersion) {
     const migrate = await p.confirm({
       message: `Graph version ${currentVersion} detected \u2014 CLI is ${cliVersion}. Run migration?`,
@@ -1767,6 +1544,7 @@ function registerInitCommand(program2) {
         } catch {
           await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
         }
+        await updateConfigVersion(yggRoot, await getCliVersion());
         const rulesPath = await installRulesForPlatform(projectRoot, options.platform);
         process.stdout.write(`Rules and schemas refreshed: ${path5.relative(projectRoot, rulesPath)}
 `);

package/graph-schemas/yg-architecture.yaml

@@ -1,12 +1,39 @@
 # yg-architecture.yaml — Schema for architecture constraints
 # File: .yggdrasil/yg-architecture.yaml
-# Defines node types with architectural constraints.
+#
+# Defines the project's type system: what kinds of nodes exist, how they can
+# relate, and which aspects apply by default. This is the foundation of the
+# graph — every node declares a type, and every type must be defined here.
+#
+# Changes to this file affect the entire graph and should be confirmed with the user.
 # All properties except description are optional — absence means no enforcement.
+# When a constraint is absent, anything is allowed. When present, only listed
+# values are permitted.
 
 node_types:
   <type-id>:
-    description: <string>                    # required — what this type is for
-    aspects: [<aspect-id>]                   # optional — required on every file of this type
-    parents: [<type-id>]                     # optional — allowed parent types
-    relations:                               # optional — allowed relation targets
-      <relation-type>: [<type-id>]           # calls | uses | extends | implements | emits | listens
+    description: <string>                    # required — what this type is for, when to use it
+
+    aspects: [<aspect-id>]                   # optional — aspects automatically applied to every node
+                                             # of this type (channel 3 in aspect resolution).
+                                             # These also cascade to children of nodes of this type
+                                             # (channel 4). Use for invariants that ALL nodes of
+                                             # this type must satisfy.
+
+    parents: [<type-id>]                     # optional — allowed parent node types in the hierarchy.
+                                             # If omitted, this type can appear under any parent.
+                                             # If specified, nesting under an unlisted parent type
+                                             # triggers a parent-type-forbidden error.
+
+    relations:                               # optional — allowed relation targets by relation type.
+                                             # If a relation type is listed, only the specified
+                                             # target types are allowed. Unlisted relation types
+                                             # are unrestricted. If omitted entirely, all relations
+                                             # are allowed.
+      <relation-type>: [<type-id>]           # Relation types:
+                                             #   calls       — runtime invocation
+                                             #   uses        — compile-time dependency
+                                             #   extends     — inheritance / specialization
+                                             #   implements  — interface contract
+                                             #   emits       — publishes events (must pair with listens)
+                                             #   listens     — subscribes to events (must pair with emits)

package/graph-schemas/yg-aspect.yaml

@@ -1,9 +1,20 @@
 # yg-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.
+# plus any number of .md content files.
+#
+# Aspect identifier = relative path from aspects/ to the directory
+# (e.g. observability/logging). Aspects can be organized in nested
+# directories — the directory structure is for organization only,
+# there is no automatic parent-child inheritance between aspects.
+#
+# The .md content files are what the reviewer checks against source code.
+# They should state WHAT must be satisfied and WHY.
 
 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)
+description: "Short description"   # optional but recommended — shown in yg aspects output
+                                   # and context packages, helps agents discover relevant aspects
+
+# implies: [other-aspect]          # optional — other aspect identifiers included automatically
+                                   # when this aspect is effective on a node. Recursive expansion
+                                   # (A implies B implies C = all three effective). Must be acyclic
+                                   # — CLI detects and rejects cycles.

package/graph-schemas/yg-flow.yaml

@@ -1,10 +1,22 @@
 # yg-flow.yaml — Schema for end-to-end business flows
 # Each flow is a directory under .yggdrasil/flows/ containing this file.
+#
+# A flow describes a business process — what happens in the world,
+# not code call sequences. "User places an order" is a flow.
+# "Handler calls service" is a relation between nodes.
+#
+# Descendants of a declared participant are automatically included —
+# listing a parent node covers all its children.
 
 name: EndToEndProcessName     # required — display name
-description: "Short description of this business process"  # optional
+description: "What this business process does"  # optional but recommended — shown in
+                                                # yg flows output and context packages
+
 nodes:                        # required, non-empty — participant nodes (alias: participants)
   - orders/order-service      # paths relative to model/
-  - payments/payment-service
-  - inventory/inventory-service
-# aspects: [requires-saga]    # optional — aspect tags propagated to ALL participants
+  - payments/payment-service  # each participant (and its descendants) must satisfy
+  - inventory/inventory-service  # any flow-level aspects declared below
+
+# aspects: [requires-saga]    # optional — aspect identifiers propagated to ALL participants
+                              # (channel 5 in aspect resolution). Use for requirements that
+                              # apply to every node in this process but not globally.

package/graph-schemas/yg-node.yaml

@@ -1,23 +1,31 @@
 # yg-node.yaml — Schema for model nodes
 # Every node is a directory under .yggdrasil/model/ containing this file.
+# The node's path in the graph = its directory path relative to model/.
+# Nodes nest by directory — a node at model/orders/handler/ is a child
+# of model/orders/ and inherits its parent's aspects.
 
 name: ComponentName           # required — display name
-type: service                 # required — must match a type from yg-architecture.yaml
-description: "Short description of what this node does"  # optional
+type: service                 # required — must match a type defined in yg-architecture.yaml
+description: "What this node does"  # optional but recommended — shown in context output,
+                                    # helps agents understand purpose without reading code
 
-aspects:                      # optional — list of aspect identifiers
-  - aspect-id                 # aspect directory name under aspects/
+aspects:                      # optional — aspect identifiers applied directly to this node
+  - aspect-id                 # must match a directory name under aspects/
+                              # these aspects also cascade to all child nodes
 
-ports:                        # optional — named entry points with required aspects (on target nodes)
-  port-name:
+ports:                        # optional — named entry points with required aspects
+  port-name:                  # consumers of this node reference ports via consumes
     description: "What this port provides"  # required
-    aspects: [aspect-id]      # required — aspects consumers must satisfy
+    aspects: [aspect-id]      # required — aspects that consumers must satisfy (channel 6)
 
 relations:                    # optional — outgoing dependencies to other nodes
-  - target: other/module-path # required — path relative to model/
+  - target: other/module-path # required — node path relative to model/
     type: calls               # required — calls | uses | extends | implements | emits | listens
-    consumes: [port-name]     # optional — port names consumed from target (required when target has ports)
+    consumes: [port-name]     # optional — port names consumed from target
+                              # required when target declares ports — otherwise check warns
 
-mapping:                      # optional — flat list of source file or directory paths
-  - src/modules/component/    # paths are relative to repository root
-  - src/modules/component.ts
+mapping:                      # optional — source files and directories owned by this node
+  - src/modules/component/    # directory — all files inside are owned (recursive)
+  - src/modules/component.ts  # file — exact match
+                              # paths are relative to repository root
+                              # each source file must have exactly one owner node

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Continuous architecture enforcement for AI-assisted development. Aspects, review, enforcement.",
   "type": "module",
   "bin": {