Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ There are several places that need reviewing and updating with any new feature o
- `schemas/` — Bundled default schema files (JSON5) using the structured-context schema dialect and top-level `$metadata`. Files starting with `_` are "partials" (fragments for `$ref`).
- `src/schema/metadata-contract.ts` — Single source of truth for the `$metadata` contract
- `schemas/generated/latest/_structured_context_schema_meta.json` — Generated metaschema for the newest dialect (generated on build or with `bun run generate:schema-meta`). `schemas/generated/<version>/` folders are frozen copies, created by the `version` script (`generate:schema-meta --release`) only when a release changes the dialect; never edit them. `src/schema/meta-schemas.ts` loads them at runtime.
- `src/schema/gating.ts` — Cascade gating: computes hierarchy depth and evaluates rules with subtree gating (schema/hierarchy/blocking-rule failures suppress downstream rule checks). See [docs/rules.md](docs/rules.md#cascade-gating).

## Testing
For most development only the main unit tests need re-running regularly.
Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,13 +131,16 @@ See [docs/schemas.md](docs/schemas.md) (`sctx docs schema`) for the dialect, com
### Validate nodes

```bash
sctx validate <space> [--watch]
sctx validate <space> [--watch] [--depth <n>] [--include-gated]
```

Validates markdown files against the JSON schema:
- Extracts YAML frontmatter from each `.md` file
- Skips files without frontmatter or without a `type` field
- Reports validation results with counts and per-file errors
- Runs executable rules (`$metadata.rules`) with **cascade gating**: a schema, hierarchy, or blocking-rule failure on a node suppresses rule evaluation for that node's hierarchy subtree. Gated checks are reported in a Coverage section so you know what wasn't evaluated and why. See [docs/rules.md](docs/rules.md#cascade-gating) for details.
- `--depth <n>` limits evaluation to hierarchy nodes within `n` breadth-first levels from the top — useful for staged agentic fix loops (fix the top level, then request the next).
- `--include-gated` evaluates rules even on gated nodes (still reported as gated) — for surfacing cheap bottom-up checks on request.

### Render space

Expand Down
2 changes: 1 addition & 1 deletion biome.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"$schema": "https://biomejs.dev/schemas/2.5.1/schema.json",
"$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
Expand Down
20 changes: 10 additions & 10 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,12 @@ Each executable rule has a **category** (`validation`, `coherence`, `workflow`,

See [docs/rules.md](rules.md) for the rules reference, including JSONata expression syntax and the full `$metadata` field reference.

### 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 future evaluative or LLM-judged layers — 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 rule checks 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
Expand Down
47 changes: 47 additions & 0 deletions docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Rules are a flat array.
| `type` | no | Restrict rule to nodes of this `resolvedType` |
| `scope` | no | Use `"global"` to evaluate once for the whole space |
| `override` | no | Only for merge conflicts: allows later duplicate `id` to replace earlier |
| `gatesDescendants` | no | Whether a violation gates downstream checks on the node's hierarchy subtree. Defaults to `true` for rules with `error` severity, `false` for `warning` and `info`. Set explicitly to override either way. |

## Categories and severity

Expand Down Expand Up @@ -137,6 +138,52 @@ Example override:
}
```

## Cascade gating

When a schema uses `$metadata.hierarchy`, rule evaluation cascades top-down through the
hierarchy tree (breadth-first from roots and orphans). A **gate** occurs when a node fails
in a way that makes its descendants' checks untrustworthy or wasteful to run:

- **Schema validation failure** on a node — always gates. The node's own rule checks are
suppressed too, since its data is structurally invalid.
- **Hierarchy structure violation** on a node (e.g. an invalid parent) — always gates the
node's subtree, though the node's own rules still run.
- **A rule violation with `gatesDescendants: true`** (the default for `error`-severity rules; `warning` and `info` rules don't gate unless they set `gatesDescendants: true`) — gates the node's subtree. The
violating node's own other rules still run (they're the same cheap deterministic layer).

Gating is per-subtree: once a node is gated, its descendants inherit the same gate (the
original blocker), rather than each generating a new one. Non-hierarchy nodes and
`scope: "global"` rules are never gated — cascade gating only applies within the hierarchy
DAG.

This exists so that expensive or semantic downstream checks (see #114) aren't wasted
evaluating nodes whose ancestors are already known-bad, and so noise doesn't drown out the
actionable failure. Set `gatesDescendants: false` on an error-severity rule whose violations shouldn't suppress
checks further down the tree, or `gatesDescendants: true` on a warning/info rule that should.

### Coverage output

`sctx validate` reports gating as **coverage gates**: which node's failure (schema,
hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the list of files gated
as a result. This makes the validation "edge" visible — e.g. "this blocked goal means all
opportunities beneath it were not evaluated" — for both human reading and agent consumption
(JSON output via `--json`, under `coverageGates`).

Use `--include-gated` to evaluate rules on gated nodes anyway (still reported as gated) —
useful for surfacing cheap, bottom-up checks (e.g. orphan detection, content quality) that
don't depend on an ancestor being valid.

### Single-file validation

`sctx validate-file <path>` applies the same gating as `sctx validate`, so a file's rule results match its entry in a full run. Rules are evaluated for the whole space and the output is restricted to the file. If the file is gated, its rule checks are skipped and a `gated:<file>` entry (kind `gated`, severity `info`) under `warnings` names the blocker, so a gated file doesn't read as clean. `--include-gated` evaluates the file's rules anyway. `--depth` is not supported.

### Depth-limited evaluation

`--depth <n>` restricts validation to hierarchy nodes within `n` breadth-first levels from
the top (roots and orphans are depth 1). This is a manual, coarser control than cascade
gating — intended for staged workflows (e.g. an agent fixes the top level, then requests
the next). Excluded nodes are reported under `skippedByDepth`, separate from gated nodes.

## Common patterns

```jsonata
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
},
"devDependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.3.191",
"@biomejs/biome": "^2.5.1",
"@biomejs/biome": "^2.5.15",
"@types/bun": "latest",
"@types/js-yaml": "^4.0.9",
"json-schema-to-ts": "^3.1.1",
Expand Down
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "structured-context",
"version": "0.12.4",
"version": "0.12.6",
"description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.",
"homepage": "https://github.com/mindsocket/structured-context",
"repository": "https://github.com/mindsocket/structured-context",
Expand Down
12 changes: 10 additions & 2 deletions plugin/skills/structured-context/references/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,25 @@ Then use the `sctx` command for all operations. Always pass `--config <path>` wh
## validate

```bash
sctx validate <space> [--watch] [--config <path>]
sctx validate <space> [--watch] [--config <path>] [--depth <n>] [--include-gated]
```

Validates all `.md` files in the space against the JSON schema. For each file:
- Extracts YAML frontmatter
- Skips files with no frontmatter or no `type` field (after `fieldMap` remapping)
- Runs JSON schema validation
- Runs reference checks (wikilinks → known node titles)
- Runs executable rules (JSONata expressions in `$metadata.rules`), reporting each violation with a severity (`error`, `warning`, `info`)
- Runs executable rules (JSONata expressions in `$metadata.rules`), with cascade gating: a
schema, hierarchy, or blocking-rule failure on a node suppresses rule evaluation for its
hierarchy subtree. Gated nodes are reported in a coverage section (and `coverageGates` in
`--json` output) so you know what wasn't checked and why.
- Checks hierarchy ordering

`--depth <n>` restricts evaluation to hierarchy nodes within `n` breadth-first levels from
the top — useful for fixing a space level by level (fix the top, re-run with a deeper
`--depth`, repeat). `--include-gated` evaluates rules on gated nodes anyway, still reporting
them as gated — use it to surface cheap bottom-up checks even when an upstream blocker fired.

Exit codes: `0` = clean (warning and info rule violations don't fail), `1` = validation errors found.

**Scenarios:**
Expand Down
3 changes: 3 additions & 0 deletions schemas/generated/latest/_structured_context_schema_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,9 @@
},
"override": {
"type": "boolean"
},
"gatesDescendants": {
"type": "boolean"
}
},
"required": ["id", "category", "description", "check"],
Expand Down
7 changes: 5 additions & 2 deletions src/commands/validate-file.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,12 @@ export { validateFile } from '../validate';
* Loads config automatically from the environment, outputs human-readable or JSON,
* and returns an exit code (0 = valid, 1 = errors found).
*/
export async function validateFileCommand(filePath: string, options: { json?: boolean } = {}): Promise<number> {
export async function validateFileCommand(
filePath: string,
options: { json?: boolean; includeGated?: boolean } = {},
): Promise<number> {
const config = loadConfig();
const result = await validateFile(filePath, config);
const result = await validateFile(filePath, config, { includeGated: options.includeGated });

if (!result.inSpace) {
if (options.json) {
Expand Down
29 changes: 27 additions & 2 deletions src/commands/validate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,12 @@ import { bundledSchemasDir } from '../schema/schema';
import type { FileValidationIssue, RuleSeverity, SpaceContext } from '../types';
import { formatErrors, validateSpace } from '../validate';

export async function validate(context: SpaceContext, options: { json?: boolean } = {}): Promise<number> {
export async function validate(
context: SpaceContext,
options: { json?: boolean; depth?: number; includeGated?: boolean } = {},
): Promise<number> {
const { schema, schemaRefRegistry } = context;
const result = await validateSpace(context);
const result = await validateSpace(context, { depth: options.depth, includeGated: options.includeGated });
const ruleCounts: Record<RuleSeverity, number> = { error: 0, warning: 0, info: 0 };
for (const v of result.ruleViolations) ruleCounts[v.severity]++;

Expand Down Expand Up @@ -68,6 +71,9 @@ export async function validate(context: SpaceContext, options: { json?: boolean
orphanCount: result.orphans.length,
parseIssues: result.parseIssues,
unresolvedContentLinks: result.unresolvedContentLinks,
coverageGates: result.coverageGates,
skippedByDepth: result.skippedByDepth,
depthLimit: result.depthLimit,
},
null,
2,
Expand Down Expand Up @@ -113,6 +119,11 @@ export async function validate(context: SpaceContext, options: { json?: boolean
console.log(fmt(' Unresolved content links', result.unresolvedContentLinks.length, true, true));
const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
console.log(fmt(' Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
if (result.depthLimit !== undefined) {
console.log(fmt(' Skipped by depth limit', result.skippedByDepth.length, true, true));
}
const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0);
console.log(fmt(' Rule checks gated (cascade)', gatedFileCount, true, true));

if (result.orphans.length > 0) {
console.log(`\nOrphans (hierarchy nodes - no parent):`);
Expand Down Expand Up @@ -193,6 +204,20 @@ export async function validate(context: SpaceContext, options: { json?: boolean
}
}

if (result.coverageGates.length > 0) {
console.log(`\nCoverage — rule checks gated by cascade (use --include-gated to evaluate anyway):`);
for (const gate of result.coverageGates) {
const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
console.log(` ${gate.file} (${gate.nodeTitle}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
for (const file of gate.gatedFiles) console.log(` ${file}`);
}
}

if (result.skippedByDepth.length > 0) {
console.log(`\nSkipped by depth limit (--depth ${result.depthLimit}):`);
for (const { file } of result.skippedByDepth) console.log(` ${file}`);
}

console.log(`\n`);

if (
Expand Down
21 changes: 19 additions & 2 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,12 @@ program
.description('Validate a single file within its space')
.argument('<path>', 'Path to the file to validate')
.option('--json', 'Output results as JSON (machine-readable, for hooks)')
.option(
'--include-gated',
'Evaluate rules even when the file is gated by an upstream schema/hierarchy/rule failure (still reported as gated)',
)
.action(async (filePath, options) => {
process.exitCode = await validateFileCommand(filePath, { json: options.json });
process.exitCode = await validateFileCommand(filePath, { json: options.json, includeGated: options.includeGated });
});

program
Expand All @@ -67,13 +71,26 @@ program
.argument('<space-name>', 'Space name')
.option('-w, --watch', 'Watch for changes and re-run validation')
.option('--json', 'Output results as JSON')
.option(
'--depth <n>',
'Evaluate only hierarchy nodes within N breadth-first levels from the top (e.g. 1 = root level only)',
(v) => parseInt(v, 10),
)
.option(
'--include-gated',
'Evaluate rules even on nodes gated by an upstream schema/hierarchy/rule failure (still reported as gated)',
)
.action(async (spaceName, options) => {
const context = buildSpaceContext(spaceName);
if (options.watch) {
await watchValidate(context);
} else {
// exitCode rather than process.exit(): exiting straight away can cut off large piped output
process.exitCode = await validate(context, { json: options.json });
process.exitCode = await validate(context, {
json: options.json,
depth: options.depth,
includeGated: options.includeGated,
});
}
});

Expand Down
Loading
Loading