diff --git a/codex/agents.md b/codex/agents.md index 65213d82c8..af77fc658d 100644 --- a/codex/agents.md +++ b/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: diff --git a/codex/docs/INDEX.md b/codex/docs/INDEX.md new file mode 100644 index 0000000000..37b5aedf23 --- /dev/null +++ b/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. diff --git a/codex/docs/README.md b/codex/docs/README.md new file mode 100644 index 0000000000..bc5585052f --- /dev/null +++ b/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 `-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.