mindgap: Instructions file for Codex

AGENTS.md — knowledge protocol for loop sessions

You are a loop session adding knowledge to the mindgap graph. CLI: mindgap (on PATH) or python3 -m mindgap from this repo. DB: default ~/.mindgap/mindgap.db (env MINDGAP_DB/MINDGAP_HOME override).

Two interfaces, same db: the CLI (above) and the MCP server (python3 -m mindgap.mcp, registered in .mcp.json — tools mindgap_ingest/mindgap_find/mindgap_context/mindgap_link/etc.). Prefer the MCP tools when available: mindgap_ingest enforces the rules below (rejects dangling-endpoint payloads whole, requires created_by, returns the persisted rows) so you can't silently desync. The rules in this file apply identically whichever interface you use.

MUST rules

1. Run mindgap context "<topic>" BEFORE researching a topic — read what exists, avoid duplicates, build on existing nodes.
2. Write via mindgap ingest - with created_by = your loop name (e.g. loop:confluence-scan) on every node and edge.
3. Every node sourced from Confluence/GitHub/arXiv MUST carry a urls entry ({"label","url","kind"}; kind: confluence|github|arxiv|jira|web).
4. Use [[wiki-links]] in bodies to densify the graph — each [[node-id]] auto-creates a mentions edge (stub node if target missing). Wiki-links MUST use the exact node id (check with mindgap find), not the title or a guessed slug — [[maestro]] is a dangling stub if the node is repo-maestro.
5. Prefer upserting existing ids over creating near-duplicate new nodes — run mindgap find first (see below).
6. Run mindgap export at session end (snapshot to ~/.mindgap/snapshots/).

Vocabularies

• Node type: concept | definition | software | repo | page | paper | person | team | design | feature | learning | jira-ticket | todo | stub
• Edge rel: relates_to | defines | implements | depends_on | cites | part_of | mentions | assigned_to | reported_by | resolved_by
• Todo status: an open todo is a type='todo' node tagged neither status:done nor status:dropped — both are terminal. status:doing is in-flight work and stays open. A todo carrying no status:* tag at all is still open — some are tagged open-action instead. The rule is stated as an absence, so apply it as one wherever you can read the tag list yourself. find cannot: it matches a tag token and has no negation, so it cannot express "not done". The todo-mindmap skill therefore asks for what it can name — tag="status:open", then again tag="status:doing" — which is the closest approximation available through that tool and does miss a todo tagged neither. Closing one means: strip every status:* tag, append status:done (or status:dropped), and bump updated_at. Timestamps are UTC at second resolution, written with a +00:00 offset — which is what datetime.now(timezone.utc).isoformat(timespec="seconds") produces — and never a Z, which is what chrono's to_rfc3339 would give you.
• mindtop (Rust, tui/) implements the tag/timestamp half of that closing rule: tui/src/db.rs::close_todo rewrites the tags JSON directly in SQL — strip status:*, push status:done, bump updated_at — and nothing else. It is not equivalent to a skill-driven close: the todo-mindmap skill additionally appends a **Done:** YYYY-MM-DD — <outcome> line to the body and adds a resolved_by edge when an artifact exists, neither of which close_todo writes; nor can it record status:dropped, which only the skill path can set. A todo closed from the TUI is therefore correctly out of the open set but carries no record of how. If the tag/timestamp rule above changes, close_todo must change with it; tests/test_tui_contract.py is what catches divergence — but only once the crate is built, since it skips when tui/target/debug/mindtop is absent.