validate

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. arscontexta/ops/derivation-manifest.md — vocabulary mapping, platform hints

   • Use vocabulary.notes for the notes folder name
   • Use vocabulary.note / vocabulary.note_plural for note type references
   • Use vocabulary.topic_map for MOC references
   • Use vocabulary.templates for the templates folder path

2. arscontexta/ops/config.yaml — processing depth

   • processing.depth: deep | standard | quick

If these files don't exist, use universal defaults.

Processing depth adaptation:

EXECUTE NOW

Target: $ARGUMENTS

Parse immediately:

• If target contains a note name: validate that specific note
• If target contains --handoff: output RALPH HANDOFF block at end
• If target is "all" or "notes": validate all notes in docs/notes/ directory
• If target is empty: ask which note to validate

Execute these steps:

Step 1: Locate Template

Determine which template applies to the target note:

1. Check the note's location — notes in docs/notes/ use the standard note template
2. Check the type field in frontmatter — specialized types may have dedicated templates
3. Look for a templates directory (check arscontexta/ops/arscontexta/templates/ or domain-specific path from derivation manifest)
4. If the template has a _schema block, read it — this is the authoritative schema definition

If no template is found, use the default schema checks below.

Step 2: Read Target Note

Read the target note's full YAML frontmatter. Parse:

• All YAML fields and their values
• The body content (for link scanning)
• The footer section (for Topics and Relevant Notes)

Step 3: Run Schema Checks

Run ALL validation checks. Each check produces PASS, WARN, or FAIL.

START NOW.

Schema Checks

Required Fields (FAIL if missing)

A missing required field is a hard failure. The note cannot pass validation without these.

Description Quality (WARN if weak)

How to check "adds new info": Read the title (filename without .md). Read the description. If the description merely restates the title using different words, it fails this check. A good description adds one of:

• Mechanism — how or why the claim works
• Scope — what boundaries the claim has
• Implication — what follows from the claim
• Context — where the claim applies

Examples:

Bad (restates title):

• Title: vector proximity measures surface overlap not deep connection
• Description: "Semantic similarity captures surface-level overlap rather than genuine conceptual relationships"

Good (adds mechanism):

• Title: vector proximity measures surface overlap not deep connection
• Description: "Two notes about the same concept with different vocabulary score high, while genuinely related ideas across domains score low"

YAML Validity (FAIL if broken)

Domain-Specific Enum Checks (WARN if invalid)

If the note has fields with enumerated values, check them against the template's _schema.enums block:

If a field has a value not in the enum list, report the invalid value and list the valid options.

Link Health (WARN per broken link)

How to verify link resolution: For each [[link text]], check if a file named link text.md exists anywhere in the vault. Wiki links resolve by filename, not path.

Relevant Notes Format (WARN if incorrect)

Composability (WARN if fails)

Topic labels vs claims:

• "knowledge management" — topic label, not a claim, FAILS composability
• "knowledge management requires curation not accumulation" — claim, PASSES composability

Batch Mode

When validating all notes (target is "all" or "notes"):

1. Discover all .md files in docs/notes/ directory
2. Optionally include additional directories (e.g., arscontexta/self/memory/) if they exist
3. Run all schema checks on each note
4. Produce summary report:
   • Total notes checked
   • PASS / WARN / FAIL counts
   • Top issues grouped by check type
   • Notes needing immediate attention (FAIL items)
   • Pattern analysis: are certain check types failing systematically?

Batch output format:

## Validation Summary

Checked: N notes
- PASS: M (X%)
- WARN: K (Y%)
- FAIL: J (Z%)

### FAIL Items (immediate attention)
| Note | Check | Detail |
|------|-------|--------|
| [[note]] | description | Missing |
| [[note]] | topics | No topics footer |

### Top WARN Patterns
- Description restates title: N notes
- Missing context phrases in relevant_notes: N notes
- Enum value not in template: N notes

### Notes Needing Attention
1. [[note]] — 2 FAIL, 1 WARN
2. [[note]] — 1 FAIL, 3 WARN

Output Format (Single Note)

=== VALIDATION: [[note title]] ===

PASS:
- description: present, 147 chars, adds mechanism beyond title
- topics: ["[[topic-name]]"] — exists
- yaml: well-formed, valid delimiters
- composability: title works as prose ("This note argues that [title]")

WARN:
- relevant_notes: bare link without context phrase for [[note-x]]
- type: "observation" not in template enum (valid: claim, methodology, tension, problem, learning)

FAIL:
- (none)

Overall: PASS (2 warnings)
===

If WARN or FAIL items exist, include:

### Suggested Fixes
- **relevant_notes**: Add context phrase — e.g., `["[[note-x]] -- extends this by adding..."]`
- **type**: Change to valid enum value or propose adding "observation" to template

Handoff Mode (--handoff flag)

When invoked with --handoff, output this structured format at the END:

=== RALPH HANDOFF: validate ===
Target: [[note title]]

Work Done:
- Validated against [template name] schema
- Checks run: N
- Status: PASS | WARN | FAIL

Findings:
- PASS: [list]
- WARN: [list or "none"]
- FAIL: [list or "none"]

Files Modified:
- [task file path] (Validate section updated, if applicable)

Learnings:
- [Friction]: [description] | NONE
- [Surprise]: [description] | NONE
- [Methodology]: [description] | NONE
- [Process gap]: [description] | NONE

Queue Updates:
- Mark: validate done for this task
=== END HANDOFF ===

Task File Update

When a task file is in context (pipeline execution), update the ## Validate section:

## Validate
**Validated:** [UTC timestamp]

Schema check against [template name]:
- description: PASS (147 chars, adds mechanism beyond title)
- topics: PASS (["[[topic-name]]"])
- yaml: PASS (well-formed)
- type: not specified (optional)
- relevant_notes: WARN (bare link for [[note-x]])
- composability: PASS

Overall: PASS (1 warning)

Severity Levels

FAIL blocks pipeline completion. A note with any FAIL-level issue should NOT be marked done in the queue. It stays at current_phase: "verify" (or "validate" if run standalone) for re-validation after fixes.

WARN does not block. Warnings are quality signals, not gates. A note can proceed through the pipeline with warnings.

Critical Constraints

never:

• block note creation based on validation failures (validation is a quality check, not a gate)
• auto-fix issues without reporting them first
• skip checks because the note "looks fine"
• report PASS without actually running the check
• ignore _schema blocks in templates when they exist

always:

• check ALL schema requirements, not a subset
• report specific field values in FAIL/WARN messages (not just "description is weak")
• suggest concrete fixes for every WARN and FAIL
• use template _schema as the authoritative source when available
• fall back to default checks gracefully when no template exists
• log patterns when running batch validation (recurring issues signal systematic problems)