motief/thoughts/shared/mindmodel

Purpose

A small, developer-focused guide for the mindmodel validator used by reviewers and contributors.

What this validator does

• Validates the repository's mindmodel manifest and evidence against project policies.
• Flags common issues for reviewers (secrets, missing evidence, excessively truncated evidence, policy violations).

Where the manifest lives

The canonical manifest is stored at:

.mindmodel/manifest.yaml

Reviewer checklist

When reviewing mindmodel submissions, make a quick pass over the following items:

1. Secrets: Ensure there are no secrets (API keys, tokens, private credentials) included in the manifest or evidence. If you spot secrets, escalate and remove them immediately.
2. Evidence truncation: Verify that evidence files or snippets are not truncated in a way that removes important context. If evidence is truncated for size, confirm the truncated portion is non-essential and that a pointer to full evidence is provided.
3. Read-only policy: Confirm that the mindmodel only documents read-only artifacts. The validator and reviewers must ensure no actions, credentials, or writable endpoints are exposed.
4. Completeness: Check that required fields from the manifest schema are present and that evidence links to real files or reports in the repository.

Running the validator locally

You can run the validator locally with the provided Python script. Example:

python -m scripts.mindmodel.cli .mindmodel/manifest.yaml reports/tmp.json

The CLI prints JSON to stdout and accepts positional arguments: manifest_path [report_path].

Validator code / CLI: scripts/mindmodel/validator.py and scripts/mindmodel/cli.py

Notes

• Keep this document concise and developer-focused. It exists to help reviewers run the validator and spot common problems quickly.
• If you change the manifest schema or validator behavior, update this README to reflect any new checklist items or command-line options.