> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Doc Maintenance

> This runbook keeps AGENTS.md and nested AGENTS files high-signal and low-noise.

This runbook keeps `AGENTS.md` and nested AGENTS files high-signal and low-noise.

## Goals

* keep always-loaded agent context concise
* avoid duplication across `constitution.md`, `AI_GUIDE.md`, and `AGENTS.md`
* preserve non-discoverable "landmine" guidance
* detect stale instructions before they mislead agents

## Canonical Responsibilities

* `constitution.md`: normative guardrails and policy
* `AI_GUIDE.md`: implementation process and spec workflow
* `AGENTS.md`: quick reference, routing, and canonical "What AI Must NEVER Do"
* nested `src/**/AGENTS.md`: module-scoped constraints and routing

## Landmine Date Markers

When adding a non-discoverable gotcha, include `[YYYY-MM]`.

Example:

```md theme={null}
- [2026-05] First typecheck run can take 5-7 minutes while tsc cache warms.
```

## Staleness Audit

Run periodically (full scan of the default high-traffic agent docs):

```bash theme={null}
npm run audit:agent-doc-staleness
```

Fail CI/governance on stale markers:

```bash theme={null}
npm run audit:agent-doc-staleness:strict
```

The strict check flags `[YYYY-MM]` markers older than 90 days.

### Changed-file scoping (PRs)

The default run scans a fixed list of high-traffic agent docs. To scope to only
the agent docs a PR changed — so any core's `AGENTS.md` is covered, not just the
default three — pass `--since=<ref>` and/or explicit paths:

```bash theme={null}
# Only agent docs changed since the base branch
npm run audit:agent-doc-staleness -- --since=origin/development

# Explicit paths (non-agent-doc paths are ignored)
npm run audit:agent-doc-staleness -- src/cores/fa/AGENTS.md
```

The PR step in `docs-coverage.yml` runs `--since=origin/<base_ref>` (warn-only
during burn-in). "Agent doc" means any `AGENTS.md` (root or nested), `AI_GUIDE.md`,
or `constitution.md`/`.mdc`; other changed paths in the diff are skipped.

## Maintenance Cadence

* monthly:
  * run staleness audit
  * prune duplicated/discoverable instructions
  * verify links and command references
* quarterly:
  * run `agents-memory-updater` maintenance pass in Cursor
  * review high-churn module AGENTS files for size and relevance

## `agents-memory-updater` Workflow

Suggested prompt:

```text theme={null}
Audit AGENTS.md + nested AGENTS files for stale instructions, duplicate guidance, and missing landmines.
Return:
1) stale/incorrect lines with file paths,
2) concrete patch suggestions,
3) a prioritized update list.
```

Apply suggested edits only after human review.