You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
73 lines
4.2 KiB
73 lines
4.2 KiB
---
|
|
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).
|
|
|