/prose-validate

namespace: aiwg
name: prose-validate
description: Validate an OpenProse program file against Prose contract grammar without executing it — checks frontmatter, contract structure, service references, and strategy syntax
version: 0.1.0
platforms: [all]
requires:
  - target: path to a .md program file, or directory containing a multi-service program (index.md entry)
ensures:
  - report: structured validation report with per-check pass/fail/warn status
  - verdict: one of VALID, INVALID, or VALID WITH WARNINGS
  - "if multi-service: service wiring graph checked for satisfied requires: and DAG validity"
errors:
  - prose-not-found: OpenProse installation not detected; run /prose-detect for guidance
  - file-not-found: target path does not exist or is not a valid .md file
invariants:
  - validation never executes the program — structural analysis only
  - empty ensures: always fails; a program that ensures nothing is structurally invalid

Prose Validate Skill

You validate OpenProse program files against the contract grammar, checking for structural correctness without executing the program.

Triggers

• "validate prose program" / "check prose file"
• "is this a valid prose program"
• "prose validate [path]"
• "lint prose contract"

Input

A path to a `.md` file to validate, or a directory containing a multi-service program.

Behavior

Step 0: Detect OpenProse Installation

Run `/prose-detect` to locate the OpenProse installation and resolve `PROSE_ROOT`. The contract grammar spec at `$PROSE_ROOT/prose.md` is used as the validation reference. If not found, stop and report:

OpenProse not found. Run /prose-setup to install it, or set PROSE_ROOT to an existing installation.

Validation Checks

Run all checks and report results as pass/fail with details:

1. Frontmatter Validation

• [ ] YAML frontmatter present (between `---` markers)
• [ ] `name` field present and non-empty
• [ ] `kind` field present and valid (`program`, `service`, `library`, `test`)
• [ ] If `kind: program`: `services` list present and non-empty
• [ ] No unknown/unsupported frontmatter fields (warn, don't fail)

2. Contract Validation

• [ ] `requires:` section present (warn if missing — some programs have no inputs)
• [ ] `ensures:` section present and non-empty (fail if missing — all valid programs must ensure something)
• [ ] Each `requires:` entry has format `- name: description`
• [ ] Each `ensures:` entry has format `- name: description` or `- name: conditional description`
• [ ] No duplicate names within `requires:` or `ensures:`

3. Strategy Validation

• [ ] If `strategies:` present: each entry uses `when condition: action` format
• [ ] Strategy conditions reference names from `requires:` or `ensures:`
• [ ] No contradictory strategies (e.g., two strategies for the same condition with different actions)
• [ ] Iteration limits specified where loops are implied (e.g., "max N iterations")

4. Error and Invariant Validation

• [ ] If `errors:` present: each entry describes a failure condition
• [ ] If `invariants:` present: each entry describes an unconditional property
• [ ] Error conditions are reachable (reference known inputs or states)

5. Service Reference Validation (Multi-Service Programs)

• [ ] Each service listed in `services:` has a corresponding `.md` file in the same directory
• [ ] Each service file passes frontmatter validation independently
• [ ] Service contracts are wirable: every `requires:` input is satisfied by another service's `ensures:` output or by the program's `requires:`
• [ ] No circular dependencies between services
• [ ] Execution order is determinable (DAG has valid topological sort)

Output Format

## Prose Validation Report

**File**: {path}
**Program**: {name}
**Kind**: {kind}

### Results

| Check | Status | Details |
|-------|--------|---------|
| Frontmatter | {PASS/FAIL/WARN} | {details} |
| Contract structure | {PASS/FAIL/WARN} | {details} |
| Strategy syntax | {PASS/FAIL/WARN/SKIP} | {details} |
| Error channels | {PASS/FAIL/WARN/SKIP} | {details} |
| Service references | {PASS/FAIL/WARN/SKIP} | {details} |

### Issues Found
{numbered list of specific issues, or "No issues found"}

### Overall: {VALID / INVALID / VALID WITH WARNINGS}

Edge Cases

• **Directory input**: If given a directory, look for `index.md` as entry point
• **No strategies**: Valid — strategies are optional
• **No errors**: Valid — error channels are optional
• **Single-component with services**: Flag as inconsistency (kind should be `program`)
• **Empty ensures**: Always fail — a program that ensures nothing is meaningless

Model

This skill runs on **Sonnet** — validation is structural analysis, not complex reasoning.

References

• @$AIWG_ROOT/agentic/code/addons/prose-integration/README.md — prose-integration addon overview
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md — Run prose-detect before validating; read grammar spec from PROSE_ROOT
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/vague-discretion.md — Concrete pass/fail/warn criteria for each validation check
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference for AIWG addon integration commands