structured-context 0.11.0 → 0.13.0

package/dist/validate.js

@@ -1,10 +1,12 @@
 import { isAbsolute, relative, resolve } from 'node:path';
-import { readSpace } from './read/read-space';
-import { extractEntityInfo } from './schema/schema';
-import { validateGraph } from './schema/validate-graph';
-import { validateRules } from './schema/validate-rules';
-import { createSpaceContext } from './space-context';
-import { buildSpaceGraph } from './space-graph';
+import { readSpace } from './read/read-space.js';
+import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating.js';
+import { filterRules } from './schema/rule-filter.js';
+import { extractEntityInfo } from './schema/schema.js';
+import { validateGraph } from './schema/validate-graph.js';
+import { validateRules } from './schema/validate-rules.js';
+import { createSpaceContext } from './space-context.js';
+import { buildSpaceGraph } from './space-graph.js';
 /**
  * Format AJV errors for better readability.
  * Groups related errors and extracts helpful context like allowed values.
@@ -92,71 +94,101 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
     }
     return formatted;
 }
+/** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
+export function ruleViolationMessage(v) {
+    const evidence = v.evidence ? ` (Evidence: ${v.evidence})` : '';
+    const guidance = v.guidance ? ` Guidance: ${v.guidance}` : '';
+    return `[${v.ruleId}] ${v.description}${evidence}${guidance}`;
+}
+const summariseTrim = (report) => ({
+    nodeCount: report.nodes.size,
+    ruleIds: [...report.ruleIds].sort(),
+});
 /**
- * Run full validation on a space and return a structured result.
- * Does not output to console or call process.exit.
+ * Evaluate a space's rules. With a main hierarchy, evaluation cascades: schema, hierarchy
+ * and gating-rule failures (the `seeds`) suppress rule evaluation for the failing node's subtree.
+ * Called by `validateNodes`, the core behind `validateSpace` and `validateFile`, so both report identical rule results for a node.
+ * Semantic rules run only when a `judge` is supplied.
  */
-export async function validateSpace(context, options = {}) {
+async function evaluateSpaceRules(nodes, metadata, seeds, options = {}) {
+    const rules = metadata.rules && filterRules(metadata.rules, options.ruleFilter);
+    if (!rules)
+        return { violations: [], gates: [] };
+    const provider = options.judge;
+    if (!metadata.hierarchy) {
+        const result = await validateRules(nodes, rules, {
+            judge: provider,
+            judgeTarget: options.judgeTarget,
+            trimReport: options.trimReport,
+        });
+        return { violations: result, gates: [] };
+    }
+    const graph = buildSpaceGraph(nodes, metadata.hierarchy);
+    return evaluateRulesWithGating(nodes, rules, graph, seeds, {
+        includeGated: options.includeGated,
+        provider,
+        judgeTarget: options.judgeTarget,
+        trimReport: options.trimReport,
+    });
+}
+/**
+ * The one validation pipeline: type and schema checks, duplicate titles, reference and hierarchy
+ * checks, cascade-gated rules, and unresolved content links. Returns every entry; `validateSpace`
+ * and `validateFile` are views over it, so a file's results match its entry in a full run.
+ * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
+ */
+async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
-    const readResult = options.readResult ?? (await readSpace(context));
-    const { nodes, parseIssues } = readResult;
     // Pre-extract valid types for early type validation
     const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
     const result = {
         validCount: 0,
-        nodeErrorCount: 0,
-        nodeErrors: [],
+        nodeFailures: [],
         refErrors: [],
         duplicateErrors: [],
         ruleViolations: [],
         hierarchyViolations: [],
         orphans: [],
-        parseIssues,
         unresolvedContentLinks: [],
+        coverageGates: [],
+        contextTrimmed: { nodeCount: 0, ruleIds: [] },
     };
     for (const node of nodes) {
         // Early type validation - check before full AJV validation to prevent cascading errors
         const nodeType = node.schemaData.type;
         if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
-            result.nodeErrorCount++;
-            result.nodeErrors.push({
-                file: node.label,
+            const sortedTypes = [...validTypes].sort();
+            result.nodeFailures.push({
+                node,
+                invalidType: { validTypes },
                 errors: [
                     {
                         instancePath: '/type',
                         keyword: 'enum',
-                        message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
-                        params: { allowedValues: validTypes },
+                        message: `Invalid type "${nodeType}". Valid types are: ${sortedTypes.join(', ')}`,
+                        params: { allowedValues: sortedTypes },
                         schemaPath: '#/oneOf',
                         data: nodeType,
                     },
                 ],
-                nodeData: node.schemaData,
             });
             continue;
         }
-        const valid = schemaValidator(node.schemaData);
-        if (valid) {
+        if (schemaValidator(node.schemaData)) {
             result.validCount++;
         }
         else {
-            result.nodeErrorCount++;
-            result.nodeErrors.push({
-                file: node.label,
-                errors: schemaValidator.errors || [],
-                nodeData: node.schemaData,
-            });
+            result.nodeFailures.push({ node, errors: schemaValidator.errors || [] });
         }
     }
     // Detect duplicate node keys (titles)
     const titleToFiles = new Map();
     for (const node of nodes) {
-        const title = node.title;
-        if (!titleToFiles.has(title)) {
-            titleToFiles.set(title, []);
+        if (!titleToFiles.has(node.title)) {
+            titleToFiles.set(node.title, []);
         }
-        titleToFiles.get(title).push(node.label);
+        titleToFiles.get(node.title).push(node.label);
     }
     for (const [title, files] of titleToFiles) {
         if (files.length > 1) {
@@ -164,16 +196,27 @@ export async function validateSpace(context, options = {}) {
         }
     }
     // Validate all hierarchy constraints (field references and structure)
-    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
+    const hierarchyValidation = validateGraph(nodes, metadata, unresolvedRefs);
     result.refErrors.push(...hierarchyValidation.refErrors);
     result.hierarchyViolations = [...hierarchyValidation.violations];
-    // Calculate orphan count (informational, not a validation error)
-    if (metadata.hierarchy) {
-        result.orphans = [...buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans];
+    // Calculate orphans across every hierarchy (informational, not a validation error)
+    for (const hierarchy of metadata.hierarchies ?? []) {
+        result.orphans.push(...buildSpaceGraph(nodes, hierarchy).orphans);
     }
-    // Load and execute rules validation if schema defines rules
+    // Load and execute rules validation if schema defines rules (with cascade gating, see docs/rules.md).
     if (metadata.rules) {
-        result.ruleViolations = await validateRules(nodes, metadata.rules);
+        const seeds = [
+            ...result.nodeFailures.map(({ node }) => {
+                const file = node.source?.file ?? node.label;
+                return { file, title: String(node.schemaData.title ?? file), reason: 'schema' };
+            }),
+            ...result.hierarchyViolations.map((v) => ({ file: v.file, title: v.nodeTitle, reason: 'hierarchy' })),
+        ];
+        const trimReport = { nodes: new Set(), ruleIds: new Set() };
+        const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { ...options, trimReport });
+        result.ruleViolations = violations;
+        result.coverageGates = gates;
+        result.contextTrimmed = summariseTrim(trimReport);
     }
     // Collect unresolved content links (warnings — not errors)
     const seen = new Set();
@@ -190,8 +233,61 @@ export async function validateSpace(context, options = {}) {
     }
     return result;
 }
+/**
+ * Run full validation on a space and return a structured result.
+ * Does not output to console or call process.exit.
+ */
+export async function validateSpace(context, options = {}) {
+    const metadata = context.schema.metadata;
+    const readResult = options.readResult ?? (await readSpace(context));
+    let nodes = readResult.nodes;
+    // Depth limiting: evaluate only hierarchy nodes within N breadth-first levels from the
+    // top. Non-hierarchy nodes are unaffected — depth scoping only applies to the hierarchy DAG.
+    const skippedByDepth = [];
+    if (options.depth !== undefined && metadata.hierarchy) {
+        const fullGraph = buildSpaceGraph(nodes, metadata.hierarchy);
+        const depths = computeHierarchyDepths(fullGraph);
+        const included = [];
+        for (const node of nodes) {
+            const nodeDepth = depths.get(node.title);
+            if (nodeDepth !== undefined && nodeDepth > options.depth) {
+                skippedByDepth.push({ file: node.label, title: node.title });
+            }
+            else {
+                included.push(node);
+            }
+        }
+        nodes = included;
+    }
+    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, {
+        includeGated: options.includeGated,
+        ruleFilter: options.ruleFilter,
+        judge: options.judge,
+    });
+    return {
+        validCount: result.validCount,
+        nodeErrorCount: result.nodeFailures.length,
+        nodeErrors: result.nodeFailures.map(({ node, errors }) => ({
+            file: node.source?.file ?? node.label,
+            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+            errors,
+            nodeData: node.schemaData,
+        })),
+        refErrors: result.refErrors,
+        duplicateErrors: result.duplicateErrors,
+        ruleViolations: result.ruleViolations,
+        hierarchyViolations: result.hierarchyViolations,
+        orphans: result.orphans,
+        parseIssues: readResult.parseIssues,
+        unresolvedContentLinks: result.unresolvedContentLinks,
+        coverageGates: result.coverageGates,
+        contextTrimmed: result.contextTrimmed,
+        skippedByDepth,
+        depthLimit: options.depth,
+    };
+}
 /** Find which space a file belongs to by checking directory containment. */
-function resolveFileSpace(filePath, config) {
+export function resolveFileSpace(filePath, config) {
     const absFile = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
     for (const space of config.spaces) {
         const absSpace = isAbsolute(space.path) ? space.path : resolve(process.cwd(), space.path);
@@ -204,109 +300,112 @@ function resolveFileSpace(filePath, config) {
     return null;
 }
 /**
- * Validate a single file within its space.
- *
- * Reads the full space (required for graph correctness) but filters all reported
- * errors to only those attributable to the target file.
- *
- * Returns a result object — does not output to console or call process.exit.
- * If the file is not in any configured space, returns a result with `inSpace: false`.
+ * Select one file's entries from a space's validation result: issues keyed and formatted, errors split from warnings.
+ * Pure — a file's entries are exactly its slice of the result.
  */
-export async function validateFile(filePath, config, options = {}) {
-    const resolved = resolveFileSpace(filePath, config);
-    if (!resolved) {
-        return {
-            file: filePath,
-            inSpace: false,
-            message: 'File does not belong to any configured space.',
-        };
-    }
-    const { space, label } = resolved;
-    const context = createSpaceContext(space.name, config, { configDir: options.configDir });
-    const { schema, schemaRefRegistry, schemaValidator } = context;
-    const metadata = schema.metadata;
-    const readResult = await readSpace(context);
-    const { nodes } = readResult;
-    // Pre-extract valid types for early type validation
-    const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
+function issuesForFile(result, label, context, includeGated) {
+    const { schema, schemaRefRegistry } = context;
     const errors = {};
-    // Schema validation errors for this node
-    for (const node of nodes) {
+    const warnings = {};
+    for (const { node, errors: ajvErrors, invalidType } of result.nodeFailures) {
         if (node.label !== label)
             continue;
-        // Early type validation - check before full AJV validation to prevent cascading errors
-        const nodeType = node.schemaData.type;
-        if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
-            errors[`schema:type:${validTypes.join(',')}`] = {
+        const position = {
+            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+            ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
+        };
+        if (invalidType) {
+            errors[`schema:type:${invalidType.validTypes.join(',')}`] = {
                 kind: 'schema',
-                message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
+                message: ajvErrors[0].message,
+                ...position,
             };
             continue;
         }
-        const valid = schemaValidator(node.schemaData);
-        if (!valid) {
-            const formatted = formatErrors(schemaValidator.errors ?? [], schema, schemaRefRegistry, node.schemaData);
-            for (const { message, dedupeKey } of formatted) {
-                errors[`schema:${dedupeKey}`] = { kind: 'schema', message };
-            }
+        const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, node.schemaData);
+        for (const { message, dedupeKey } of formatted) {
+            errors[`schema:${dedupeKey}`] = { kind: 'schema', message, ...position };
         }
     }
     // Duplicate key errors — include if this file is one of the duplicates
-    const titleToFiles = new Map();
-    for (const node of nodes) {
-        if (!titleToFiles.has(node.title))
-            titleToFiles.set(node.title, []);
-        titleToFiles.get(node.title).push(node.label);
-    }
-    for (const [title, files] of titleToFiles) {
-        if (files.length > 1 && files.includes(label)) {
-            const others = files.filter((f) => f !== label);
-            errors[`duplicate:${title}`] = {
-                kind: 'duplicate',
-                message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
-            };
-        }
+    for (const { title, files } of result.duplicateErrors) {
+        if (!files.includes(label))
+            continue;
+        const others = files.filter((f) => f !== label);
+        errors[`duplicate:${title}`] = {
+            kind: 'duplicate',
+            message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
+        };
     }
     // Broken links and hierarchy violations from this file
-    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
-    for (const { file, parent, error } of hierarchyValidation.refErrors) {
+    for (const { file, parent, error } of result.refErrors) {
         if (file === label) {
             errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
         }
     }
-    for (const v of hierarchyValidation.violations) {
+    for (const v of result.hierarchyViolations) {
         if (v.file === label) {
             errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
         }
     }
-    // Rule violations for this node
-    if (metadata.rules) {
-        const ruleViolations = await validateRules(nodes, metadata.rules);
-        for (const v of ruleViolations) {
-            if (v.file === label) {
-                errors[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}` };
-            }
+    // Rule violations — only error severity counts as an error.
+    for (const v of result.ruleViolations) {
+        if (v.file === label) {
+            const target = v.severity === 'error' ? errors : warnings;
+            target[`rule:${v.ruleId}`] = {
+                kind: 'rule',
+                message: ruleViolationMessage(v),
+                severity: v.severity,
+            };
         }
     }
-    // Unresolved content links for this node (warnings — do not affect errorCount)
-    const warnings = {};
-    const targetNode = nodes.find((n) => n.label === label);
-    if (targetNode) {
-        const seen = new Set();
-        for (const link of targetNode.resolvedLinks) {
-            if (link.location === 'internal' && !seen.has(link.target)) {
-                seen.add(link.target);
-                warnings[`content-link:${link.target}`] = {
-                    kind: 'content-link',
-                    message: `Unresolved content link: ${link.target}`,
-                };
-            }
+    // A gated file with no violations would otherwise look clean — say that its rules were not checked.
+    for (const gate of result.coverageGates) {
+        if (!gate.gatedFiles.includes(label))
+            continue;
+        const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
+        warnings[`gated:${gate.file}`] = {
+            kind: 'gated',
+            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.file}`,
+            severity: 'info',
+        };
+    }
+    // Unresolved content links (warnings — do not affect errorCount)
+    for (const link of result.unresolvedContentLinks) {
+        if (link.file === label) {
+            warnings[`content-link:${link.target}`] = {
+                kind: 'content-link',
+                message: `Unresolved content link: ${link.target}`,
+            };
         }
     }
+    return { errors, warnings };
+}
+/** The result for a file that belongs to no configured space. */
+export function fileNotInSpace(filePath) {
+    return {
+        file: filePath,
+        inSpace: false,
+        message: 'File does not belong to any configured space.',
+    };
+}
+/**
+ * Validate a file in an already-resolved space. Checks the whole space (required for graph
+ * correctness), judging only the file, then selects the file's issues from the result.
+ */
+export async function validateResolvedFile(filePath, label, context, options = {}) {
+    const readResult = await readSpace(context);
+    const result = await validateNodes(context, readResult.nodes, readResult.unresolvedRefs, {
+        includeGated: options.includeGated,
+        ruleFilter: options.ruleFilter,
+        judge: options.judge,
+        judgeTarget: label,
+    });
+    const { errors, warnings } = issuesForFile(result, label, context, options.includeGated);
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,
-        space: space.name,
+        space: context.space.name,
         errors,
         errorCount: Object.keys(errors).length,
         warnings,
@@ -314,3 +413,19 @@ export async function validateFile(filePath, config, options = {}) {
         inSpace: true,
     };
 }
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file.
+ *
+ * Returns a result object — does not output to console or call process.exit.
+ * If the file is not in any configured space, returns a result with `inSpace: false`.
+ */
+export async function validateFile(filePath, config, options = {}) {
+    const resolved = resolveFileSpace(filePath, config);
+    if (!resolved)
+        return fileNotInSpace(filePath);
+    const context = createSpaceContext(resolved.space.name, config, { configDir: options.configDir });
+    return validateResolvedFile(filePath, resolved.label, context, options);
+}

package/docs/concepts.md

@@ -1,4 +1,8 @@
-# Structured Context: Concepts and Terminology
+---
+title: "Concepts and Terminology"
+---
+
+# Concepts and Terminology
 
 This document is the canonical reference for concepts and terminology used in this project. It focuses on the meta-concepts the project supports, not the content of specific frameworks modelled in schemas. Before naming things in code, tests, comments, or documentation, check definitions here for consistency, and update them here when the project's "world view" changes, avoiding blurry terms as much as possible.
 
@@ -47,7 +51,7 @@ Each `.md` file with a `type` frontmatter field is a **typed page** — it repre
 
 - **Heading with `[type:: x]`** or **anchor-implied type** (e.g. `## My Goal ^goal1`) → becomes a child node.
 - **Relationship headings** (e.g. `### Assumptions`) → when matched to a relationship definition in the schema, signals that following content (list items or table rows) should be typed as that relationship's child type, without requiring explicit inline annotations.
-- **Untyped headings** → update the depth stack for parent resolution but do not become nodes.
+- **Untyped headings** → update the depth stack for parent resolution but do not become nodes. They stay in the content of the node whose section contains them; see [Node content](#node-content).
 - **Typed bullet items** (`- [type:: solution] Title`) → become child nodes at any nesting depth.
 - **Table rows** under a relationship heading → become child nodes of the relationship type.
 - **YAML blocks** and **unbracketed `key:: value` paragraph fields** → merged into the current node's `schemaData`.
@@ -83,7 +87,7 @@ Key properties:
 
 #### Preamble
 
-**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node.
+**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node, and not part of any node's `content`.
 
 ---
 
@@ -93,6 +97,10 @@ A **space node** (or **node** for short) is a single entity in a `space` — a n
 
 Node types are defined by the schema in use and may vary across schemas. Examples from the default schema: `vision`, `mission`, `goal`, `opportunity`, `solution`. The tooling is not prescriptive about which types exist — schemas are designed to be extended and replaced.
 
+Each node retains its physical `source` location (`file`, and `line` / `column` where available) so that validation diagnostics, edge errors, and downstream tooling pinpoint the exact location in the vault.
+
+A node's `content` is the markdown source of its body; see [Node content](#node-content).
+
 > `space_on_a_page` and `dashboard` are not `space node` types — they are `tooling types`.
 
 ### Embedded node
@@ -101,6 +109,20 @@ An **embedded node** is a `space node` defined *within* a containing document ra
 
 A `typed page` may contain embedded nodes in its body. Those nodes become full members of the parsed node set, with `parent references` wired to their containing page or enclosing heading.
 
+### Node content
+
+A node's `content` is the markdown of its body, copied unchanged from the file: blank lines, list looseness, line endings and code fences all stay as written. The content of a list item node is dedented by the item's content indent, so it reads as markdown on its own. Leading blank lines and trailing whitespace are trimmed.
+
+A node owns the source from its heading or list item up to the next heading that ends its section, with these parts removed:
+
+- Its own heading line or list marker text.
+- The sections of nested embedded nodes.
+- Field syntax that supplies data: frontmatter and other YAML blocks, and lines that hold only `key:: value` or `[key:: value]` fields. A field written inside a sentence stays in the prose, and its value is still read as a field.
+
+An untyped heading belongs to the content of the node whose section contains it. An untyped heading at the same level as an embedded node's heading, or at a higher level (fewer `#`), ends that node's section, so the heading and what follows it go to the enclosing node, or to the page. An untyped heading at a deeper level stays inside the section. Inline fields below an untyped heading are assigned the same way.
+
+In a `space_on_a_page` file, content before the first heading (the preamble) is not assigned to any node.
+
 ### Type alias
 
 A **type alias** is an alternative name accepted in the `type` field for a given `space node` type. Aliases allow teams to use their own vocabulary while still receiving schema validation. For example, a schema might accept `outcome` as an alias for `goal`.
@@ -111,7 +133,7 @@ A `space node`'s resolved type (`resolvedType`) is its canonical type after alia
 
 ## Typed page
 
-A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`.
+A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`. The page node's `content` is the body markdown outside any embedded node (the entire body when there are none).
 
 Typed pages are distinct from `space on a page` files: a typed page *is* a `space node`; a `space_on_a_page` file is merely a container.
 
@@ -123,7 +145,7 @@ A **schema** defines the valid structure for nodes in a `space`: the fields, typ
 
 The schema handles structural validation. Cross-node and workflow checks are handled by executable `rules` defined in `$metadata.rules`.
 
-Schemas are composable: structural definitions and metadata can be sourced across `$ref` graphs, then merged deterministically (root metadata applied last, single hierarchy provider, aliases merged, rules merged by `id` with explicit override semantics).
+Schemas are composable. Structural definitions are reused with `$ref` (validation only). Metadata is reused only by listing schema `$id`s in `$metadata.imports`: imports merge transitively, in order, with the schema's own metadata last. Hierarchies, relationships, aliases and rules all follow one rule — a duplicate is an error unless the later entry sets `override: true` — and each declared hierarchy is kept as a separate named hierarchy.
 
 ### Rules
 
@@ -141,8 +163,34 @@ Rules may be:
 
 Rules are distinct from schema validation: the schema checks structure; rules check meaning and quality.
 
+A rule's `when` is its **applicability condition**: a test that decides whether the rule applies to a node. Its `expression` is the test the node must pass.
+
+Each executable rule has a **category** (`validation`, `coherence`, `workflow`, `best-practice`) that supplies its default **severity** (`error`, `warning`, `info`). A rule may override its category's severity, but categories are the preferred grouping. Only `error` severity violations fail validation.
+
 See [docs/rules.md](rules.md) for the rules reference, including JSONata expression syntax and the full `$metadata` field reference.
 
+### Semantic rules
+
+A **semantic rule** is a rule with a `semantic` part. It asks a model to evaluate a node, for example whether an opportunity is a customer need. The `semantic` object can carry a `rubric`, `verdicts`, a verdict `severity` map, a `scope` and `includeContent`. A rule can also have an `expression`, a JSONata test that runs before the model.
+
+A **model provider** evaluates semantic rules: a decision model (Jev) or a chat model (Claude, OpenAI-compatible). It is a bundled provider or an entry in `modelProviders`. For each rule, the model gives one **verdict** from the rule's `semantic.verdicts`, for example `customer-need`, `vague` or `solution`. The rule's `semantic.severity` says which verdicts report a violation. Semantic rules cost money, so they are evaluated only when a run asks for it (`--semantic`); a rule's `expression` always runs. See [docs/semantic-rules.md](semantic-rules.md).
+
+The **evaluated node** is the node a semantic rule is judged on. A rule's `semantic.scope` adds **related nodes** (parent, siblings, children, ancestors, descendants, or the whole branch) along the main hierarchy's edges, and `semantic.includeContent` chooses whose body is sent. See [Related nodes and content](semantic-rules.md#related-nodes-and-content).
+
+A **node ruleset group** is the set of nodes that share the same semantic rules. It forms within one evaluation step of [cascade gating](#cascade-gating): one hierarchy depth, or the set of non-hierarchy nodes. Nodes are keyed on the rules left after `when` and `expression` filtering. A model provider on the `openrouter-decisions` or `typesafe-systemone` API evaluates one group in as few decision requests as it can.
+
+A **decision request** is one call to a decisions API. It carries the state of one or more nodes and a list of decision questions.
+
+A **decision question** is one choice question about one node under one semantic rule, inside a decision request.
+
+The **per-node input cap** limits the input for one evaluated node and its related nodes. See [Input size and trimming](semantic-rules.md#input-size-and-trimming).
+
+### Cascade gating
+
+**Cascade gating** is the mechanism by which a schema failure, hierarchy structure violation, or blocking rule violation on a node suppresses rule evaluation for that node's `hierarchy` subtree. It exists so downstream checks — especially costly semantic (model-judged) rules — aren't run against inputs already known to be invalid.
+
+A **coverage gate** records one instance of this: the gating node, what kind of failure triggered it (`schema`, `hierarchy`, or a specific rule `id`), and the set of nodes whose rules were suppressed as a result. `sctx validate` reports coverage gates so both humans and agents can see the validation "edge" — where evaluation stopped and why. See [docs/rules.md](rules.md#cascade-gating) for the full model, including the per-rule `gatesDescendants` field and the `--include-gated` / `--depth` CLI options.
+
 ---
 
 ## Tooling types
@@ -160,6 +208,10 @@ The **hierarchy** is the ordered list of node types in a space, from root to lea
 
 The hierarchy is modelled as a layered DAG: a non-root node may have zero parents (orphaned), one parent, or multiple parents. The `show` command renders this as an indented tree, marking repeated nodes with `(*)` where the subtree is already shown elsewhere.
 
+A space may have **several hierarchies**, one for each imported schema that declares one. Each hierarchy has a **name** (defaulting to the declaring schema's file stem), and each type belongs to at most one hierarchy. Structural validation runs per hierarchy; relationships may connect types across hierarchies.
+
+The **main hierarchy** is the one declared by the root schema; failing that, the only imported hierarchy; failing that, the one the root selects with `"hierarchy": { "$ref": ... }`. The main hierarchy drives `space on a page` parsing, hierarchy embedding, template sync, and default rendering. `show`, `diagram` and `render` take `--hierarchy <name>` to render another. See [docs/schemas.md](schemas.md#multiple-hierarchies).
+
 Each non-root level uses the shared `field`, `fieldOn`, and `multiple` edge options (see [Graph edges](#graph-edges)). Hierarchy-specific options:
 
 | Option | Default | Meaning |
@@ -250,9 +302,10 @@ Each entry is a `ResolvedParentRef` object:
 | `title` | `string` | The parent node's title |
 | `field` | `string` | The frontmatter field that held the wikilink |
 | `source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy level or a relationship |
+| `hierarchy` | `string` | Name of the hierarchy the edge belongs to; present only when `source` is `'hierarchy'` |
 | `selfRef` | `boolean` | Whether the edge is a same-type (self-referential) parent link |
 
-The `source` label lets downstream consumers distinguish edge types without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
+The `source` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
 
 ### Content links
 
@@ -288,7 +341,7 @@ An **anchor** is a block anchor (e.g. `^goal1`) appended to a heading in a `type
 
 ## Filter expressions
 
-A **filter expression** is a string that selects a subset of nodes from a space. Filter expressions are used with the `--filter` flag on the `show` command and in named filter views in config.
+A **filter expression** is a string that selects a subset of nodes from a space. Filter expressions are used with the `--filter` flag on the `show` and `render` commands and in named filter views in config.
 
 ### Syntax
 
@@ -303,7 +356,7 @@ Keywords (`WHERE`, `SELECT`) are case-insensitive.
 
 ### Predicate context
 
-The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Node fields (from `schemaData`) are accessible directly — e.g. `resolvedType`, `status`, `title`. Additionally, two pre-computed traversal arrays are available:
+The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Node fields (from `schemaData`) are accessible directly — e.g. `resolvedType`, `status`. `label` (relative file path, e.g. `"solutions/My Solution.md"`) and `title` are always available regardless of schema. Additionally, two pre-computed traversal arrays are available:
 
 | Field | Description |
 |-------|-------------|
@@ -315,9 +368,12 @@ Each entry in `ancestors[]` or `descendants[]` includes all schema fields of the
 | Metadata field | Type | Description |
 |----------------|------|-------------|
 | `_field` | `string` | The edge field name that connects to this ancestor/descendant |
-| `_source` | `'hierarchy' \| 'relationship'` | Whether the edge came from the hierarchy or a relationship |
+| `_source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy or a relationship |
+| `_hierarchy` | `string` | Hierarchy name; present only for hierarchy edges |
 | `_selfRef` | `boolean` | Whether the edge is a same-type (self-referential) link |
 
+Dates and datetimes are the strings written in frontmatter, so compare them with `$toMillis()` rather than as strings (offsets and precision vary), e.g. `WHERE $toMillis(updated) > $toMillis('2026-03-31T00:00:00Z')`. See [Rules: dates and times](rules.md#dates-and-times).
+
 ### SELECT spec
 
 The SELECT clause expands the result set by walking the graph from matched nodes. The spec is a comma-separated list of directives: