feat(mindmodel): add manifest loader and tests
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
---
|
||||
date: 2026-03-24
|
||||
topic: "mindmodel-generation"
|
||||
status: draft
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
We generated a .mindmodel/ snapshot for this repository using an automated orchestrator. The output includes inferred constraints, patterns, schema snippets, and remediation recommendations. We need a short, validated design that explains what was produced, how to verify and integrate it safely, and a recommended next set of changes (low-risk remediation and CI additions).
|
||||
|
||||
## Constraints
|
||||
|
||||
**Non-negotiables:**
|
||||
- Keep the generated .mindmodel/ files read-only until validated.
|
||||
- Do not make behavioral changes to production code in the same change as model metadata updates.
|
||||
- Avoid committing secrets or lockfiles without explicit review.
|
||||
|
||||
**Limitations:**
|
||||
- The orchestrator used heuristic file reads; some evidence pointers may be truncated or approximate.
|
||||
- No poetry.lock / requirements.txt or CI workflows were found; dependency remediation must be conservative.
|
||||
|
||||
## Approach
|
||||
|
||||
I'm choosing an **audit-first, incremental integration** approach because the generated artifacts are high-value policy documents but rely on evidence that needs verification. We will: (1) validate evidence pointers and missing files, (2) mark fixes for trivial issues (move pytest to dev-deps, add formatter configs) in a small non-invasive PR, (3) integrate the .mindmodel/ into the repo and add a CI lint step that validates the manifest, and (4) iterate on higher-risk changes after tests pass.
|
||||
|
||||
Alternatives considered:
|
||||
- Accept-and-commit everything immediately (faster) — rejected because of truncated reads and potential wrong pointers.
|
||||
- Manual rewrite of constraints by hand (accurate) — rejected due to time cost; validation + targeted fixes gives best ROI.
|
||||
|
||||
## Architecture
|
||||
|
||||
This is a documentation/metadata integration task, not a runtime service. Components:
|
||||
|
||||
- **.mindmodel/**: constraint files and manifest produced by orchestrator. Source of truth for conventions and inferred patterns.
|
||||
- **Validator job (CI)**: lightweight script/CI step that verifies manifest consistency, required files exist, and key evidence pointers resolve.
|
||||
- **Small remediation PRs**: conservative code/config edits (pyproject tweaks, add black/ruff/isort configs, pre-commit) that enable future automation.
|
||||
|
||||
## Components
|
||||
|
||||
- Constraint Validator: verifies every .mindmodel/ constraint references existing files; flags truncated evidence ranges; ensures no secrets.
|
||||
- Staging branch: holds small remediation commits; each commit is limited to one class of change (deps dev/prod move, linters, CI yaml).
|
||||
- CI pipeline changes: add a validation job and a docs check that ensures .mindmodel/ manifest is up to date.
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. Orchestrator output (.mindmodel/) exists in the working tree.
|
||||
2. Validator runs locally or in CI to check pointers and file existence.
|
||||
3. Developer reviews validator report and accepts/edits constraint files.
|
||||
4. Remediation PRs are opened for low-risk fixes.
|
||||
5. CI runs tests + validator; on green we merge and enable scheduled checks.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Validator failures are non-blocking for mainline but must be resolved before we rely on constraints for automation.
|
||||
- If a constraint references a deleted or moved file, mark the constraint as "needs-review" in the manifest and leave file unchanged.
|
||||
- For ambiguous evidence (truncated reads), add an explicit comment in the constraint file pointing to the reviewer.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Unit: small pytest tests that assert README/pyproject presence and that manifest YAML parses.
|
||||
- Integration: CI job that runs the Constraint Validator and fails on missing files or secrets.
|
||||
- Manual: reviewer inspects a sample of constraint files (3-5) for accuracy before merging.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Do we want the validator to auto-fix trivial issues (reformatting YAML paths) or only report? I'm leaning toward report-only for safety.
|
||||
- Should .mindmodel/ be protected by branch policy or just reviewed by humans? Recommend human review + CI check, not protected branch yet.
|
||||
|
||||
## Next Steps (what I'll do now)
|
||||
|
||||
1. Create this design doc (done).
|
||||
2. Commit the design doc to the repo (doing now).
|
||||
3. Spawn the planner to create a step-by-step implementation plan based on this design (spawning now).
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user