3. Shape Lint
Shape Lint validates note heading structure against matching Shape templates.
When:
Enable shape heading validation
is enabled in:
Settings → Shapes
Shape validation becomes part of normal Vault Lint.
Run:
Forge: Run Vault Lint
What Shape Lint Checks
| Rule | Meaning |
|---|---|
shape_heading_missing | Required template heading is missing |
shape_heading_order | Matching headings exist but appear in the wrong order |
shape_heading_extra | A heading exists outside the expected structure |
shape_section_empty | Required section exists but contains no direct content |
Shape validation helps detect gradual structural drift as templates evolve over time.
Recursive Tree Matching
Shape Lint compares heading trees recursively.
Matching is not based on heading text alone.
Forge evaluates:
heading text + heading level + parent heading chain
That means:
## Risks
under:
# Project
is treated differently from:
## Risks
under:
# Decision
Forge validates structural context, not just isolated headings.
Tiny tree goblin remains defeated.
Why Recursive Matching Matters
Without recursive matching, templates become unreliable in larger notes.
Forge can detect:
- misplaced sections
- duplicated heading branches
- broken hierarchy
- incorrect nesting
- drifted templates
- missing structure
This becomes especially useful for:
- project systems
- operational runbooks
- research workflows
- meeting systems
- structured templates
Scope
Shape Lint can scan:
- all vault notes
- selected folders only
Using folder scope is recommended while:
- testing new templates
- refining shapes
- experimenting with workflows
- rolling out structure gradually
Most users should switch to full-vault validation only after Shapes stabilize.
Severity and Strict Mode
Strict mode primarily affects Shape validation severity.
It does not override schema-defined field severities.
| Finding | Non-strict | Strict |
|---|---|---|
| Missing heading | Error | Error |
| Wrong heading order | Warning | Error |
| Extra H1 heading | Warning | Error |
| Extra H2+ heading | Info | Warning |
| Empty required section | Info | Warning |
Strict mode is best suited for mature vaults with stable templates.
Most users should begin with strict mode disabled.
Empty Sections
shape_section_empty checks whether required sections contain direct content when empty headings are not allowed.
Example:
## Decisions
with no meaningful body content beneath it may trigger an empty section finding.
Turn on Allow empty headings in Forge settings when your vault intentionally uses structural headings without prose, such as an H1 followed immediately by H2/H3 headings or a section whose first content is a Dataview table.
This helps detect notes that technically match the template but were never meaningfully completed.
Shape Drift Over Time
Without validation, recurring note types gradually diverge.
Examples:
- headings renamed manually
- sections reordered
- required sections skipped
- nested headings moved
- templates partially copied
Shape Lint helps surface those inconsistencies before dashboards, workflows, exports, and operational systems become unreliable.
Recommended Workflow
A practical workflow usually looks like this:
- Create or refine Shapes
- Run Vault Lint
- Review Shape findings
- Run Shape Repair dry run
- Review proposed repairs
- Apply repairs gradually
- Re-run lint
Slow refinement usually works better than aggressive large-scale repair passes.
Shapes and Dataview
Consistent note structure improves:
- Dataview dashboards
- Bases
- exports
- relationship indexes
- AI-assisted retrieval
- operational review systems
Predictable structure makes downstream tooling more reliable.
