@chrisdudek/yg 4.2.0 → 5.0.0-alpha.1

package/graph-schemas/yg-architecture.yaml

@@ -9,16 +9,49 @@
 
 node_types:
   <type-id>:
-    description: <string>                    # required — what this type is for, when to use it
+    description: <string>                    # required — what this type is for, when to use it.
+                                             # Validator emits description-missing if absent.
+
+    when: <file-predicate>                   # optional — per-file classification.
+                                             # Types WITH `when` are file-classifying: every file in
+                                             # a node's mapping must satisfy the predicate (forward
+                                             # check). Types WITHOUT `when` are organizational:
+                                             # parent-only nodes — any mapping fires
+                                             # type-without-when-with-mapping.
+                                             #
+                                             # Grammar:
+                                             #   path: <glob>                — minimatch glob on repo-relative POSIX path
+                                             #   content: <regex>            — JavaScript regex against file content
+                                             #   path + content combined     — implicit all_of of both atoms
+                                             #   all_of: [<predicate>, ...]  — every child must satisfy
+                                             #   any_of: [<predicate>, ...]  — at least one child must satisfy
+                                             #   not: <predicate>            — single child negation
+                                             #
+                                             # See: yg knowledge read working-with-architecture
+
+    enforce: strict                          # optional — bidirectional enforcement.
+                                             # Requires `when`. Every repo file matching the type's
+                                             # `when` MUST belong to exactly one node of this type
+                                             # (backward scan). A matching file owned by no such node
+                                             # emits type-strict-orphan; one owned by a node of a
+                                             # different type emits type-strict-misplaced.
+                                             # Use only for types where missing the type means missing
+                                             # a critical aspect (security, audit, regulatory).
+
+    log_required: <boolean>                  # optional — default true. Set false for infrastructure
+                                             # or utility types where an approval log adds no value
+                                             # (e.g. config, types, constants).
 
     aspects:                                 # optional — aspects automatically applied to every
                                              # node of this type (channel 3). Two forms per entry:
-      - simple-aspect                        #   bare string — unconditional
-      - id: conditional-aspect               #   object form — with per-site applicability filter
-        when: <predicate>                    #   see graph-schemas/yg-aspect.yaml for grammar
+      - <aspect-id>                          #   bare string — unconditional
+      - id: <aspect-id>                      #   object form — with per-site applicability filter
+        status: enforced                     #   optional — explicit status override (channel 3).
+                                             #   Must satisfy bump rule (bump up OK, downgrade is validator error).
+        when: <aspect-predicate>             #   optional — see schemas/yg-aspect.yaml for grammar
                                              # These also cascade to children (channel 4).
 
-    parents: [<type-id>]                     # optional — allowed parent node types in the hierarchy.
+    parents: [<type-id>, ...]                # optional — allowed parent node types in the hierarchy.
 
     relations:                               # optional — allowed relation targets by relation type.
-      <relation-type>: [<type-id>]           # calls | uses | extends | implements | emits | listens
+      <relation-type>: [<type-id>, ...]      # calls | uses | extends | implements | emits | listens

package/graph-schemas/yg-aspect.yaml

@@ -1,6 +1,7 @@
 # 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.
+# plus any number of .md content files (for LLM aspects) or a check.mjs
+# (for deterministic aspects).
 #
 # Aspect identifier = relative path from aspects/ to the directory
 # (e.g. observability/logging). Aspects can be organized in nested
@@ -11,14 +12,56 @@
 # They should state WHAT must be satisfied and WHY.
 
 name: CrossCuttingRequirementName  # required — display name
-description: "Short description"   # optional but recommended — shown in yg aspects output
-                                   # and context packages, helps agents discover relevant aspects
+description: "Short description"   # required — shown in yg aspects output and context packages.
+                                   # Validator emits description-missing if absent.
+
+reviewer:                          # required — which reviewer verifies this aspect
+  type: llm                        #   required: 'llm' or 'deterministic'
+                                   #     llm           — aspect ships content.md; an LLM reads it and judges the code.
+                                   #     deterministic — aspect ships check.mjs; the structure runner executes it
+                                   #                     locally with graph-aware ctx (files, fs, graph, parsers).
+                                   #                     Language-agnostic. No LLM call, zero token cost.
+  # tier: deep                     #   optional, only when type: llm.
+                                   #     If omitted, the aspect uses reviewer.default from yg-config.yaml.
+                                   #     If present, must reference a key under reviewer.tiers in the config.
+                                   #     Forbidden when type is 'deterministic'.
+
+status: enforced                   # optional — aspect-level default. enum: draft | advisory | enforced.
+                                   # Absent → 'enforced'.
+                                   # draft     = reviewer skipped, no verdict, no baseline, no drift.
+                                   # advisory  = reviewer runs; refused → warning (no block).
+                                   # enforced  = reviewer runs; refused → error (blocks check).
+                                   # This is only the aspect-level default. The effective status on a
+                                   # node is max() across cascading channels 1–6; channel 7 (implies)
+                                   # carries status_inherit instead. Downgrade attempts are validator
+                                   # errors. Advisory and enforced verdicts are recorded in the
+                                   # baseline; draft aspects get no verdict.
 
 # implies:                         # optional — other aspects included automatically when this
 #                                  # aspect is effective on a node. Two forms:
 #   - simple-aspect-id             # bare string — implied unconditionally (when outer aspect passes)
 #   - id: conditional-aspect-id    # object form — imply only when `when` passes on the node
 #     when: <predicate>            # see `when` section below for grammar
+#     status_inherit: strictest    # optional — propagation modifier for this implies edge.
+                                   # enum: strictest | own-default.
+                                   # Absent → 'strictest' (implied aspect promotes to
+                                   # the implier's effective status if higher than the
+                                   # implied aspect's own default).
+                                   # 'own-default' anchors the implied aspect to its
+                                   # own aspect-level default (decouples from implier).
+                                   #
+                                   # ASYMMETRY NOTE: attach-site entries on channels
+                                   # 1–6 (node, ancestor, architecture type, ancestor
+                                   # type, flow, port) carry an explicit `status:`
+                                   # VALUE. Channel 7 (implies) carries a propagation
+                                   # MODIFIER (`status_inherit:`) instead. Implies is
+                                   # not a direct attach — the implied aspect's status
+                                   # is structurally derived from the implier's
+                                   # effective status on the node. The modifier
+                                   # selects how to derive; a value-overriding
+                                   # `status:` on an implies edge would couple the
+                                   # edge to a literal that becomes stale if the
+                                   # implied aspect's own default changes.
                                    # Chains expand recursively. Cycles are forbidden — CLI detects.
 
 # when: <predicate>                # optional — applicability filter. If the predicate evaluates
@@ -53,3 +96,26 @@ description: "Short description"   # optional but recommended — shown in yg as
                                    #     any_of:
                                    #       - relations: { calls: { target_type: service-client } }
                                    #       - descendants: { relations: { calls: { target_type: service-client } } }
+
+# references:                      # optional — supporting files for the LLM reviewer.
+                                   #   Permitted on LLM aspects ONLY (forbidden on deterministic).
+                                   #   Each entry is a string (shorthand) OR an object { path, description? }.
+                                   #
+                                   # Example:
+                                   #   references:
+                                   #     - docs/error-codes.md                    # shorthand
+                                   #     - path: source/cli/src/errors/codes.ts
+                                   #       description: "Catalogue of valid error codes; reviewer rejects unknown codes."
+                                   #
+                                   # Constraints (validated by `yg check`):
+                                   #   - Path is repo-root-relative.
+                                   #   - No '..' that escapes the repo root; no leading '/'; no Windows drive letter; no '~'.
+                                   #   - File must exist at check time and resolve (after symlink follow) to a regular file.
+                                   #   - No duplicates within one aspect.
+                                   #
+                                   # Drift semantics: changes to referenced files cascade to all nodes where this
+                                   # aspect is effective — same as changes to content.md. Run `yg impact --file <ref>`
+                                   # before editing a widely-referenced file.
+                                   #
+                                   # Size limits: per-tier caps via reviewer.tiers.<tier>.references.* in yg-config.yaml.
+                                   # Defaults: 64 KiB per file, 256 KiB total per aspect.

package/graph-schemas/yg-config.yaml

@@ -2,12 +2,12 @@
 # Located at .yggdrasil/yg-config.yaml — one per project.
 # Edit this after running yg init to describe your project.
 
-version: "4.0.0"                  # managed by CLI — do not edit manually. Tracks the CLI version
+version: "5.0.0"                  # managed by CLI — do not edit manually. Tracks the CLI version
                                   # that last initialized or upgraded this config.
 
 quality:                          # optional — quality thresholds
   max_direct_relations: 10        #   maximum outgoing relations per node (warning if above)
-  max_mapping_source_files: 10    #   maximum source files per node (warning if above, for nodes with aspects)
+  max_node_chars: 40000           #   per-node character budget — mapped source + aspect reference files (error if above; binaries skipped; opt out per-node via sizeExempt)
 
 parallel: 1                       # optional — concurrency limit for batch approve (positive integer, default: 1)
 
@@ -15,13 +15,29 @@ debug: false                      # optional — when true, appends all command
                                   # Default: false (off). Log is append-only; rotate or delete manually.
 
 reviewer:                         # required — aspect verification during yg approve
-  active: ollama                  #   required when multiple providers configured
-  consensus: 1                    #   positive odd integer >= 1 (3+ for majority vote)
-  ollama:                         #   provider-specific config
-    model: "qwen3.5:9b"          #     model ID
-    endpoint: "http://localhost:11434"  #   custom endpoint
-    temperature: 0                #     reduces variability — keep at 0
-    max_tokens: auto              #     auto = query provider, or explicit number
-    context_length_field: ""      #     ollama model_info key for context window size
-  claude-code:                    #   alternative provider — uses claude CLI subprocess
-    model: haiku                  #     haiku, sonnet, or opus
+  default: standard               # required when more than one tier is configured; optional with exactly one tier.
+                                  #   Must reference one of the keys under reviewer.tiers.
+  tiers:                          # required — named tier configurations, minimum one entry.
+    standard:                     #   tier name — referenced from aspects via reviewer.tier:
+      provider: ollama            #     provider id (one of: ollama, openai, anthropic, google,
+                                  #                       openai-compatible, claude-code, codex, gemini-cli)
+      consensus: 1                #     positive odd integer >= 1 (3+ for majority vote). Per-tier.
+      config:                     #     provider-specific settings — same fields the provider accepts.
+        model: "qwen3.5:9b"       #       model id
+        endpoint: "http://localhost:11434"   # custom endpoint (required for ollama, openai-compatible)
+        temperature: 0            #       reduces variability — keep at 0
+        max_tokens: auto          #       auto = query provider, or explicit positive integer
+        context_length_field: ""  #       ollama: model_info key for context window size
+        # timeout: 300            #       Per-call timeout in SECONDS (default 300). Only CLI providers.
+      # references:                # optional — limits on aspect reference files for aspects resolving to this tier
+      #   max_bytes_per_file: 65536          # positive integer; default 65536 (64 KiB)
+      #   max_total_bytes_per_aspect: 262144 # positive integer; default 262144 (256 KiB)
+    # Add more tiers as needed (e.g. a `deep` tier with a higher-capability model for critical aspects).
+    # An aspect references a non-default tier via:
+    #
+    #   reviewer:
+    #     type: llm
+    #     tier: deep
+    #
+    # Tier names match ^[a-zA-Z][a-zA-Z0-9_-]{0,62}$ and `default` is reserved.
+    # API keys live in yg-secrets.yaml (api_key only) — never in this file.

package/graph-schemas/yg-flow.yaml

@@ -9,8 +9,8 @@
 # listing a parent node covers all its children.
 
 name: EndToEndProcessName     # required — display name
-description: "What this business process does"  # optional but recommended — shown in
-                                                # yg flows output and context packages
+description: "What this business process does"  # required — shown in yg flows output and
+                                                # context packages. Validator emits description-missing if absent.
 
 nodes:                        # required, non-empty — participant nodes (alias: participants)
   - orders/order-service      # paths relative to model/
@@ -20,4 +20,6 @@ nodes:                        # required, non-empty — participant nodes (alias
 aspects:                      # optional — aspects propagate to all flow participants (channel 5)
   - simple-aspect             #   bare string
   - id: conditional-aspect    #   object form with per-site applicability filter
-    when: <predicate>         #   see graph-schemas/yg-aspect.yaml for grammar
+    status: enforced          #   optional — explicit status override (channel 5).
+                              #   Must satisfy bump rule (bump up OK, downgrade is validator error).
+    when: <predicate>         #   optional — see schemas/yg-aspect.yaml for grammar

package/graph-schemas/yg-node.yaml

@@ -6,14 +6,16 @@
 
 name: ComponentName           # required — display name
 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
+description: "What this node does"  # required — shown in context output and helps agents
+                                    # understand purpose. Validator emits description-missing if absent.
 
 aspects:                      # optional — aspect identifiers applied directly to this node.
                               # Two forms per entry:
   - simple-aspect             #   bare string — always effective once attached (channel 1)
   - id: conditional-aspect    #   object form — attach with per-site applicability filter
-    when: <predicate>         #   see graph-schemas/yg-aspect.yaml for grammar
+    status: enforced          #   optional — explicit status override (channel 1).
+                              #   Must satisfy bump rule (bump up OK, downgrade is validator error).
+    when: <predicate>         #   optional — see schemas/yg-aspect.yaml for grammar
                               # Aspects cascade to all child nodes.
 
 ports:                        # optional — named entry points with required aspects
@@ -22,16 +24,28 @@ ports:                        # optional — named entry points with required as
     aspects:                  # required — aspects consumers must satisfy (channel 6)
       - simple-aspect         #   bare string form
       - id: conditional-aspect
-        when: <predicate>     #   object form with per-attach applicability filter
+        status: enforced      #   optional — explicit status override (channel 6).
+                              #   Must satisfy bump rule (bump up OK, downgrade is validator error).
+        when: <predicate>     #   optional — object form with per-attach applicability filter
 
 relations:                    # optional — outgoing dependencies to other nodes
   - 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 declares ports — otherwise check warns
+                              # required when target declares ports — otherwise yg check emits a
+                              # BLOCKING ERROR (port-missing-consumes) that fails the architecture gate.
+                              # There is no waiver; resolve by adding consumes or removing the ports.
+                              # Naming a target that declares no ports raises consumes-without-ports.
 
 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
+
+sizeExempt:                   # optional — opt out of the per-node character budget (quality.max_node_chars)
+  reason: "package-lock.json is npm-generated and cannot be split"  # required — non-empty justification
+                              # Binary files (images, fonts, archives, etc.) count 0 toward the budget
+                              # automatically — they never need sizeExempt. Use sizeExempt ONLY for a
+                              # large unsplittable TEXT artifact (e.g. a generated lockfile), not images.
+                              # Normal oversized nodes must be split.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "4.2.0",
-  "description": "Continuous architecture enforcement for AI-assisted development. Aspects, review, enforcement.",
+  "version": "5.0.0-alpha.1",
+  "description": "Architecture rules your coding agent can't ignore. Written in Markdown, verified on every change, enforced in the agent's loop — not after on a PR. Works with Claude Code, Cursor, Copilot, Codex, Cline.",
   "type": "module",
   "bin": {
     "yg": "dist/bin.js"
@@ -9,6 +9,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/**/*.wasm",
     "graph-schemas/"
   ],
   "engines": {
@@ -24,17 +25,23 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write \"src/**/*.ts\"",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -p tsconfig.check.json"
   },
   "keywords": [
     "yggdrasil",
-    "ai-agents",
     "architecture-enforcement",
-    "code-review",
-    "ai-governance",
+    "code-guardrails",
+    "agentic-guardrails",
+    "rule-engine",
+    "agents-md",
+    "claude-md",
+    "claude-code",
+    "ai-agents",
+    "coding-agents",
+    "ai-coding",
+    "ai-assisted-development",
     "cli",
-    "developer-tools",
-    "ai-coding"
+    "developer-tools"
   ],
   "author": "Krzysztof Dudek <me@chrisdudek.com>",
   "license": "MIT",
@@ -48,27 +55,56 @@
     "url": "git+https://github.com/krzysztofdudek/Yggdrasil.git",
     "directory": "source/cli"
   },
+  "exports": {
+    "./ast": {
+      "import": "./dist/ast.js",
+      "types": "./dist/ast.d.ts"
+    },
+    "./structure": {
+      "import": "./dist/structure.js",
+      "types": "./dist/structure.d.ts"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "^1.2.0",
+    "@clack/prompts": "^1.5.0",
     "chalk": "^5.6.2",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "ignore": "^7.0.5",
-    "semver": "^7.7.4",
-    "yaml": "^2.8.2"
+    "minimatch": "^10.2.5",
+    "minisearch": "^7.2.0",
+    "semver": "^7.8.1",
+    "smol-toml": "^1.6.1",
+    "web-tree-sitter": "^0.26.9",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.0",
+    "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",
+    "@tree-sitter-grammars/tree-sitter-toml": "^0.7.0",
+    "@tree-sitter-grammars/tree-sitter-yaml": "^0.7.1",
+    "@types/node": "^25.9.1",
     "@types/semver": "^7.7.1",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.1",
-    "prettier": "^3.8.1",
+    "@vitest/coverage-v8": "^4.1.7",
+    "eslint": "^10.4.1",
+    "prettier": "^3.8.3",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-c-sharp": "^0.23.5",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-json": "^0.24.8",
+    "tree-sitter-php": "^0.24.2",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-typescript": "^0.23.2",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.2",
-    "typescript-eslint": "^8.56.0",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^4.1.7"
   }
 }