@chrisdudek/yg 4.0.2 → 4.2.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>
@@ -118,6 +125,7 @@ import { Command } from "commander";
 
 // src/cli/init.ts
 import chalk from "chalk";
+import { existsSync } from "fs";
 import { mkdir as mkdir2, writeFile as writeFile4, readdir as readdir2, readFile as readFile4, stat as stat2 } from "fs/promises";
 import path5 from "path";
 import { fileURLToPath } from "url";
@@ -153,437 +161,237 @@ 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.
-
-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.
+var SYSTEM = `## SYSTEM
 
-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>
+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.
 
-Every rule below is mandatory \u2014 no skill, plan, workflow, or instruction overrides these requirements.
-</EXTREMELY-IMPORTANT>
+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.
 
-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:
-
-*Partially mapped* (file unmapped but inside a mapped module): ask whether to add to existing node or create new one.
-
-*Existing code:*
+**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.
 
-- Option A \u2014 Proper node: create node(s), map files, write description in \`yg-node.yaml\`
-- Option B \u2014 Abort
+**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).
 
-*Greenfield (new code):* Only Option A. Follow the graph-first workflow:
+**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.
 
-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\`
+**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.
 
-**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.
+**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.
 
-**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.
+**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\`.
 
-**\`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.
+### How Aspects Reach a Node \u2014 7 Channels + Applicability Filter
 
-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
+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.
 
-\`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.
+### Applicability Filter (\`when\`) \u2014 Evaluated on Every Channel
 
-**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.
+Seven channels propagate aspects onto nodes. A separate mechanism \u2014 the \`when\`
+predicate \u2014 filters applicability. Every channel's attachment passes through
+\`when\` before the aspect becomes effective. The predicate is evaluated by the
+CLI against the graph (deterministic, no LLM call); if false, the aspect is
+silently skipped on that node.
 
-**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
+\`when\` can be declared globally on the aspect (applies across channels) or
+per attach site (per channel instance). Global and attach-site \`when\` combine
+via AND on each channel path. Multiple channels deliver independently \u2014 the
+aspect is effective if any channel's path passes both its global and
+attach-site filter.
 
-**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.
+Use \`when\` when an aspect is meaningful for only a subset of nodes under a
+common attach channel. Example: \`external-api-error-mapping\` attached to
+type \`command\` but only applicable when the node calls \`service-client\` \u2014
+declare on the aspect:
 
-### Delegating to Subagents
+    when:
+      relations:
+        calls:
+          target_type: service-client
 
-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:
+Domain-neutral examples: a \`pii-encryption\` aspect attached to all
+repositories, but only applicable when the repository stores a field of
+type \`user-profile\`; an \`idempotency-key\` aspect required only for commands
+that emit events; a \`database-migration-review\` aspect only for nodes with
+\`has_mapping: true\` pointing at \`db/migrations/\`.
 
-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
+### Reviewer
 
-Include this as the FIRST instruction in every subagent prompt:
+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.
 
-\`\`\`
-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 |
+| \`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 |
 
-### Context Assembly
+### Impact and Cost
 
-Two context commands serve different purposes:
+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.
 
-- **\`yg context --node <path>\`** \u2014 node overview: aspects, flows, dependents
-- **\`yg context --file <path>\`** \u2014 per-file: aspects to satisfy, consumed dependencies
+When code doesn't match an aspect, three options:
 
-**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.
+| 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 --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
+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
 
-\`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
+### Workflow
 
-Read ALL aspect content files listed \u2014 the cost is low, the risk of skipping is high.
+**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.
 
-### Information Routing
+**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>\`.
 
-When you encounter information, route it to the correct location:
+**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.
 
-- **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.
+**End of conversation:** \`yg check\` \u2014 resolve all drift. \`yg check\` failures block CI. If drift remains, the build breaks.
 
-### Quick Routing Table
+**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.
 
-| 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 |
+**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.
 
-### Creating Aspects
+### When to Create Graph Elements
 
-- [ ] 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\`
+**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.
 
-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.
+**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.
 
-### Creating Flows
+**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.
 
-- [ ] 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\`
+**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.
 
-Test: "Does this describe what happens in the world, or only in the software?" If only software \u2014 rewrite.
+**\`when\` predicate on an aspect or attach site** \u2014 when the aspect applies to
+only a subset of nodes under a common attach channel. Prefer \`when\` over
+splitting node types (proliferation of types). Prefer \`when\` over leaving
+the decision to the reviewer textually inside \`content.md\`; \`when\` is
+deterministic, has zero LLM cost, and keeps the graph as the source of
+truth for applicability.
 
-**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";
@@ -1363,11 +1171,31 @@ var MIGRATIONS = [
   }
 ];
 
+// src/formatters/message-builder.ts
+function buildIssueMessage(msg) {
+  return `${msg.what}
+${msg.why}
+${msg.next}`;
+}
+
 // src/cli/init.ts
+function getPackageRoot() {
+  let dir = path5.dirname(fileURLToPath(import.meta.url));
+  while (dir !== path5.dirname(dir)) {
+    if (existsSync(path5.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path5.dirname(dir);
+  }
+  throw new Error("Could not locate package root (no package.json found walking up from init module).");
+}
 function getGraphSchemasDir() {
-  const currentDir = path5.dirname(fileURLToPath(import.meta.url));
-  const packageRoot = path5.join(currentDir, "..");
-  return path5.join(packageRoot, "graph-schemas");
+  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");
@@ -1661,6 +1489,25 @@ async function createYggdrasilStructure(projectRoot, yggRoot, platform) {
   await writeFile4(path5.join(yggRoot, ".gitignore"), GITIGNORE_CONTENT, "utf-8");
   await installRulesForPlatform(projectRoot, platform);
 }
+async function runVersionUpgrade(projectRoot, yggRoot, fromVersion, toVersion, platform) {
+  const migrationResults = await runMigrations(fromVersion, MIGRATIONS, yggRoot);
+  await updateConfigVersion(yggRoot, toVersion);
+  await refreshSchemas(yggRoot);
+  const architecturePath = path5.join(yggRoot, "yg-architecture.yaml");
+  try {
+    await stat2(architecturePath);
+  } catch {
+    await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
+  }
+  const rulesPath = await installRulesForPlatform(projectRoot, platform);
+  const migrationActions = [];
+  const migrationWarnings = [];
+  for (const r of migrationResults) {
+    migrationActions.push(...r.actions);
+    migrationWarnings.push(...r.warnings);
+  }
+  return { rulesPath, migrationActions, migrationWarnings };
+}
 async function existingInit(projectRoot) {
   const yggRoot = path5.join(projectRoot, ".yggdrasil");
   if (!isTTY()) {
@@ -1669,35 +1516,30 @@ 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?`,
-      initialValue: true
-    });
-    assertNotCancelled(migrate);
-    if (migrate) {
-      const s = p.spinner();
-      s.start("Running migrations...");
-      const results = await runMigrations(currentVersion, MIGRATIONS, yggRoot);
-      await updateConfigVersion(yggRoot, cliVersion);
-      await refreshSchemas(yggRoot);
-      s.stop("Migration complete.");
-      for (const result of results) {
-        for (const action2 of result.actions) {
-          p.log.info(action2);
-        }
-        for (const warning of result.warnings) {
-          p.log.warning(warning);
-        }
-      }
-      p.log.step("Next steps:");
-      p.log.info("1. Run yg init again to configure reviewer (if not set)");
-      p.log.info("2. Run yg check to verify graph integrity");
-      p.log.info("3. Run yg approve on all nodes to establish baselines");
-      p.outro(chalk.green(`Migrated from ${currentVersion} to ${cliVersion}.`));
-      return;
-    }
+    p.log.step(`Graph version ${currentVersion} detected \u2014 CLI is ${cliVersion}. Upgrade required.`);
+    p.log.info("Select the agent platform so rules and schemas advance together.");
+    const platform = await promptPlatform();
+    const s = p.spinner();
+    s.start("Running migrations and installing rules...");
+    const result = await runVersionUpgrade(projectRoot, yggRoot, currentVersion, cliVersion, platform);
+    s.stop("Upgrade complete.");
+    for (const action2 of result.migrationActions) {
+      p.log.info(action2);
+    }
+    for (const warning of result.migrationWarnings) {
+      p.log.warning(warning);
+    }
+    p.log.step("Next steps:");
+    p.log.info("1. Run yg check to verify graph integrity");
+    p.log.info("2. Run yg approve on all nodes to establish baselines");
+    p.outro(
+      chalk.green(
+        `Migrated from ${currentVersion} to ${cliVersion}. Rules installed: ${path5.relative(projectRoot, result.rulesPath)}`
+      )
+    );
+    return;
   }
   const action = await p.select({
     message: "What would you like to do?",
@@ -1711,15 +1553,9 @@ async function existingInit(projectRoot) {
   switch (action) {
     case "upgrade": {
       const platform = await promptPlatform();
-      await refreshSchemas(yggRoot);
-      const architecturePath = path5.join(yggRoot, "yg-architecture.yaml");
-      try {
-        await stat2(architecturePath);
-      } catch {
-        await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
-      }
-      const rulesPath = await installRulesForPlatform(projectRoot, platform);
-      p.outro(chalk.green(`Rules and schemas refreshed: ${path5.relative(projectRoot, rulesPath)}`));
+      const fromVersion = currentVersion ?? cliVersion;
+      const result = await runVersionUpgrade(projectRoot, yggRoot, fromVersion, cliVersion, platform);
+      p.outro(chalk.green(`Rules and schemas refreshed: ${path5.relative(projectRoot, result.rulesPath)}`));
       break;
     }
     case "reviewer": {
@@ -1760,16 +1596,27 @@ function registerInitCommand(program2) {
           process.stderr.write(chalk.red("Error: No .yggdrasil/ directory found. Run 'yg init' first.\n"));
           process.exit(1);
         }
-        await refreshSchemas(yggRoot);
-        const architecturePath = path5.join(yggRoot, "yg-architecture.yaml");
-        try {
-          await stat2(architecturePath);
-        } catch {
-          await writeFile4(architecturePath, DEFAULT_ARCHITECTURE, "utf-8");
+        const toVersion = await getCliVersion();
+        const fromVersion = await detectVersion(yggRoot);
+        if (fromVersion === null) {
+          process.stderr.write(chalk.red(buildIssueMessage({
+            what: "No graph version detected.",
+            why: ".yggdrasil/yg-config.yaml is missing a 'version:' field, so --upgrade cannot determine which migrations to run.",
+            next: "Run 'yg init' interactively once to record the current version, then retry 'yg init --upgrade --platform <name>'."
+          }) + "\n"));
+          process.exit(1);
         }
-        const rulesPath = await installRulesForPlatform(projectRoot, options.platform);
-        process.stdout.write(`Rules and schemas refreshed: ${path5.relative(projectRoot, rulesPath)}
-`);
+        const result = await runVersionUpgrade(
+          projectRoot,
+          yggRoot,
+          fromVersion,
+          toVersion,
+          options.platform
+        );
+        process.stdout.write(
+          `Rules and schemas refreshed: ${path5.relative(projectRoot, result.rulesPath)}
+`
+        );
         return;
       }
       let exists = false;
@@ -1926,7 +1773,219 @@ function normalizeProviderConfig(providerName, pc, generalConfig, filename) {
 // src/io/node-parser.ts
 import { readFile as readFile6 } from "fs/promises";
 import { parse as parseYaml4 } from "yaml";
-var RELATION_TYPES = [
+
+// src/io/when-parser.ts
+var RELATION_TYPES = /* @__PURE__ */ new Set([
+  "calls",
+  "uses",
+  "extends",
+  "implements",
+  "emits",
+  "listens"
+]);
+var ATOMIC_KEYS = /* @__PURE__ */ new Set(["relations", "descendants", "node"]);
+var BOOLEAN_KEYS = /* @__PURE__ */ new Set(["all_of", "any_of", "not"]);
+function parseWhen(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: when must be a YAML mapping`);
+  }
+  const keys = Object.keys(raw);
+  if (keys.length === 0) {
+    throw new Error(`${ctx}: when mapping must not be empty`);
+  }
+  const booleanKeys = keys.filter((k) => BOOLEAN_KEYS.has(k));
+  const atomicKeys = keys.filter((k) => ATOMIC_KEYS.has(k));
+  const unknownKeys = keys.filter((k) => !BOOLEAN_KEYS.has(k) && !ATOMIC_KEYS.has(k));
+  if (unknownKeys.length > 0) {
+    throw new Error(`${ctx}: unknown when operator '${unknownKeys[0]}' (expected one of: all_of, any_of, not, relations, descendants, node)`);
+  }
+  if (booleanKeys.length > 0 && atomicKeys.length > 0) {
+    throw new Error(`${ctx}: when cannot mix boolean operators with atomic clauses at the same level`);
+  }
+  if (booleanKeys.length > 1) {
+    throw new Error(`${ctx}: when can have at most one boolean operator at a level (got: ${booleanKeys.join(", ")})`);
+  }
+  if (booleanKeys.length === 1) {
+    return parseBoolean(raw, booleanKeys[0], ctx);
+  }
+  return parseAtomic(raw, ctx);
+}
+function parseBoolean(raw, key, ctx) {
+  const val = raw[key];
+  if (key === "not") {
+    return { not: parseWhen(val, `${ctx}/not`) };
+  }
+  if (!Array.isArray(val)) {
+    throw new Error(`${ctx}: '${key}' must be an array`);
+  }
+  if (val.length === 0) {
+    throw new Error(`${ctx}: '${key}' array must not be empty`);
+  }
+  const items = val.map((v, i) => parseWhen(v, `${ctx}/${key}[${i}]`));
+  return key === "all_of" ? { all_of: items } : { any_of: items };
+}
+function parseAtomic(raw, ctx) {
+  const result = {};
+  if ("relations" in raw) {
+    result.relations = parseRelationClause(raw.relations, `${ctx}/relations`);
+  }
+  if ("descendants" in raw) {
+    result.descendants = parseDescendantsClause(raw.descendants, `${ctx}/descendants`);
+  }
+  if ("node" in raw) {
+    result.node = parseNodeClause(raw.node, `${ctx}/node`);
+  }
+  return result;
+}
+function parseRelationClause(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: relations must be a YAML mapping keyed by relation type`);
+  }
+  const entries = Object.entries(raw);
+  if (entries.length === 0) {
+    throw new Error(`${ctx}: relations mapping must not be empty`);
+  }
+  const out = {};
+  for (const [relType, match] of entries) {
+    if (!RELATION_TYPES.has(relType)) {
+      throw new Error(`${ctx}: unknown relation type '${relType}' (valid: ${Array.from(RELATION_TYPES).join(", ")})`);
+    }
+    out[relType] = parseRelationMatch(match, `${ctx}/${relType}`);
+  }
+  return out;
+}
+function parseRelationMatch(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: must be a YAML mapping`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set(["target_type", "target", "consumes_port"]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`${ctx}: unknown field '${k}' (allowed: target_type, target, consumes_port)`);
+    }
+  }
+  const out = {};
+  if ("target_type" in obj) {
+    if (typeof obj.target_type !== "string" || obj.target_type.trim() === "") {
+      throw new Error(`${ctx}: target_type must be a non-empty string`);
+    }
+    out.target_type = obj.target_type.trim();
+  }
+  if ("target" in obj) {
+    if (typeof obj.target !== "string" || obj.target.trim() === "") {
+      throw new Error(`${ctx}: target must be a non-empty string (node path relative to model/)`);
+    }
+    out.target = obj.target.trim();
+  }
+  if ("consumes_port" in obj) {
+    if (typeof obj.consumes_port !== "string" || obj.consumes_port.trim() === "") {
+      throw new Error(`${ctx}: consumes_port must be a non-empty string`);
+    }
+    out.consumes_port = obj.consumes_port.trim();
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${ctx}: at least one of target_type, target, consumes_port must be present`);
+  }
+  return out;
+}
+function parseDescendantsClause(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: descendants must be a YAML mapping`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set(["relations", "type", "has_port"]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`${ctx}: unknown field '${k}' (allowed: relations, type, has_port)`);
+    }
+  }
+  const out = {};
+  if ("relations" in obj) {
+    out.relations = parseRelationClause(obj.relations, `${ctx}/relations`);
+  }
+  if ("type" in obj) {
+    if (typeof obj.type !== "string" || obj.type.trim() === "") {
+      throw new Error(`${ctx}: type must be a non-empty string`);
+    }
+    out.type = obj.type.trim();
+  }
+  if ("has_port" in obj) {
+    if (typeof obj.has_port !== "string" || obj.has_port.trim() === "") {
+      throw new Error(`${ctx}: has_port must be a non-empty string`);
+    }
+    out.has_port = obj.has_port.trim();
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${ctx}: at least one of relations, type, has_port must be present`);
+  }
+  return out;
+}
+function parseNodeClause(raw, ctx) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${ctx}: node must be a YAML mapping`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set(["type", "has_port", "has_mapping"]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`${ctx}: unknown field '${k}' (allowed: type, has_port, has_mapping)`);
+    }
+  }
+  const out = {};
+  if ("type" in obj) {
+    if (typeof obj.type !== "string" || obj.type.trim() === "") {
+      throw new Error(`${ctx}: type must be a non-empty string`);
+    }
+    out.type = obj.type.trim();
+  }
+  if ("has_port" in obj) {
+    if (typeof obj.has_port !== "string" || obj.has_port.trim() === "") {
+      throw new Error(`${ctx}: has_port must be a non-empty string`);
+    }
+    out.has_port = obj.has_port.trim();
+  }
+  if ("has_mapping" in obj) {
+    if (typeof obj.has_mapping !== "boolean") {
+      throw new Error(`${ctx}: has_mapping must be a boolean`);
+    }
+    out.has_mapping = obj.has_mapping;
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${ctx}: at least one of type, has_port, has_mapping must be present`);
+  }
+  return out;
+}
+function parseAspectAttachment(raw, ctx) {
+  if (typeof raw === "string") {
+    const id = raw.trim();
+    if (id === "") {
+      throw new Error(`${ctx}: aspect id must be a non-empty string`);
+    }
+    return { id };
+  }
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw;
+    if (typeof obj.id !== "string" || obj.id.trim() === "") {
+      throw new Error(`${ctx}: object form requires 'id' as a non-empty string`);
+    }
+    const result = { id: obj.id.trim() };
+    const allowed = /* @__PURE__ */ new Set(["id", "when"]);
+    for (const k of Object.keys(obj)) {
+      if (!allowed.has(k)) {
+        throw new Error(`${ctx}: unknown field '${k}' in aspect attachment (allowed: id, when)`);
+      }
+    }
+    if ("when" in obj) {
+      result.when = parseWhen(obj.when, `${ctx}/when`);
+    }
+    return result;
+  }
+  throw new Error(`${ctx}: aspect attachment must be a string or an object with 'id' (and optional 'when')`);
+}
+
+// src/io/node-parser.ts
+var RELATION_TYPES2 = [
   "uses",
   "calls",
   "extends",
@@ -1935,7 +1994,7 @@ var RELATION_TYPES = [
   "listens"
 ];
 function isValidRelationType(t) {
-  return typeof t === "string" && RELATION_TYPES.includes(t);
+  return typeof t === "string" && RELATION_TYPES2.includes(t);
 }
 async function parseNodeYaml(filePath) {
   const content = await readFile6(filePath, "utf-8");
@@ -1952,52 +2011,43 @@ async function parseNodeYaml(filePath) {
   const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const relations = parseRelations(raw.relations, filePath);
   const mapping = parseMapping(raw.mapping, filePath);
-  const aspects = parseAspects(raw.aspects, filePath);
+  const aspectsResult = parseAspects(raw.aspects, filePath);
   const ports = parsePorts(raw.ports, filePath);
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
     description,
-    aspects,
+    aspects: aspectsResult.aspects,
+    ...aspectsResult.aspectWhens && { aspectWhens: aspectsResult.aspectWhens },
     relations: relations.length > 0 ? relations : void 0,
     mapping,
     ports
   };
 }
 function parseAspects(raw, filePath) {
-  if (raw === void 0 || raw === null) return void 0;
+  if (raw === void 0 || raw === null) return {};
   if (!Array.isArray(raw)) {
     throw new Error(`yg-node.yaml at ${filePath}: 'aspects' must be an array`);
   }
-  if (raw.length === 0) return void 0;
-  const result = [];
-  const seenAspects = /* @__PURE__ */ new Set();
+  if (raw.length === 0) return {};
+  const aspects = [];
+  let aspectWhens;
+  const seen = /* @__PURE__ */ new Set();
   for (let i = 0; i < raw.length; i++) {
-    const item = raw[i];
-    let aspectId;
-    if (typeof item === "string") {
-      aspectId = item.trim();
-      if (aspectId === "") {
-        throw new Error(
-          `yg-node.yaml at ${filePath}: aspects[${i}] must be a non-empty string`
-        );
-      }
-    } else if (typeof item === "object" && item !== null) {
-      throw new Error(
-        `yg-node.yaml at ${filePath}: aspects must be an array of strings.`
-      );
-    } else {
-      throw new Error(`yg-node.yaml at ${filePath}: aspects[${i}] must be a string`);
+    const parsed = parseAspectAttachment(
+      raw[i],
+      `yg-node.yaml at ${filePath}: aspects[${i}]`
+    );
+    if (seen.has(parsed.id)) {
+      throw new Error(`yg-node.yaml at ${filePath}: duplicate aspect '${parsed.id}' in aspects list`);
     }
-    if (seenAspects.has(aspectId)) {
-      throw new Error(
-        `yg-node.yaml at ${filePath}: duplicate aspect '${aspectId}' in aspects list`
-      );
+    seen.add(parsed.id);
+    aspects.push(parsed.id);
+    if (parsed.when) {
+      (aspectWhens ??= {})[parsed.id] = parsed.when;
     }
-    seenAspects.add(aspectId);
-    result.push(aspectId);
   }
-  return result.length > 0 ? result : void 0;
+  return { aspects: aspects.length > 0 ? aspects : void 0, aspectWhens };
 }
 function parseRelations(raw, filePath) {
   if (raw === void 0) return [];
@@ -2089,13 +2139,28 @@ function parsePorts(rawPorts, filePath) {
     if (!Array.isArray(obj.aspects)) {
       throw new Error(`yg-node.yaml at ${filePath}: ports.${name}.aspects must be an array`);
     }
-    const aspects = obj.aspects.map((a, i) => {
-      if (typeof a !== "string" || a.trim() === "") {
-        throw new Error(`yg-node.yaml at ${filePath}: ports.${name}.aspects[${i}] must be a non-empty string`);
+    const portAspects = [];
+    let portAspectWhens;
+    const seenPortAspects = /* @__PURE__ */ new Set();
+    for (let i = 0; i < obj.aspects.length; i++) {
+      const parsed = parseAspectAttachment(
+        obj.aspects[i],
+        `yg-node.yaml at ${filePath}: ports.${name}.aspects[${i}]`
+      );
+      if (seenPortAspects.has(parsed.id)) {
+        throw new Error(`yg-node.yaml at ${filePath}: ports.${name}.aspects has duplicate '${parsed.id}'`);
       }
-      return a.trim();
-    });
-    ports[name] = { description: obj.description.trim(), aspects };
+      seenPortAspects.add(parsed.id);
+      portAspects.push(parsed.id);
+      if (parsed.when) {
+        (portAspectWhens ??= {})[parsed.id] = parsed.when;
+      }
+    }
+    ports[name] = {
+      description: obj.description.trim(),
+      aspects: portAspects,
+      ...portAspectWhens && { aspectWhens: portAspectWhens }
+    };
   }
   return Object.keys(ports).length > 0 ? ports : void 0;
 }
@@ -2146,17 +2211,34 @@ async function parseAspect(aspectDir, aspectYamlPath, id) {
   const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const artifacts = await readArtifacts(aspectDir, ["yg-aspect.yaml"]);
   let implies;
+  let impliesWhens;
   if (raw.implies !== void 0) {
     if (!Array.isArray(raw.implies)) {
-      throw new Error(`yg-aspect.yaml at ${aspectYamlPath}: 'implies' must be an array of strings`);
+      throw new Error(`yg-aspect.yaml at ${aspectYamlPath}: 'implies' must be an array`);
     }
-    implies = raw.implies.filter((t) => typeof t === "string");
+    implies = [];
+    for (let i = 0; i < raw.implies.length; i++) {
+      const parsed = parseAspectAttachment(
+        raw.implies[i],
+        `yg-aspect.yaml at ${aspectYamlPath}: implies[${i}]`
+      );
+      implies.push(parsed.id);
+      if (parsed.when) {
+        (impliesWhens ??= {})[parsed.id] = parsed.when;
+      }
+    }
+  }
+  let when;
+  if (raw.when !== void 0) {
+    when = parseWhen(raw.when, `yg-aspect.yaml at ${aspectYamlPath}: when`);
   }
   return {
     name: raw.name.trim(),
     id: idTrimmed,
     description,
     implies,
+    ...impliesWhens && { impliesWhens },
+    ...when && { when },
     artifacts
   };
 }
@@ -2188,19 +2270,30 @@ async function parseFlow(flowDir, flowYamlPath) {
     );
   }
   let aspects;
+  let aspectWhens;
   if (raw.aspects !== void 0) {
     if (!Array.isArray(raw.aspects)) {
       throw new Error(`yg-flow.yaml at ${flowYamlPath}: 'aspects' must be an array of strings`);
     }
-    const aspectTags = raw.aspects.filter((a) => typeof a === "string");
-    aspects = aspectTags.length > 0 ? aspectTags : [];
+    aspects = [];
+    for (let i = 0; i < raw.aspects.length; i++) {
+      const parsed = parseAspectAttachment(
+        raw.aspects[i],
+        `yg-flow.yaml at ${flowYamlPath}: aspects[${i}]`
+      );
+      aspects.push(parsed.id);
+      if (parsed.when) {
+        (aspectWhens ??= {})[parsed.id] = parsed.when;
+      }
+    }
   }
   return {
     path: path8.basename(flowDir),
     name: raw.name.trim(),
     description,
     nodes: nodePaths,
-    ...aspects !== void 0 && { aspects }
+    ...aspects !== void 0 && { aspects },
+    ...aspectWhens && { aspectWhens }
   };
 }
 
@@ -2247,12 +2340,28 @@ async function parseArchitecture(filePath) {
         `yg-architecture.yaml: node type '${typeName}' has unknown field 'integration_aspects'. Use ports on the target node instead.`
       );
     }
-    const aspects = Array.isArray(entry.aspects) ? entry.aspects.filter((t) => typeof t === "string") : void 0;
+    let aspects;
+    let aspectWhens;
+    if (Array.isArray(entry.aspects)) {
+      aspects = [];
+      for (let i = 0; i < entry.aspects.length; i++) {
+        const parsed = parseAspectAttachment(
+          entry.aspects[i],
+          `yg-architecture.yaml: node_types.${typeName}.aspects[${i}]`
+        );
+        aspects.push(parsed.id);
+        if (parsed.when) {
+          (aspectWhens ??= {})[parsed.id] = parsed.when;
+        }
+      }
+      if (aspects.length === 0) aspects = void 0;
+    }
     const parents = Array.isArray(entry.parents) ? entry.parents.filter((t) => typeof t === "string") : void 0;
     const relations = parseRelations2(entry.relations, typeName);
     nodeTypes[typeName] = {
       description: entry.description,
-      aspects: aspects && aspects.length > 0 ? aspects : void 0,
+      aspects,
+      ...aspectWhens && { aspectWhens },
       parents: parents && parents.length > 0 ? parents : void 0,
       relations
     };
@@ -2529,57 +2638,191 @@ async function loadSchemas(schemasDir) {
 import { readFile as readFile13 } from "fs/promises";
 import path12 from "path";
 
+// src/core/when-evaluator.ts
+function evaluateWhen(predicate, node, graph) {
+  if ("all_of" in predicate) {
+    return predicate.all_of.every((p2) => evaluateWhen(p2, node, graph));
+  }
+  if ("any_of" in predicate) {
+    return predicate.any_of.some((p2) => evaluateWhen(p2, node, graph));
+  }
+  if ("not" in predicate) {
+    return !evaluateWhen(predicate.not, node, graph);
+  }
+  return evaluateAtomic(predicate, node, graph);
+}
+function evaluateAtomic(clause, node, graph) {
+  if (clause.relations) {
+    if (!evaluateRelationClause(clause.relations, node.meta.relations ?? [], graph)) return false;
+  }
+  if (clause.descendants) {
+    if (!evaluateDescendantsClause(clause.descendants, node, graph)) return false;
+  }
+  if (clause.node) {
+    if (!evaluateNodeClause(clause.node, node)) return false;
+  }
+  return true;
+}
+function evaluateRelationClause(rc, relations, graph) {
+  for (const [relType, match] of Object.entries(rc)) {
+    if (!match) continue;
+    const candidates = relations.filter((r) => r.type === relType);
+    if (!candidates.some((r) => matchesRelation(r, match, graph))) {
+      return false;
+    }
+  }
+  return true;
+}
+function matchesRelation(r, match, graph) {
+  if (match.target !== void 0 && r.target !== match.target) return false;
+  if (match.target_type !== void 0) {
+    const tgt = graph.nodes.get(r.target);
+    if (!tgt || tgt.meta.type !== match.target_type) return false;
+  }
+  if (match.consumes_port !== void 0) {
+    if (!r.consumes || !r.consumes.includes(match.consumes_port)) return false;
+  }
+  return true;
+}
+function evaluateDescendantsClause(dc, node, graph) {
+  const descendants = collectDescendants(node);
+  if (descendants.length === 0) return false;
+  if (dc.type !== void 0) {
+    if (!descendants.some((d) => d.meta.type === dc.type)) return false;
+  }
+  if (dc.has_port !== void 0) {
+    if (!descendants.some((d) => d.meta.ports && Object.prototype.hasOwnProperty.call(d.meta.ports, dc.has_port))) {
+      return false;
+    }
+  }
+  if (dc.relations) {
+    if (!descendants.some((d) => evaluateRelationClause(dc.relations, d.meta.relations ?? [], graph))) {
+      return false;
+    }
+  }
+  return true;
+}
+function evaluateNodeClause(nc, node) {
+  if (nc.type !== void 0 && node.meta.type !== nc.type) return false;
+  if (nc.has_port !== void 0) {
+    if (!node.meta.ports || !Object.prototype.hasOwnProperty.call(node.meta.ports, nc.has_port)) return false;
+  }
+  if (nc.has_mapping !== void 0) {
+    const has = (node.meta.mapping?.length ?? 0) > 0;
+    if (has !== nc.has_mapping) return false;
+  }
+  return true;
+}
+function collectDescendants(node) {
+  const out = [];
+  const queue = [...node.children];
+  while (queue.length > 0) {
+    const curr = queue.shift();
+    out.push(curr);
+    for (const c of curr.children) queue.push(c);
+  }
+  return out;
+}
+
 // src/core/effective-aspects.ts
 function computeEffectiveAspects(node, graph) {
-  const raw = /* @__PURE__ */ new Set();
+  const direct = /* @__PURE__ */ new Set();
+  const ancestors = collectAncestors(node);
+  const tryAdd = (aspectId, attachWhen) => {
+    const aspectDef = graph.aspects.find((a) => a.id === aspectId);
+    const globalWhen = aspectDef?.when;
+    if (globalWhen && !evaluateWhen(globalWhen, node, graph)) {
+      debugWrite(`[effective-aspects] node '${node.path}' aspect '${aspectId}' filtered: global when=false`);
+      return;
+    }
+    if (attachWhen && !evaluateWhen(attachWhen, node, graph)) {
+      debugWrite(`[effective-aspects] node '${node.path}' aspect '${aspectId}' filtered: attach-site when=false`);
+      return;
+    }
+    direct.add(aspectId);
+  };
   for (const id of node.meta.aspects ?? []) {
-    raw.add(id);
+    tryAdd(id, node.meta.aspectWhens?.[id]);
   }
-  const ancestors = collectAncestors(node);
   for (const ancestor of ancestors) {
     for (const id of ancestor.meta.aspects ?? []) {
-      raw.add(id);
+      tryAdd(id, ancestor.meta.aspectWhens?.[id]);
     }
   }
   if (graph.architecture) {
     const typeDef = graph.architecture.node_types[node.meta.type];
     for (const id of typeDef?.aspects ?? []) {
-      raw.add(id);
+      tryAdd(id, typeDef?.aspectWhens?.[id]);
     }
   }
   if (graph.architecture) {
     for (const ancestor of ancestors) {
       const typeDef = graph.architecture.node_types[ancestor.meta.type];
       for (const id of typeDef?.aspects ?? []) {
-        raw.add(id);
+        tryAdd(id, typeDef?.aspectWhens?.[id]);
       }
     }
   }
   const allPaths = /* @__PURE__ */ new Set([node.path, ...ancestors.map((a) => a.path)]);
   for (const flow of graph.flows) {
-    if (flow.nodes.some((n) => allPaths.has(n))) {
-      for (const id of flow.aspects ?? []) {
-        raw.add(id);
-      }
+    if (!flow.nodes.some((n) => allPaths.has(n))) continue;
+    for (const id of flow.aspects ?? []) {
+      tryAdd(id, flow.aspectWhens?.[id]);
     }
   }
   if (node.meta.relations) {
     for (const relation of node.meta.relations) {
       const targetNode = graph.nodes.get(relation.target);
       if (!targetNode) continue;
-      if (relation.consumes && targetNode.meta.ports) {
-        for (const portName of relation.consumes) {
-          const port = targetNode.meta.ports[portName];
-          if (port?.aspects) {
-            for (const id of port.aspects) {
-              raw.add(id);
-            }
-          }
+      if (!relation.consumes || !targetNode.meta.ports) continue;
+      for (const portName of relation.consumes) {
+        const port = targetNode.meta.ports[portName];
+        if (!port?.aspects) continue;
+        for (const id of port.aspects) {
+          tryAdd(id, port.aspectWhens?.[id]);
         }
       }
     }
   }
-  return expandImplies(raw, graph);
+  return expandImpliesFiltered(direct, node, graph);
+}
+function expandImpliesFiltered(directIds, node, graph) {
+  const idToAspect = /* @__PURE__ */ new Map();
+  for (const a of graph.aspects) idToAspect.set(a.id, a);
+  const result = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  const visit = (id, implierId) => {
+    if (stack.has(id)) {
+      throw new Error(`Aspect implies cycle detected involving aspect '${id}'`);
+    }
+    if (visited.has(id)) return;
+    const aspectDef = idToAspect.get(id);
+    if (aspectDef?.when && !evaluateWhen(aspectDef.when, node, graph)) {
+      debugWrite(`[effective-aspects] node '${node.path}' aspect '${id}' filtered: global when=false (implies path)`);
+      return;
+    }
+    if (implierId) {
+      const implierDef = idToAspect.get(implierId);
+      const perImplies = implierDef?.impliesWhens?.[id];
+      if (perImplies && !evaluateWhen(perImplies, node, graph)) {
+        debugWrite(`[effective-aspects] node '${node.path}' aspect '${id}' filtered: impliesWhens from '${implierId}' is false`);
+        return;
+      }
+    }
+    stack.add(id);
+    visited.add(id);
+    result.add(id);
+    const implies = aspectDef?.implies;
+    if (implies) {
+      for (const implied of implies) {
+        visit(implied, id);
+      }
+    }
+    stack.delete(id);
+  };
+  for (const id of directIds) visit(id, null);
+  return result;
 }
 function getAspectSource(aspectId, node, graph) {
   if (node.meta.aspects?.includes(aspectId)) {
@@ -2646,37 +2889,6 @@ function collectAncestors(node) {
   }
   return ancestors;
 }
-function expandImplies(aspectIds, graph) {
-  const idToImplies = /* @__PURE__ */ new Map();
-  for (const aspect of graph.aspects) {
-    if (aspect.implies) {
-      idToImplies.set(aspect.id, aspect.implies);
-    }
-  }
-  const result = /* @__PURE__ */ new Set();
-  const visited = /* @__PURE__ */ new Set();
-  const stack = /* @__PURE__ */ new Set();
-  function collect(id) {
-    if (stack.has(id)) {
-      throw new Error(`Aspect implies cycle detected involving aspect '${id}'`);
-    }
-    if (visited.has(id)) return;
-    stack.add(id);
-    visited.add(id);
-    result.add(id);
-    const implies = idToImplies.get(id);
-    if (implies) {
-      for (const implied of implies) {
-        collect(implied);
-      }
-    }
-    stack.delete(id);
-  }
-  for (const id of aspectIds) {
-    collect(id);
-  }
-  return result;
-}
 
 // src/core/context-builder.ts
 var STRUCTURAL_RELATION_TYPES = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
@@ -3069,13 +3281,6 @@ async function expandMappingPaths(projectRoot, mappingPaths) {
   return result;
 }
 
-// src/formatters/message-builder.ts
-function buildIssueMessage(msg) {
-  return `${msg.what}
-${msg.why}
-${msg.next}`;
-}
-
 // src/core/validator.ts
 async function validate(graph, scope = "all") {
   const issues = [];
@@ -3126,6 +3331,7 @@ async function validate(graph, scope = "all") {
   issues.push(...checkPortAspectsDefined(graph));
   issues.push(...checkPortConsumes(graph));
   issues.push(...checkOrphanedAspects(graph));
+  issues.push(...checkWhenReferences(graph));
   let filtered = issues;
   let nodesScanned = graph.nodes.size;
   const normalizedScope = scope.trim().replace(/\\/g, "/").replace(/\/+$/, "");
@@ -3943,6 +4149,141 @@ function checkOrphanedAspects(graph) {
   }
   return issues;
 }
+function checkWhenReferences(graph) {
+  const issues = [];
+  const knownTypes = new Set(Object.keys(graph.architecture?.node_types ?? {}));
+  const visitPredicate = (p2, ctx) => {
+    if ("all_of" in p2) {
+      p2.all_of.forEach((c, i) => visitPredicate(c, `${ctx}/all_of[${i}]`));
+      return;
+    }
+    if ("any_of" in p2) {
+      p2.any_of.forEach((c, i) => visitPredicate(c, `${ctx}/any_of[${i}]`));
+      return;
+    }
+    if ("not" in p2) {
+      visitPredicate(p2.not, `${ctx}/not`);
+      return;
+    }
+    visitAtomic(p2, ctx);
+  };
+  const visitAtomic = (a, ctx) => {
+    if (a.relations) visitRelationClause(a.relations, `${ctx}/relations`);
+    if (a.descendants) visitDescendantsClause(a.descendants, `${ctx}/descendants`);
+    if (a.node) visitNodeClause(a.node, `${ctx}/node`);
+  };
+  const visitRelationClause = (rc, ctx) => {
+    for (const [relType, match] of Object.entries(rc)) {
+      if (!match) continue;
+      if (match.target_type !== void 0 && !knownTypes.has(match.target_type)) {
+        issues.push({
+          severity: "error",
+          code: "when-unknown-type",
+          rule: "when-unknown-type",
+          message: buildIssueMessage({
+            what: `Unknown node type '${match.target_type}' in when at ${ctx}/${relType}.target_type.`,
+            why: "The predicate references a type that is not defined in yg-architecture.yaml; it will never evaluate.",
+            next: `Fix the type name or define it in yg-architecture.yaml. Known types: ${Array.from(knownTypes).join(", ")}.`
+          })
+        });
+      }
+      if (match.target !== void 0 && !graph.nodes.has(match.target)) {
+        issues.push({
+          severity: "error",
+          code: "when-unknown-node",
+          rule: "when-unknown-node",
+          message: buildIssueMessage({
+            what: `Referenced node '${match.target}' in when at ${ctx}/${relType}.target does not exist.`,
+            why: "The predicate targets a node that is not in the graph.",
+            next: `Fix the node path or add the node under .yggdrasil/model/.`
+          })
+        });
+      }
+      if (match.consumes_port !== void 0 && match.target !== void 0) {
+        const tgt = graph.nodes.get(match.target);
+        if (tgt && !(tgt.meta.ports && match.consumes_port in tgt.meta.ports)) {
+          issues.push({
+            severity: "error",
+            code: "when-unknown-port",
+            rule: "when-unknown-port",
+            message: buildIssueMessage({
+              what: `Port '${match.consumes_port}' is not declared on node '${match.target}' in when at ${ctx}/${relType}.consumes_port.`,
+              why: "The predicate references a port that does not exist on the target node.",
+              next: `Fix the port name or add it to .yggdrasil/model/${match.target}/yg-node.yaml.`
+            })
+          });
+        }
+      }
+    }
+  };
+  const visitDescendantsClause = (dc, ctx) => {
+    if (dc.relations) visitRelationClause(dc.relations, `${ctx}/relations`);
+    if (dc.type !== void 0 && !knownTypes.has(dc.type)) {
+      issues.push({
+        severity: "error",
+        code: "when-unknown-type",
+        rule: "when-unknown-type",
+        message: buildIssueMessage({
+          what: `Unknown node type '${dc.type}' in when at ${ctx}/type.`,
+          why: "The predicate references a type that is not defined in yg-architecture.yaml.",
+          next: `Fix the type name or define it in yg-architecture.yaml. Known types: ${Array.from(knownTypes).join(", ")}.`
+        })
+      });
+    }
+  };
+  const visitNodeClause = (nc, ctx) => {
+    if (nc.type !== void 0 && !knownTypes.has(nc.type)) {
+      issues.push({
+        severity: "error",
+        code: "when-unknown-type",
+        rule: "when-unknown-type",
+        message: buildIssueMessage({
+          what: `Unknown node type '${nc.type}' in when at ${ctx}/type.`,
+          why: "The predicate references a type that is not defined in yg-architecture.yaml.",
+          next: `Fix the type name or define it in yg-architecture.yaml. Known types: ${Array.from(knownTypes).join(", ")}.`
+        })
+      });
+    }
+  };
+  for (const aspect of graph.aspects) {
+    if (aspect.when) visitPredicate(aspect.when, `aspect '${aspect.id}' when`);
+    if (aspect.impliesWhens) {
+      for (const [targetId, pred] of Object.entries(aspect.impliesWhens)) {
+        visitPredicate(pred, `aspect '${aspect.id}' implies[${targetId}] when`);
+      }
+    }
+  }
+  if (graph.architecture) {
+    for (const [typeName, typeDef] of Object.entries(graph.architecture.node_types)) {
+      if (!typeDef.aspectWhens) continue;
+      for (const [aspectId, pred] of Object.entries(typeDef.aspectWhens)) {
+        visitPredicate(pred, `architecture node_types.${typeName} aspectWhens[${aspectId}]`);
+      }
+    }
+  }
+  for (const [nodePath, node] of graph.nodes) {
+    if (node.meta.aspectWhens) {
+      for (const [aspectId, pred] of Object.entries(node.meta.aspectWhens)) {
+        visitPredicate(pred, `node '${nodePath}' aspectWhens[${aspectId}]`);
+      }
+    }
+    if (node.meta.ports) {
+      for (const [portName, portDef] of Object.entries(node.meta.ports)) {
+        if (!portDef.aspectWhens) continue;
+        for (const [aspectId, pred] of Object.entries(portDef.aspectWhens)) {
+          visitPredicate(pred, `node '${nodePath}' ports.${portName} aspectWhens[${aspectId}]`);
+        }
+      }
+    }
+  }
+  for (const flow of graph.flows) {
+    if (!flow.aspectWhens) continue;
+    for (const [aspectId, pred] of Object.entries(flow.aspectWhens)) {
+      visitPredicate(pred, `flow '${flow.path}' aspectWhens[${aspectId}]`);
+    }
+  }
+  return issues;
+}
 
 // src/cli/owner.ts
 import path15 from "path";
@@ -4240,12 +4581,14 @@ async function writeNodeDriftState(yggRoot, nodePath, nodeState) {
   const content = JSON.stringify(nodeState, null, 2) + "\n";
   await writeFile5(filePath, content, "utf-8");
 }
-async function garbageCollectDriftState(yggRoot, validNodePaths) {
+async function garbageCollectDriftState(yggRoot, validNodePaths, shouldKeep) {
   const driftDir = path16.join(yggRoot, DRIFT_STATE_DIR);
   const allNodePaths = await scanJsonFiles(driftDir, driftDir);
   const removed = [];
   for (const nodePath of allNodePaths) {
-    if (!validNodePaths.has(nodePath)) {
+    const inGraph = validNodePaths.has(nodePath);
+    const keep = inGraph && (shouldKeep ? shouldKeep(nodePath) : true);
+    if (!keep) {
       const filePath = nodeStatePath(yggRoot, nodePath);
       await rm2(filePath);
       await removeEmptyParents(filePath, driftDir);
@@ -4524,7 +4867,16 @@ function getChildMappingExclusions(graph, nodePath) {
 }
 async function runGC(graph) {
   const validPaths = new Set(graph.nodes.keys());
-  return garbageCollectDriftState(graph.rootPath, validPaths);
+  return garbageCollectDriftState(
+    graph.rootPath,
+    validPaths,
+    (nodePath) => {
+      const node = graph.nodes.get(nodePath);
+      if (!node) return false;
+      const effective = computeEffectiveAspects(node, graph);
+      return effective.size > 0;
+    }
+  );
 }
 async function commitApproval(yggRoot, result) {
   if (result.pendingDriftState) {
@@ -4824,6 +5176,15 @@ async function runCheck(graph, gitTrackedFiles) {
     coverageIssue = buildCoverageIssue(uncovered, totalFiles);
   }
   const orphanedPaths = await detectOrphanedDriftState(graph);
+  await garbageCollectDriftState(
+    graph.rootPath,
+    new Set(graph.nodes.keys()),
+    (nodePath) => {
+      const node = graph.nodes.get(nodePath);
+      if (!node) return false;
+      return computeEffectiveAspects(node, graph).size > 0;
+    }
+  );
   const yggRelative = path19.relative(path19.dirname(graph.rootPath), graph.rootPath).replace(/\\/g, "/").replace(/\/+$/, "");
   const orphanWarnings = orphanedPaths.map((p2) => ({
     severity: "warning",
@@ -5472,26 +5833,57 @@ async function loadSecrets(rootPath, providerName) {
     return void 0;
   }
   const raw = parseYaml9(content);
-  if (!raw) return void 0;
-  if (raw.reviewer && typeof raw.reviewer === "object") {
-    const reviewerRaw = raw.reviewer;
-    if (!providerName) return void 0;
-    const providerKey = providerName;
-    const providerSection = reviewerRaw[providerKey];
-    if (!providerSection || typeof providerSection !== "object") return void 0;
-    return extractSecretFields(providerSection);
-  }
-  return void 0;
-}
-function extractSecretFields(raw) {
+  if (raw === null || raw === void 0) return void 0;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`yg-secrets.yaml: top level must be a YAML mapping`);
+  }
+  const rawObj = raw;
+  if (rawObj.reviewer === void 0) return void 0;
+  if (typeof rawObj.reviewer !== "object" || rawObj.reviewer === null || Array.isArray(rawObj.reviewer)) {
+    throw new Error(`yg-secrets.yaml: 'reviewer' must be a YAML mapping`);
+  }
+  if (!providerName) return void 0;
+  const reviewerRaw = rawObj.reviewer;
+  const providerSection = reviewerRaw[providerName];
+  if (providerSection === void 0) return void 0;
+  if (typeof providerSection !== "object" || providerSection === null || Array.isArray(providerSection)) {
+    throw new Error(`yg-secrets.yaml: 'reviewer.${providerName}' must be a YAML mapping`);
+  }
+  return extractSecretFields(providerSection, providerName);
+}
+function extractSecretFields(raw, providerName) {
+  const ctx = (field) => `yg-secrets.yaml at reviewer.${providerName}.${field}`;
   const partial = {};
-  if (typeof raw.api_key === "string") partial.api_key = raw.api_key;
-  if (typeof raw.provider === "string") partial.provider = raw.provider;
-  if (typeof raw.model === "string") partial.model = raw.model;
-  if (typeof raw.endpoint === "string") partial.endpoint = raw.endpoint;
-  if (typeof raw.temperature === "number") partial.temperature = raw.temperature;
-  if (typeof raw.consensus === "number") partial.consensus = raw.consensus;
-  if (raw.max_tokens !== void 0) partial.max_tokens = raw.max_tokens;
+  if (raw.api_key !== void 0) {
+    if (typeof raw.api_key !== "string") throw new Error(`${ctx("api_key")}: must be a string`);
+    partial.api_key = raw.api_key;
+  }
+  if (raw.provider !== void 0) {
+    if (typeof raw.provider !== "string") throw new Error(`${ctx("provider")}: must be a string`);
+    partial.provider = raw.provider;
+  }
+  if (raw.model !== void 0) {
+    if (typeof raw.model !== "string") throw new Error(`${ctx("model")}: must be a string`);
+    partial.model = raw.model;
+  }
+  if (raw.endpoint !== void 0) {
+    if (typeof raw.endpoint !== "string") throw new Error(`${ctx("endpoint")}: must be a string`);
+    partial.endpoint = raw.endpoint;
+  }
+  if (raw.temperature !== void 0) {
+    if (typeof raw.temperature !== "number") throw new Error(`${ctx("temperature")}: must be a number`);
+    partial.temperature = raw.temperature;
+  }
+  if (raw.consensus !== void 0) {
+    if (typeof raw.consensus !== "number") throw new Error(`${ctx("consensus")}: must be a number`);
+    partial.consensus = raw.consensus;
+  }
+  if (raw.max_tokens !== void 0) {
+    if (typeof raw.max_tokens !== "number" && raw.max_tokens !== "auto") {
+      throw new Error(`${ctx("max_tokens")}: must be a number or 'auto'`);
+    }
+    partial.max_tokens = raw.max_tokens;
+  }
   return Object.keys(partial).length > 0 ? partial : void 0;
 }
 function mergeLlmConfig(base, secrets) {
@@ -5988,7 +6380,7 @@ function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   }
   return chains.sort();
 }
-function collectDescendants(graph, nodePath) {
+function collectDescendants2(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) return [];
   const result = [];
@@ -6142,7 +6534,7 @@ async function handleFlowImpact(graph, flowName) {
   for (const nodePath of flow.nodes) {
     if (graph.nodes.has(nodePath)) {
       participants.add(nodePath);
-      for (const desc of collectDescendants(graph, nodePath)) {
+      for (const desc of collectDescendants2(graph, nodePath)) {
         participants.add(desc);
       }
     }
@@ -6318,7 +6710,7 @@ function registerImpactCommand(program2) {
 `);
           }
         }
-        const descendants = collectDescendants(graph, nodePath);
+        const descendants = collectDescendants2(graph, nodePath);
         if (descendants.length > 0) {
           process.stdout.write("\nDescendants (hierarchy impact):\n");
           for (const desc of descendants) {