## [2026-05-15T10:45:56.847Z]
Redesign rules.ts and knowledge: extract log-management, ports-and-relations, flows as new knowledge topics; trim rules.ts CLI table to essentials with route to cli-reference; remove duplicate authz rule from suppress-syntax (kept in rules.ts as behavioral rule); remove duplicate cross-file-evasion section from working-with-architecture (moved to ports-and-relations); remove 7-channels table + brownfield signs from aspects-overview (kept in rules.ts as mental model and Aspect Discovery heuristic); add per-node-independent-execution detail to drift-and-cascade; expand 'Where to find more' routing table to all 12 topics. Goal: rules.ts stays a lean primer + router (always loaded); knowledge holds deep reference (on-demand). Nothing lost — every fact preserved in either rules.ts or some knowledge file.
## [2026-05-15T10:47:19.010Z]
Lint fix: escape pipe inside CLI essentials table row at TypeScript level (\\| → renders as \| in markdown so the | between flags is literal text, not column separator). Output-equivalent semantic, ESLint no-useless-escape compliant.
## [2026-05-15T11:03:40.337Z]
Restore three items I had over-trimmed during the redesign — user feedback that nothing should be lost from rules.ts: (1) re-add yg-suppress proposal procedure step 1 ('Show the user the violation and explain why the code cannot comply now') as an explicit numbered step in the rules.ts Authorization section — previously only implicit in 'PROPOSE'. (2) re-add the yg log merge-resolve narrative paragraph (what the tool validates, why not to concatenate manually) to the rules.ts 'Log management — workflow' section — previously only in log-management knowledge. (3) re-add yg log merge-resolve to the rules.ts CLI essentials table. Knowledge files keep their full coverage too.
## [2026-05-15T17:44:40.170Z]
Phase 2: reclassified from adapter to template. Mapping narrowed to {default-config,platform,rules}.ts. Knowledge docs moved to cli/knowledge.
## [2026-05-16T08:39:07.651Z]
installRulesForPlatform: normalize returned path with POSIX replace before returning — satisfies posix-paths-output aspect added via init flow
## [2026-05-16T13:46:18.742Z]
Update default-config.ts and knowledge/configuration.ts: version 4.4.0 → 4.3.0 as part of flattening 4.3.0+4.4.0 into single 4.3.0 release.
## [2026-05-16T14:15:27.164Z]
Added self-containment rules for log entries to agent-rules.md Log management section, and trimmed the duplicated rules block out of the log-management knowledge topic so only an illustrative worked example remains there. Rationale: log.md is consumed by future agents who do not have the surrounding conversation, the plan being executed, or the code state at the time the entry was written; entries that point at any of those become unreadable as soon as those artifacts change or disappear. Rules now require each entry to be self-contained — no references to external artifacts, file paths, identifiers outside the entry text, plan or task numbers, or pointers to current code state; rationale must be embedded as prose; stable external standards may be cited only by canonical identifier plus an inline summary. Pattern follows the existing 'lean rules + deep knowledge topic' split — primer holds the always-loaded rule set, knowledge topic adds an example on demand, no duplication across the two surfaces. Forward-only — existing log entries are not rewritten.
## [2026-05-26T10:57:50.412Z]
Add SYSTEM-section paragraph describing language: field requirement on AST aspects. Required before regenerating .yggdrasil/agent-rules.md (per AGENTS.md, never hand-edit generated file).
## [2026-05-27T12:26:25.571Z]
Updated DEFAULT_CONFIG version from 4.3.0 to 5.0.0 — new projects initialized with yg init will receive v5 config schema by default, compatible with the v5 reviewer tiers format.
## [2026-05-27T13:54:52.349Z]
Rules content now teaches the current reviewer shape (mapping with type and optional tier) instead of the legacy scalar; AST aspects are described as reviewer.type ast and explicitly may not declare a tier. Adopters running init upgrade now receive guidance that matches the validator they are upgrading into.
## [2026-05-28T09:17:21.417Z]
Added references field to LLM aspects in rules.ts: updated Aspects definition and Reviewer description to mention declared reference files (lookup tables, catalogues) that are included in the reviewer prompt and exposed to the agent under read:. This documents the new references feature for agents working in any repository that adopts Yggdrasil.
## [2026-05-28T15:38:22.781Z]
Added aspect-status content to agent rules: nine targeted insertions across SYSTEM (graph elements, channel cascade, reviewer behavior, drift) and DECISIONS (impact-and-cost options table, aspect creation guidance, suppress vs draft distinction, business-language translation, where-to-find-more table). The rules content is the agent system prompt; agents in any repository adopting Yggdrasil rely on this for correct workflow. The new three-level status model (draft/advisory/enforced) needed surfacing here so agents know to set status on aspect creation, understand cascade semantics, distinguish status drift, and translate user phrases. Regenerated agent-rules.md (consumed by claude-code) reflects these edits verbatim.
## [2026-05-28T19:04:03.881Z]
Aspect-status final review polish: added explicit sentence to Drift and Cascade section of rules.ts surfacing the suggestedNext priority rule (errors before warnings). The check command emits both errors and warnings when status flips surface refused baselines; agents need to know to fix the error path first because warnings never block CI.
## [2026-05-28T20:25:12.328Z]
Added a paragraph to the canonical agent rules content addressing log-entry mimicry. The self-contained content rule was already present and already clear, but real entries across the repository routinely contained ephemeral references — plan-step numbers, design-section markers, file paths in prose — that the rule forbids.

The path through which the rule was violated turned out to be the recommended workflow itself: the rules instruct an agent to read recent entries before editing a node, which exposes the agent to whatever style the node's prior entries used, and in-context mimicry then propagates that style into the new entry even when the rules text contradicts it. The new paragraph names this mimicry vector explicitly, gives concrete examples of patterns to treat as anti-templates, and grants permission to deviate from prior surface style when those entries pre-date or contradict the current rule.

The intent is a small behavioral override at the exact decision point where agents previously inherited the contamination — not a restatement of the underlying self-containment rule, which the agent already saw. Without this addition, every newly-onboarded agent that follows the recommended pre-edit reading workflow inherits the same failure mode the rule was meant to prevent, and the contaminated style perpetuates itself one node-edit at a time.
## [2026-05-29T08:33:49.605Z]
Added 'Write a structure aspect' row to the Where-to-find-more table in rules.ts, pointing to the new writing-structure-aspects knowledge topic. This keeps the table consistent with all three reviewer types (LLM, AST, structure).
## [2026-05-29T15:03:36.189Z]
Corrected the agent-facing rules guidance that lists the choices available when source code does not satisfy an aspect: the prose said 'three options' while the accompanying decision table enumerates five (change code, change aspect, demote to advisory, mark draft, suppress). The count was updated to five so the narrative matches the table the agent actually reads when weighing a cost/impact trade-off. Wording-only change in the generated rules content; no diagnostic-message structure or path-handling behavior was touched.
## [2026-05-29T15:36:21.985Z]
The agent-facing rules and the drift-and-cascade and log-management knowledge documents were aligned to a single statement of when a log entry is mandatory at approve time: only when the node type has log-required true (the default) and the node's source files changed since the last approve, with the entry newer than the one captured at that approve. The wording now states explicitly that this requirement is independent of aspect status — it never depends on whether a node's aspects are draft, advisory, or enforced — and that a cascade-only re-approve with no source change needs no new entry. The previously documented exemption that said a node whose every effective aspect is draft does not require a log entry was removed, because it described behavior that has been corrected: the all-draft path skips the reviewer but not the log gate.
## [2026-05-29T16:20:43.331Z]
Documented that an advisory-status aspect violation does not fail approval. The reviewer guidance now states that only an enforced code violation refuses with a non-zero exit; an advisory code violation exits zero with an informational line while still recording the baseline and per-aspect verdict, after which the verdict surfaces as a non-blocking warning during the unified check. This keeps the agent-facing rules and the aspect-status reference consistent with advisory's warns-but-does-not-block semantics.
## [2026-05-29T22:37:52.287Z]
The init-time templates were separated so the agent-rules content stands alone from the configuration and platform-installer templates, keeping each unit small enough that a reviewer can inspect it in full without context-window truncation. No template content changed; only which node owns which file.
## [2026-05-30T02:29:44.841Z]
The per-node size guard changed from limiting the raw count of mapped source files to limiting the total number of characters in a node's reviewer context — its mapped source files plus the reference files of its effective aspects — and from a non-blocking warning to a blocking error. The motivation is that the reviewer concatenates all of a node's files into each aspect prompt, so an oversized node risks exceeding the model's context window, which deterministically rejects unchanged code near the truncation point; a file-count limit missed this because one very large file could stay under the count while still blowing the prompt. Binary files do not count toward the budget, and a node mapping a single unsplittable generated or binary artifact (a lockfile, an append-only changelog, an image) may carry a documented per-node exemption with a required justification.
## [2026-05-30T04:33:16.741Z]
Corrected the impact-and-cost guidance so it states that model-review calls are incurred only by LLM aspects (multiplied by the tier's consensus count and the number of prompt chunks), while AST and structure aspects run locally at zero model cost. The previous wording implied every aspect on every affected node costs a model call, which overstated the cost of the deterministic reviewer types and could push an agent toward avoiding aspects that are actually free to enforce.
## [2026-05-30T06:03:05.875Z]
Completed the documentation alignment for the three reviewer types and the model-cost model in the agent-facing rules: the reviewer-choice pointer now names the structure reviewer alongside LLM and AST and points at its authoring guide, matching the rest of the knowledge corpus. This finishes a correction that had been applied to some documents but not the rules pointer, where the choice was still framed as only LLM-versus-AST.
## [2026-05-30T08:49:28.256Z]
The always-on agent rules had drifted from the authoritative schemas and from the deep-reference and human-facing documentation on several enforceable facts: the rules enumerated only two reviewer types when three exist, stated the per-aspect review cost as a flat single call while it scales with consensus and prompt chunks, called a missing port contract a non-blocking warning when it actually blocks, and described aspect-batch and flow-batch approval as covering every node carrying the aspect rather than only the nodes that need re-review. A consistency audit reconciled the rules to the formal contracts and the rest of the documentation so an agent reading the always-on rules is never misled into wrong assumptions about how enforcement works. This is a content-only reconciliation — no behavior, diagnostic-message, or path changes.
## [2026-05-30T14:09:02.058Z]
The per-aspect language declaration was removed from the system. An aspect that ships a parsed-tree check used to carry a `language:` list naming the languages it targeted, and the system validated that list with four dedicated checks. Nothing in the runtime ever read it: the engine already determines each source file's language from its file extension through one shared registry, then loads the matching grammar. The declaration was therefore inert metadata that could silently disagree with what the engine actually parsed — an authoritative-looking field that governed nothing.

This change deletes the field, the validators that policed its shape, and the documentation and tests that described it, and promotes the extension-to-grammar registry to the single authority for matching a file to its parser. The motivation is to remove a confusing mismatch between what an aspect claimed about languages and what the engine did, and to collapse the duplicated extension-knowledge that had drifted into more than one place.

The language a parsed-tree check sees for a given file is now derived solely from that file's extension; an unrecognized extension yields no parsed tree rather than a per-aspect error. The drift identity of a graph-aware structural check is deliberately held stable across this change so existing approvals are not invalidated by metadata that never affected behavior.
## [2026-05-30T15:43:16.672Z]
Re-verification was made selective. When a component needs re-approval because one of its rules changed, only that rule is re-checked and the component's other rules keep their prior verdict — instead of re-checking every rule on the component on every re-approval. The motivation is cost: re-checking a rule against a non-deterministic reviewer is the expensive operation, and a change to one rule's definition (or a cheap deterministic identity shift) previously forced a full, repeated re-review of every rule on every affected component, including expensive rules that could not possibly have been affected by that change.

A source-code edit still re-checks every rule on that component, because every rule reads all of the component's source — that case is component-global by nature. The optimization applies only to changes cleanly attributable to a specific rule (a change to that rule's own definition, content, reference material, or identity). Any change that cannot be attributed to a single rule conservatively re-checks everything, so a documented verdict is never silently preserved when the thing it judged has actually moved. A re-approval where nothing attributable changed performs no reviewer work at all and leaves every prior verdict intact.

This is the enabler for an upcoming change that re-stamps the identity of a large set of rules at once: without selective re-verification that re-stamp would have forced a full, expensive re-review across nearly the whole graph; with it, each re-stamped rule re-checks for free and the components' unrelated expensive verdicts carry forward.
## [2026-05-30T20:06:21.739Z]
The way a rule's verification is declared collapsed from three kinds — a human-language reviewer, a single-file programmable check, and a graph-aware programmable check — down to two: the human-language reviewer and one unified deterministic programmable check. The two programmable kinds were never a real choice, since the graph-aware kind is a superset of the single-file one; keeping both forced authors into a false up-front decision and made the tooling carry two parallel surfaces for one concept. Collapsing them removes that false choice. This change consolidates the remaining user-facing surface that still exposed the old split.

Specific to this node: the agent system-prompt guidance and the two separate aspect-authoring knowledge topics are consolidated — the prompt now describes one deterministic reviewer with two usage styles instead of three reviewer types, and the two authoring topics are merged into one deterministic-authoring topic. The generated agent rules file is regenerated from the template so the dogfood agent reads the unified guidance.
## [2026-05-31T06:24:51.159Z]
The drift documentation overclaimed that any edit to a flow file cascades drift to participants. In reality a flow influences a participant's drift only by changing the participant's effective aspects — adding or removing a flow aspect, or adding or removing a participant — not by a cosmetic edit to the flow file such as its description. The agent-facing rules and the drift-and-cascade knowledge were corrected to describe this accurately. Documentation-only; no behaviour changed.
## [2026-05-31T11:21:39.720Z]
The guidance shipped to agents described reviewer outcomes as only approve-or-reject and, in the drift guidance, implied that an unreachable reviewer still advanced the baseline with deterministic-only results. That wording would lead an agent to believe a node had gone green when in fact no LLM aspect was verified. The content now documents a third outcome — an infrastructure failure that fails closed, exits non-zero, and writes nothing — and the rule that an effective non-draft LLM aspect with no configured reviewer is itself a red, fix-the-configuration condition rather than a silent pass.
## [2026-05-31T14:10:03.174Z]
The agent guidance for locating an entry point told the agent to read the search score against absolute confidence thresholds, but the search scores are relative relevance values that cannot support absolute thresholds. The guidance now explains that the scores are normalized relative to the best match in a single query — the top result is always one and the rest are its fraction — and tells the agent to read the GAP between results rather than an absolute number: a large gap to the runner-up means a confident winner, a tight cluster means an ambiguous query to verify, and the top candidate should always be confirmed with the context command rather than trusted on score alone.
## [2026-05-31T15:19:19.833Z]
Two honesty corrections to the shipped agent rules and knowledge so the guidance matches actual behavior. First, the log-freshness requirement was ambiguous: it said a fresh entry must be "newer than the one captured at the last approve", which read as a contradiction with the rule that a single entry covers all retries including failed approves. The freshness baseline is in fact recorded only when an approve SUCCEEDS — a failed approve (reviewer rejection or infrastructure failure) advances nothing — so the same entry keeps satisfying the gate across every retry until success. The wording now says "last successful approve" and states this explicitly. Second, the deterministic check runner was described in places as a "sandbox"; that overstates the guarantee. The allow-listed read set only scopes which files count as tracked dependencies for drift detection — check.mjs runs in the main Node process with full privileges and could write files or open sockets. Reframed everywhere as a read-tracking discipline, not a security boundary, so adopters do not run untrusted aspects believing they are contained.
## [2026-06-03T07:22:56.675Z]
Updated the generated agent rules to describe the aggregating-aspect kind (a named bundle of implied child aspects with no own reviewer or verdict), the new read-only suppression-inventory command, and the removal of reviewer prompt chunking and the max-tokens cap in favour of reviewing each node whole. The rules ship to every adopting repository, so they must stay in lockstep with the reviewer and aspect-kind behaviour the CLI now enforces.
## [2026-06-08T14:21:59.772Z]
Updated the agent rules and knowledge topics for two coverage and enforcement scoping changes: an explicit empty coverage.required means require nothing (pure-advisory), and the per-node character budget applies only to nodes with a non-draft LLM aspect while deterministic-only and aspect-less nodes are unbounded. Both bring the documented behavior in line with the enforcement that actually runs.
## [2026-06-08T15:11:10.245Z]
Agent-facing rules and knowledge state that node mapping entries and architecture file-classification predicates accept glob patterns (single "*" within a path segment, "**" across segments), with examples, so an agent knows it can scope a node to a subset of a directory by naming pattern. The guidance is written declaratively as a capability — what is possible — not as a changelog of what differs from before.
## [2026-06-13T11:30:25.618Z]
Three accuracy corrections to the agent rules content. The search command's relevance scores are relative (the best match is always the top of the scale and the rest are fractions of it), not absolute thresholds, so the guidance was reworded to judge by the gap between results. The mandatory-log-entry condition now also names the first-verification case for a component that owns source, which the previous wording omitted. The single-next-step hint is selected by a fixed priority order, not output order, so 'first error' was corrected to 'highest-priority error', and the ad-hoc file-check flags were annotated as applying to mechanical checks only. The generated rules file was regenerated to match.
