feat(mindmodel): add manifest loader and tests

2026-03-24 21:24:58 +01:00
parent 9c82962d47
commit 2efd7ba3a0
17 changed files with 806 additions and 122 deletions
@@ -545,5 +545,98 @@
    "target_id": null,
    "metadata": {},
    "created_at": "2026-03-23T22:52:47.836920Z"
+  },
+  {
+    "id": "de3394a0-8c8e-4282-8369-f53aa957fd46",
+    "actor_id": null,
+    "action": "embedding_failed",
+    "target_type": "motion",
+    "target_id": "99",
+    "metadata": {
+      "error": "RuntimeError(\"Simulated embedding failure for index 0: 'failing motion'\")"
+    },
+    "created_at": "2026-03-24T19:08:06.647810Z"
+  },
+  {
+    "id": "8491ed90-9314-41a9-9d02-092a5d0bebd5",
+    "actor_id": null,
+    "action": "test_action",
+    "target_type": "unit",
+    "target_id": "u1",
+    "metadata": {
+      "k": 1
+    },
+    "created_at": "2026-03-24T19:08:08.085618Z"
+  },
+  {
+    "id": "ae7c88e5-ba28-4012-8991-c58fea9c0778",
+    "actor_id": null,
+    "action": "another_action",
+    "target_type": "motion",
+    "target_id": null,
+    "metadata": {},
+    "created_at": "2026-03-24T19:08:08.131631Z"
+  },
+  {
+    "id": "b73e6bf8-2b66-43bf-ad9c-e92d34ae38db",
+    "actor_id": null,
+    "action": "embedding_failed",
+    "target_type": "motion",
+    "target_id": "99",
+    "metadata": {
+      "error": "RuntimeError(\"Simulated embedding failure for index 0: 'failing motion'\")"
+    },
+    "created_at": "2026-03-24T19:18:02.854710Z"
+  },
+  {
+    "id": "3a6bf0e0-9f07-477d-9079-715d8c0f39c4",
+    "actor_id": null,
+    "action": "test_action",
+    "target_type": "unit",
+    "target_id": "u1",
+    "metadata": {
+      "k": 1
+    },
+    "created_at": "2026-03-24T19:18:05.512388Z"
+  },
+  {
+    "id": "75d9e229-78e6-439e-8095-c01ba7830de9",
+    "actor_id": null,
+    "action": "another_action",
+    "target_type": "motion",
+    "target_id": null,
+    "metadata": {},
+    "created_at": "2026-03-24T19:18:05.557773Z"
+  },
+  {
+    "id": "d45fc116-47be-4486-ba5c-ab2edd7f7e76",
+    "actor_id": null,
+    "action": "embedding_failed",
+    "target_type": "motion",
+    "target_id": "99",
+    "metadata": {
+      "error": "RuntimeError(\"Simulated embedding failure for index 0: 'failing motion'\")"
+    },
+    "created_at": "2026-03-24T19:28:43.867346Z"
+  },
+  {
+    "id": "b4ead1cd-58b1-4ff6-aa73-c77ab09ba063",
+    "actor_id": null,
+    "action": "test_action",
+    "target_type": "unit",
+    "target_id": "u1",
+    "metadata": {
+      "k": 1
+    },
+    "created_at": "2026-03-24T19:28:45.051895Z"
+  },
+  {
+    "id": "463bfa1b-59fe-4fd3-a8dd-b39674948656",
+    "actor_id": null,
+    "action": "another_action",
+    "target_type": "motion",
+    "target_id": null,
+    "metadata": {},
+    "created_at": "2026-03-24T19:28:45.097703Z"
  }
 ]
@@ -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.