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.