Skip to content

Plan Format Validation Tooling

Plan Metadata

  • Plan type: sub-plan
  • Parent plan: deterministic-plan-tooling.md
  • Depends on: N/A
  • Status: documentation

Status semantics: - draft: Plan is being created or updated and is not final. - approved: Plan is approved but not yet applied in code. - documentation: Code currently exists and matches the plan contract.

Update rule: - When an existing plan is edited, set status to draft until re-approved.

System Intent

  • What is being built: Deterministic validator tooling for docs/plans/*.md that enforces template structure and emits actionable remediation TODOs.
  • Primary consumer(s): AI agents and developers maintaining plan documents.
  • Boundary (black-box scope only): Validate plan file structure (metadata, section order, Mermaid block, flow contract structure) and write a checklist of required fixes to a temporary TODO artifact.

Stage Gate Tracker

  • [x] Stage 1 Mermaid approved
  • [x] Stage 2 I/O contracts approved
  • [x] Stage 3 pseudocode/technical details approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  A[Plan Markdown Files - docs/plans/*.md] -->|read and parse headings/sections| B[Plan Format Validator - scripts/plan_tooling/validate_plan_format.py]
  B -->|collect issue codes and line numbers| C[Validation Result Set]
  C -->|write remediation checklist markdown| D[Temporary TODO Output - /tmp/todo.md]
  E[Unit Tests - main/server/tests/unit/test_plan_format_validator.py] -->|assert pass/fail behavior| B
  F[CLI Callers] -->|run validator command with paths| B

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class A,B,C,D,E,F unchanged;

2. Black-Box Inputs and Outputs

Global Types

ValidationRequest {
  plans_dir: string (required; directory containing plan markdown files)
  todo_path: string (required; output path for remediation checklist)
  include_index?: boolean (optional; legacy switch to include docs/plans/index.md when present)
}

ValidationIssue {
  code: string (stable machine-readable validation code)
  message: string (human-readable issue detail)
  line?: number (optional line number within plan file)
}

ValidationSummary {
  plans_checked: number
  plans_with_issues: number
  total_issues: number
}

ValidationResult {
  summary: ValidationSummary
  issues_by_plan: map<string, ValidationIssue[]>
  todo_path: string
  exit_code: 0 | 1 | 2
}

Flow: validatePlanFiles

  • Test files: main/server/tests/unit/test_plan_format_validator.py
  • Core files: scripts/plan_tooling/validate_plan_format.py

Type Definitions

ValidatePlanFilesInput = ValidationRequest

ValidatePlanFilesOutput {
  result: ValidationResult
}

Paths

path-name input output/expected state change path-type notes updated
validate-plan-files.success-no-issues ValidatePlanFilesInput with compliant plans ValidatePlanFilesOutput result.exit_code=0 and summary.plans_with_issues=0 happy path todo output still renders summary for auditability Y
validate-plan-files.success-with-issues ValidatePlanFilesInput with one or more non-compliant plans ValidatePlanFilesOutput result.exit_code=1 and issues_by_plan populated happy path issues must include stable code and deterministic message text Y
validate-plan-files.invalid-plans-dir ValidatePlanFilesInput plans_dir missing/not-directory ValidatePlanFilesOutput result.exit_code=2 error fail fast before file traversal Y

Flow: validateMermaidSection

  • Test files: main/server/tests/unit/test_plan_format_validator.py
  • Core files: scripts/plan_tooling/validate_plan_format.py

Type Definitions

ValidateMermaidSectionInput {
  section_lines: string[] (lines in section 1 of a plan)
}

ValidateMermaidSectionOutput {
  issues: ValidationIssue[]
}

Paths

path-name input output/expected state change path-type notes updated
validate-mermaid-section.reference-and-flowchart ValidateMermaidSectionInput with required reference and flowchart fenced block ValidateMermaidSectionOutput issues=[] happy path section reference must match canonical skill path exactly Y
validate-mermaid-section.missing-reference ValidateMermaidSectionInput without required reference line ValidateMermaidSectionOutput issues includes code=mermaid-reference error missing reference is a format violation even if diagram exists Y
validate-mermaid-section.non-flowchart ValidateMermaidSectionInput with fenced block not starting with flowchart ValidateMermaidSectionOutput issues includes code=mermaid-flowchart error keeps diagrams structurally consistent across plans Y

Flow: generatePlanFormatTodo

  • Test files: main/server/tests/unit/test_plan_format_validator.py
  • Core files: scripts/plan_tooling/validate_plan_format.py

Type Definitions

GeneratePlanFormatTodoInput {
  issues_by_plan: map<string, ValidationIssue[]>
  plans_checked: number
  output_path: string
}

GeneratePlanFormatTodoOutput {
  output_path: string
  rendered: boolean
}

Paths

path-name input output/expected state change path-type notes updated
generate-plan-format-todo.with-failures GeneratePlanFormatTodoInput with non-empty issues_by_plan GeneratePlanFormatTodoOutput rendered=true and checklist entries grouped by plan happy path each issue row includes code and message, with line when available Y
generate-plan-format-todo.no-failures GeneratePlanFormatTodoInput with empty issues_by_plan GeneratePlanFormatTodoOutput rendered=true and success summary subpath todo file is still created for CI/automation traceability Y

3. Pseudocode / Technical Details for Critical Flows (Optional)

  • Flow name:: validate-plan-format-main 

    parse CLI args for plans_dir, todo_path, include_index
assert plans_dir exists and has markdown files
for each plan:
  validate required headings and order
  validate metadata and stage-gate rows
  validate mermaid section and flowchart block
  validate section 2 flow blocks and path table schema
aggregate issues_by_plan
write todo markdown to todo_path
return exit code 0 when no issues, 1 when issues exist, 2 on invalid invocation inputs

  • Implementation notes:

  • Issue codes are stable strings so downstream tooling can classify failure types.
  • TODO output is deterministic and safe to consume by follow-up automation.

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.