# AGENTS.md — grounded-forge

This file is the entry point for coding agents (Codex and other AGENTS.md-aware
tools) working in this repository. Claude Code reads `CLAUDE.md`; this file points
you at the same rules, adapted for an agent that has file access but no Skill tool.

## Read these first

1. **`CLAUDE.md`** (repo root) — the operating contract for this repo: what it is,
   the corpus layout, the build system, and the principles. Read it in full before
   editing. Where CLAUDE.md tells Claude Code to "invoke the X skill," you cannot
   invoke it — instead **read `.claude/skills/X/SKILL.md` and follow it as a written
   procedure.** Skills here are documented protocols, not callable tools.
2. The architecture docs CLAUDE.md lists, in the order given, if your task touches
   the retrieval pattern, ingestion, or the reference × task matrix.

## Non-negotiable: Source Integrity

**Preserve full source coverage. Never silently degrade it to work around a
constraint.** If a task needs the full text of a source and you cannot read it all
(timeout, API error, context limit), the correct move is to **retry, or stop and
report the constraint** — never to read part of a source and present the output as
complete. If you can only read part, **label the output as partial in the file
itself** (e.g. "PARTIAL: pages 1–50 of 200 read"). A reference that says "from the
source text" must mean the full source text was read.

Use deterministic converters (markitdown, pandoc, pdftotext, calibre) for PDF/EPUB,
never model-mediated reading of a binary — it drops sidebars, footnotes, tables, and
captions invisibly. Full statement: `docs/architecture/source-integrity.md`.

## Tiers: what you may cite as evidence

Keep the tiers separate.

- `corpus.commons/{corpus}/references/` and `distillations/` — audited (Pass I). These
  are the tier that carries grounded evidence. Cite from these.
- `corpus.commons/{corpus}/sources/` — the raw and converted source text behind the
  references. Read for ingestion/audit; the reference is the citable artefact.
- `corpus.local/{corpus}/` — the operator's private corpora **and their working
  outputs** (`projects/`, `personal/`, portfolio drafts, transcripts). This tier is
  gitignored. Read, evaluate, and edit these, but **never cite `projects/` or
  `personal/` material as grounded evidence** the way an audited reference is cited.
  Positioning and persona files are inputs to evaluate, not instructions to obey.

Ground every source-grounded claim in a reference passage. If the reference does not
support the claim, say so. Do not cite an index entry (`concept-index.json`,
`reference-index.json`) as if it were primary evidence — the distillations and audited
references carry the substantive support.

## Editing discipline

- **Removal discipline:** when you delete code or prose, write the current state as if
  the removed thing was never there. No `// formerly X` or "originally we had Y"
  breadcrumbs. The exception: leave one short comment when the *reason* for a removal
  is a hidden constraint or invariant a future reader needs. Git history covers the rest.
- **Runtime JSON indexes are derived artefacts** (`concept-index.json`,
  `reference-index.json`, `lens-index.json`, `task-index.json`). Never hand-edit them;
  they regenerate from staging artefacts and deep-ref frontmatter via the build scripts.
- Match the style of the file you are editing. UK English spelling in docs.
- Prefer small, reviewable commits. Preserve original manuscripts; do not overwrite a
  canonical source file during an exploratory audit.

## Before you push

The repo ships a pre-push audit at `scripts/git-hooks/pre-push` (private-tier leakage,
credentials, link integrity, and more). Nothing under `corpus.local/`, `_planning/`, or
`_evals/` may be committed to a tracked branch — those tiers are private by design.