# Archivum agent contract

Archivum is a durable, Git-backed workspace for knowledge, projects, decisions, and long-horizon work. A useful agent interaction should leave the archive more accurate and easier to resume. Chats disappear; the archive changes.

These instructions are tool-neutral. Follow them in Codex, Claude Code, Cursor, and other repository-aware agents.

## Orient before acting

1. Read `00_meta/workspace_profile.md`, `00_meta/workspace_state.md`, and `config.yaml`.
2. Inspect `git status --short`. Existing changes belong to the user; preserve unrelated work.
3. Search with `rg` or `rg --files` before creating a new record. Extend the canonical record when one already exists.
4. Read only the files relevant to the request. Do not recursively ingest the whole Archivum by default.
5. If the task changes durable state, identify the destination, visibility, and evidence level before writing.

Run `archivum doctor` after structural changes and `archivum status` when a quick orientation is useful. If the package is not installed, use `python -m archivum_tools.cli ...` from the workspace root.

## Route information deliberately

- `00_meta/`: workspace profile, live state, schemas, procedures, templates, and tooling.
- `01_projects/<slug>/`: active bodies of work. Keep a `README.md`, `tasks.md`, and append-only `logbook/`; add `experiments/`, `literature/`, and `sources/` when useful.
- `02_ideas_and_explorations/`: hypotheses and early ideas that have not earned project status.
- `03_knowledge_base/`: durable explanations, source notes, methods, and references.
- `04_global_tasks_and_planning/`: cross-project priorities, task inboxes, and planning state.
- `05_outputs_and_dissemination/`: drafts and released outputs, with provenance back to source records.
- `06_reviews_and_service/`: reviews, service, and external assessment work.
- `07_professional_development/`: career and learning records.
- `08_daily_journal/`, `09_calendar/`, `10_philosophy_and_reflection/`, `11_personal_journal/`: time-based and reflective records.
- `12_meetings_and_notes/`: meeting records, decisions, and owned actions.

Use `00_meta/schema.md` for metadata and naming conventions. Use a template from `00_meta/templates/` rather than inventing a parallel format.

## Preserve epistemic state

- Keep **observation**, **hypothesis**, **proposal**, **experiment**, **result**, **decision**, and **synthesis** distinct.
- Never promote a plan to an implementation, an observation to a result, or a result to an established fact without evidence.
- Record null, negative, contradictory, and inconclusive evidence when it changes what should be believed or attempted next.
- Attach sources as URLs or repository-relative paths. Distinguish quotation, paraphrase, and inference.
- Preserve authorship. Mark AI-assisted synthesis or drafting when attribution matters.
- Record uncertainty and the cheapest next test instead of smoothing gaps into confident prose.

For research records, use `maturity: seed | proposal | in-progress | observed | validated | retired`. “Validated” means the record links to evidence sufficient for its stated scope; it does not mean universal truth.

## Make writes resumable

For a substantive change:

1. Update the smallest canonical record that can hold the information.
2. Preserve `created_date`; set `last_updated_date` to the actual current date.
3. Extract decisions into a decision record when their rationale or consequences will matter later.
4. Extract owned actions into `tasks.md` or `04_global_tasks_and_planning/master_todo.md` using checkboxes and, when known, `DUE:[YYYY-MM-DD]`.
5. Link the record to its project, sources, related decisions, and output rather than duplicating the same narrative.
6. If priorities or blockers materially changed, update `00_meta/workspace_state.md` concisely.
7. Report changed paths, evidence boundaries, and unresolved questions.

Do not update live state merely because a file was read. State should describe the work, not the agent session.

## Privacy and external actions

- Treat content as private unless `visibility: public` or the user explicitly says otherwise.
- Do not publish, send, upload, or expose files merely because an output looks complete.
- Do not commit credentials, tokens, private keys, raw personal exports, or decrypted vault contents.
- Prefer summaries and source pointers over copying sensitive raw material into additional files.
- Ask before an irreversible migration, broad rename, bulk rewrite, or external action.

## Validation

- Review `git diff --check` and the relevant diff after edits.
- Run focused tests for scripts and `python -m unittest discover -s tests` for the core template.
- Run `archivum doctor` before declaring a structural change complete.
- Never claim a command, link, or integration works unless it was checked.

## Optional skill mode

The portable skill lives at `skills/archivum/SKILL.md`. In skill mode, resolve the target Archivum explicitly from the user's path, `ARCHIVUM_ROOT`, or a workspace containing `config.yaml` and `00_meta/`. Never guess between multiple archives.