Story: Doc format cleanup: migrate v1 docs and remove v2 branding
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Eliminate all "v2" branding from the document toolchain and the doc graph.
This means: (1) auditing which non-sprint documents still lack current-format
frontmatter and migrating the active ones; (2) renaming the codegen script,
Python module, and every Mustache template so none carries the v2_ prefix;
(3) updating or retiring every recipe, memory, and runbook that still
references the old names. After this story the word "v2" should not appear
in script names, template names, or doc titles — the current format is just
the format.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | All 5 tasks complete. v2 branding fully removed. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-05-29 |
Acceptance
- No file under
projects/ores.codegen/hasv2in its name. - No Mustache template filename begins with
v2_doc_. doc/recipes/codegen/how_do_i_create_a_new_v2_doc.orgis renamed (nov2in filename or title).doc/llm/memory/use_codegen_for_v2_docs.orgis updated/renamed.doc/llm/runbooks/port_v1_doc_to_v2/is retired or removed.- Active non-historical docs that lacked
#+version:now carry current frontmatter. - Historical sprint 01–17 story/task docs are explicitly out of scope.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Audit documents lacking v2 frontmatter | DONE | 2026-05-28 | 2026-05-29 | Categorise: historical (leave), active (migrate), obsolete (delete). |
| Migrate active v1 docs to current format | DONE | 2026-05-28 | 2026-05-29 | Add frontmatter to plans, skill docs, active index files. |
| Rename v2-branded codegen scripts and templates | DONE | 2026-05-28 | 2026-05-29 | Rename generate_v2_doc.sh, v2_doc_generate.py, all templates. |
| Remove v2 terminology from documentation | DONE | 2026-05-29 | 2026-05-29 | Rename recipe, update memory, retire port_v1_doc_to_v2 runbook. |
| Drop #+version field from all org files | DONE | 2026-05-29 | 2026-05-29 | Remove #+version: 2 from ~1840 files, templates, and audit script. |
Decisions
- Sprint 01–17 story/task docs already carry
#+version: 2— the earlier "54 missing" count was a BRE regex bug (^#\+version:matches#version:, not#+version:). No migration needed. - Backlog captures (
product_backlog/deferred/,next/,inbox/) are out of scope for frontmatter migration — they are ephemeral and will be replaced when promoted. - Task ordering: audit → migrate → rename codegen → update docs. Rename and doc-update can overlap once audit is done.
Out of scope
- Sprint 01–17 story/task files (~1400 historical records).
- Backlog capture files (~331 files in deferred/next/inbox).
- The
#+version:field value itself — handled in task 5 (drop_version_field) as a separate, focused PR due to the ~1840 file scope.