EvoCoder – Add /codex/docs with usage guidance for code audits and stored artifac

codex/agents.md

@@ -15,6 +15,7 @@ The `/codex` directory centralises planning artefacts so work can be tracked and
 - `/codex/STATE.md`: Master board of tickets, tracked as a Markdown table. Every ticket ID listed here must have a matching file in `codex/tickets/`.
 - `/codex/tickets/`: Canonical ticket records with context, plan, acceptance checks, PR links, and chronological log entries.
 - `/codex/plans/`: Time-boxed planning documents (for example, sprint briefs) that roll tickets into broader initiatives and demos.
+- `/codex/docs/`: Evergreen documentation (audits, incident reviews, architecture narratives) that must remain accessible after the related tickets close. See `codex/docs/README.md` for naming, metadata, and security conventions.
 
 > Tip: Avoid editing tickets marked **Done**—append follow-up work as a new ticket to keep historical artefacts immutable.
 
@@ -51,6 +52,24 @@ Planning files in `codex/plans/` should:
 - Document the planning window, goals, committed tickets, stretch objectives, demo notes, and retro actions.
 - Link back to ticket IDs and keep status snapshots so stakeholders can see progression across the time box.
 
+## Documentation Archive
+
+Use `codex/docs/` for artefacts that need to persist beyond the lifecycle of a single ticket:
+
+- Preserve code audits, compliance reviews, or security assessments requiring long-term traceability.
+- Log architecture or design decisions that inform multiple tickets or future initiatives.
+- Record incident and postmortem summaries, including follow-up owners and due dates.
+- Share durable runbooks, operational checklists, or process guides that should stay versioned alongside the board.
+
+Follow the `codex/docs/README.md` guidance when drafting or updating documentation:
+
+- Add the required YAML front matter (title, date, owner, review cadence, status, related links, and optional audience or superseded references).
+- Scrub secrets, credentials, and personal data; if redaction is impossible, store the sensitive source in the approved secure location and link to it with access notes.
+- Capture retention or access constraints up front (for example, `internal-only`, `retain 12 months`).
+- Close each document with a **Backlinks** section that lists the tickets, plans, and PRs that reference the artefact.
+
+Name documents with a chronological prefix (for example, `2025-03-18-platform-audit.md`) and link them from related tickets, plans, or READMEs so reviewers can trace the supporting context quickly. Maintain an index in `codex/docs/INDEX.md` when the archive expands to help contributors discover key references.
+
 ## Codex Agent Contract
 
 Codex agents working in this repository must:

codex/docs/INDEX.md

@@ -0,0 +1,15 @@
+# Codex Docs Index
+
+Use this catalogue to keep long-lived documentation easy to discover. Group entries by year (preferred) or topic, and link directly to the underlying Markdown artefacts.
+
+## 2025
+
+- _No archived documents yet. Add entries in the format `YYYY-MM-DD – Title (owner)` pointing to the corresponding file._
+
+---
+
+### How to Update
+
+- Add a new section when a year or topic gains documents.
+- Keep the list sorted chronologically within each section.
+- Link related tickets and PRs inline so reviewers can understand why the document exists.

codex/docs/README.md

@@ -0,0 +1,43 @@
+# Codex Documentation Archive
+
+This folder stores long-lived documentation that supplements the ticket board without depending on an active ticket. Use it for artefacts that must remain discoverable after day-to-day execution wraps up.
+
+## When to Add Documents
+
+- Code audits that capture review scope, findings, and remediation follow-up.
+- Architecture or design narratives that influence multiple tickets or future initiatives.
+- Incident, postmortem, or compliance reports that require durable retention.
+- Runbooks, checklists, and operational guides that should persist beyond a single sprint.
+- Security-sensitive write-ups that need long-term traceability—ensure they are scrubbed of secrets, credentials, tokens, or other production keys.
+- Any artefact containing regulated or personal data must be anonymised or redacted; when redaction is not possible, stash the source in the approved confidential store and link to it with access notes.
+- If a document has audience or retention constraints, call them out explicitly (for example, `internal-only`, `retain 12 months`).
+
+## Authoring Guidelines
+
+- Name files `<YYYY-MM-DD>-short-topic.md` so they sort chronologically.
+- Start with a one-paragraph summary and link any related tickets or pull requests.
+- Note owners and review cadence where relevant so stakeholders know how to keep the document current.
+- Update documents in place; if a document is superseded, link to the replacement instead of deleting history.
+- Add YAML front matter at the top of every file to align ownership and lifecycle metadata:
+
+```yaml
+---
+title: Short Topic
+date: YYYY-MM-DD
+owner: @github-handle
+review_cadence: quarterly
+status: active # active | superseded | deprecated
+related:
+  tickets: [T-123, T-456]
+  prs: [https://github.com/org/repo/pull/1234]
+superseded_by: 2025-07-01-new-guidance.md # optional
+audience: internal-only # optional
+---
+```
+
+## Cross-Referencing
+
+- Reference these documents from the relevant tickets, plans, or README sections.
+- Record material decisions or commitments inside the associated ticket log so timelines stay auditable.
+- Include a **Backlinks** section at the end of each document listing the related tickets, PRs, or plans so reviewers can traverse context quickly.
+- Keep an `INDEX.md` in this directory (grouped by year or topic) when the archive grows; the index should point to the most important or frequently referenced documents.