---
date: 2026-03-24
topic: "mindmodel-generation"
status: draft
---

# Implementation Plan: mindmodel-generation

Goal: Implement a lightweight, safe Constraint Validator for the generated .mindmodel/ snapshot plus small CI / config artifacts to validate and integrate the manifest incrementally and safely.

Design reference: thoughts/shared/designs/2026-03-24-mindmodel-generation-design.md

---

## Overview

This plan breaks work into four batches: Foundation, Core, Components, Integration/Configs. Each micro-task is small and independently testable. Tests accompany core modules. The validator intentionally avoids reading repository secret files and only scans manifest text and evidence snippets.

## Batch 1: Foundation (parallel)

- Task 1.1: Manifest loader
  - Path: scripts/mindmodel/loader.py
  - Test: tests/scripts/mindmodel/test_loader.py
  - Behavior: load YAML or JSON manifest, normalize to dict, raise ManifestLoadError on failure

- Task 1.2: Low-level checks
  - Path: scripts/mindmodel/checks.py
  - Test: tests/scripts/mindmodel/test_checks.py
  - Behavior: file existence (without opening), truncated-snippet heuristics, manifest-text secret heuristics

## Batch 2: Core Modules (depends on Batch 1)

- Task 2.1: Constraint Validator (core)
  - Path: scripts/mindmodel/validator.py
  - Test: tests/scripts/mindmodel/test_validator.py
  - Behavior: load manifest, scan for secrets, verify referenced files exist, detect truncated snippets, produce machine-readable report and exit codes: 0 ok, 1 warnings, 2 critical

## Batch 3: Components (depends on Batch 2)

- Task 3.1: CLI wrapper for CI and local runs
  - Path: scripts/mindmodel/cli.py
  - Test: tests/scripts/mindmodel/test_cli.py
  - Behavior: simple wrapper delegating to validator; callable as python -m scripts.mindmodel.cli

## Batch 4: Integration / Configs / Docs (parallel)

- Task 4.1: CI workflow to run validator on PRs and scheduled checks
  - Path: .github/workflows/mindmodel-validate.yml
  - Behavior: run tests, then run validator against .mindmodel/manifest.yaml if present

- Task 4.2: .mindmodel/ README describing read-only policy
  - Path: .mindmodel/README.md

- Task 4.3: Add a minimal pre-commit config (trailing whitespace, eof fixer, check-yaml)
  - Path: .pre-commit-config.yaml

## Verification

- Each unit has a focused pytest test to validate behavior.
- CI will run the validator and tests; the validator should skip if no manifest present.

## Implementation Checklist

- [ ] Add scripts/mindmodel/loader.py + tests/scripts/mindmodel/test_loader.py
- [ ] Add scripts/mindmodel/checks.py + tests/scripts/mindmodel/test_checks.py
- [ ] Add scripts/mindmodel/validator.py + tests/scripts/mindmodel/test_validator.py
- [ ] Add scripts/mindmodel/cli.py + tests/scripts/mindmodel/test_cli.py
- [ ] Add .github/workflows/mindmodel-validate.yml
- [ ] Add .mindmodel/README.md
- [ ] Add .pre-commit-config.yaml

## Next steps

1. Create the files above in small commits (one micro-task per commit).
2. Run unit tests for each new module as added.
3. Open a small PR with the validator + CI + docs; request reviewers to run the validator locally.