Add repo docs for agent guidance

AGENTS.md

@@ -18,89 +18,107 @@ This file gives general operating guidance for coding agents working in this rep
 - Check whether there are existing tests, scripts, or conventions to follow.
 - Do not assume missing context; infer from the codebase first.
 
+## Repo State Preflight
+
+- Before starting work, inspect `git status --short`.
+- Treat pre-existing dirty files as user-owned by default.
+- Do not include pre-existing user edits in agent commits unless explicitly approved.
+- If requested work overlaps with user-owned uncommitted files, pause and ask how to proceed.
+- Encourage the user to commit or stash their work before continuing when appropriate.
+
 ## Implementation Guidance
 
 - Match the style and structure already used in the repository.
-- Avoid broad refactors unless they are necessary to complete the task.
+- Avoid broad refactors unless necessary to complete the task.
 - Add comments only where intent would otherwise be unclear.
-- Prefer explicit, boring code over abstractions introduced too early.
+- Prefer explicit, simple code over premature abstraction.
 - Keep public APIs, file layouts, and naming stable unless the task calls for a change.
 
 ## Testing Expectations
 
 - Create or update tests for every non-trivial behavior change.
-- Prefer tests that prove the user-visible or contract-level behavior, not just implementation details.
-- Run relevant tests frequently while working, not only at the end.
-- After each meaningful code change, run the smallest test scope that gives fast feedback.
-- Before finishing, run the most relevant broader verification available for the touched area.
-- If a change is not practical to test automatically, state that clearly and explain the gap.
+- Prefer tests that prove user-visible or contract-level behavior.
+- Run relevant tests frequently while working.
+- After each meaningful change, run the smallest test scope that gives fast feedback.
+- Before finishing, run broader verification for the touched area.
+- If a change cannot be tested automatically, state that clearly.
 
 ## Safety Rules
 
 - Never overwrite or revert user changes unless explicitly asked.
-- Avoid destructive commands unless the user clearly requested them.
+- Avoid destructive commands unless clearly requested.
 - Call out assumptions when they materially affect behavior.
-- If you find unrelated problems, note them separately rather than folding them into the same change.
+- If you find unrelated problems, note them separately.
 
 ## Verification
 
-- Run the smallest relevant verification available after making changes.
+- Run the smallest relevant verification after making changes.
 - If tests or checks cannot be run, say so explicitly.
-- When possible, verify both the happy path and the most likely failure path.
+- Verify both the happy path and the most likely failure path when possible.
+
+## Documentation
+
+- Re-read `AGENTS.md`, `PLAN.md`, and relevant files in `docs/` before planning or implementing.
+- Update `docs/` when behavior, structure, or standards change.
+- Update `PLAN.md` when work is completed, deferred, or split into follow-up work.
+- Do not consider work complete until code and docs are aligned.
 
 ## Commit Discipline
 
-- Commit work in logical, reviewable increments rather than as one large batch.
-- Prefer a commit after each completed unit of work that passes relevant verification.
+- Commit work in logical, reviewable increments.
+- Prefer a commit after each completed unit of work that passes verification.
 - Keep commits focused; avoid mixing unrelated changes.
-- Use clear commit messages that describe the behavior or intent of the change.
-- Do not commit broken work unless the user explicitly asks for a checkpoint commit.
+- Use clear commit messages describing behavior or intent.
+- Do not commit broken work unless explicitly requested.
 
 ## Branch Discipline
 
-- Do new feature work on a dedicated branch rather than directly on the main line.
-- Use a distinct branch for each feature, fix, or clearly scoped task.
-- Do not mix unrelated work on the same branch.
-- Start new work from `dev` unless the user specifies otherwise.
-- Keep branch names descriptive and scoped to the task.
-- Before switching branches, check for uncommitted work and avoid carrying unrelated changes forward.
-- If the current branch is not appropriate for the requested task, create or switch to a better-scoped branch before editing code.
-- Merge completed feature branches into `dev` after relevant verification passes.
+- Do new feature work on a dedicated branch.
+- Use a distinct branch per feature, fix, or scoped task.
+- Start new work from `dev` unless specified otherwise.
+- Keep branch names descriptive and scoped.
+- Do not carry unrelated uncommitted changes across branches.
+- Merge completed feature branches into `dev` after verification.
 - Reserve `main` for release-ready code.
 
-## AI Metadata Branch
+## AI Metadata
 
-- Keep AI coordination files on a dedicated `ai` branch unless the user specifies otherwise.
-- Treat files such as `AGENTS.md`, `PLAN.md`, task notes, and other agent-only working documents as AI metadata rather than product code.
+- Keep purely agent-only working notes on the `ai` branch unless specified otherwise.
 - Do not mix AI metadata commits with application feature commits.
-- When updating AI metadata, switch to `ai` before editing or committing those files.
-- Keep the `ai` branch distinct from `dev` and `main` unless the user explicitly wants those files promoted.
+- If a file is required for active repo guidance, keep it in the working branch.
 
 ## Agent Identity
 
-- Use a dedicated Git author identity for AI-created commits instead of the user's personal identity.
-- Set the Git author name for agent work to `Codex`.
-- Set the Git author email for agent work to `codex@local`.
-- Prefer per-commit identity flags such as `git -c user.name="Codex" -c user.email="codex@local" commit ...` instead of changing Git configuration.
-- If explicit author metadata is needed, use `--author="Codex <codex@local>"`.
-- Do not change the user's global Git identity for agent work.
-- Do not rely on inherited global Git identity for AI-authored commits.
+- Use a dedicated Git author identity for AI-created commits.
+- Default agent identity:
+  - Name: `Codex`
+  - Email: `codex@local`
+- Prefer per-commit identity flags:
+  - `git -c user.name="Codex" -c user.email="codex@local" commit ...`
+- Do not change the user's global Git identity.
+
+## Commit Ownership
+
+- The user and agents use separate Git identities.
+- Only agent-authored changes should be included in agent commits.
+- Do not include pre-existing user edits in agent commits unless explicitly approved.
+- If overlap exists, pause and ask before proceeding.
 
 ## Release And Versioning
 
-- Treat `dev` as the active integration branch for ongoing work.
-- Merge `dev` into `main` only when preparing a release.
-- Bump the project version only as part of release preparation unless the user asks otherwise.
-- Keep version changes in a dedicated release commit or tightly grouped release branch work.
-- Tag releases from `main` when the repository adopts a release process.
+- Treat `dev` as the active integration branch.
+- Merge `dev` into `main` only for releases.
+- Bump versions only during release preparation unless instructed otherwise.
+- Keep version changes grouped into release commits.
+- Tag releases from `main` when applicable.
 
 ## Communication
 
 - Be concise and concrete.
-- Summarize what changed, why it changed, and how it was verified.
-- Surface risks, tradeoffs, and follow-up work plainly.
+- Summarize what changed, why, and how it was verified.
+- Surface risks, tradeoffs, and follow-up work clearly.
 
 ## Scope
 
 - This file is intentionally general.
-- Add stack-specific or workflow-specific guidance here as the repository grows.
+- Add stack-specific or workflow-specific guidance as the repository grows.