Step-only nomenclature — retire the word “phase”
Source: plans/meta-2026-06-11-step-only-nomenclature.md · synced 2026-06-12
Step-only nomenclature — retire the word “phase”
What changed (2026-06-11)
The 2026-06-03 reorg (meta-2026-06-03-nomenclature-reorg.md) collapsed five vocabularies into two: Step + Phase / Sub-phase. That was the right direction but Ben confirmed in conversation 2026-06-11 that even “Phase” felt redundant — the decimal-numbered IDs (5.1, 5.1.1, etc.) already carry the hierarchy, and saying “Step 5 Phase 1” + “Phase 5.1” + “step-5-phase-1-cv-parser-design.md” was tripled bookkeeping for the same concept.
Locked: the only build vocabulary now is Step (decimal-numbered). The word “phase” is retired.
The new convention — Step (decimal-numbered)
- Step 1, Step 2, …, Step 12 — top-level steps.
- Step 5.1, Step 5.2, … — sub-step, single decimal level.
- Step 5.1.1, Step 5.1.2, … — sub-sub-step, used when a single step has distinct phases of work (e.g. core build vs hardening) that warrant separate plan files but stay logically grouped under the parent.
Plan files follow step-N.M[.K]-<descriptive-name>-<design|impl>.md. Examples:
step-3.1-vocab-bootstrap-design.mdstep-5.1.1-cv-parser-design.md(core build)step-5.1.2-cv-parser-hardening-design.md(continuation work, distinct branch)step-5.4-industry-filter-design.md
The other three prefixes — pipeline-, amendment-, meta- — are unchanged.
What was renamed 2026-06-11
| Old filename | New filename | Reason |
|---|---|---|
step-3-phase-1-vocab-bootstrap-design.md | step-3.1-vocab-bootstrap-design.md | Drop “-phase-” infix |
step-3-phase-1-vocab-bootstrap-impl.md | step-3.1-vocab-bootstrap-impl.md | Same |
step-5-phase-1-cv-parser-design.md | step-5.1.1-cv-parser-design.md | Drop infix + introduce sub-step 5.1.1 for parser core |
step-5-phase-1-cv-parser-impl.md | step-5.1.1-cv-parser-impl.md | Same |
step-5-phase-1-cv-parser-hardening-design.md | step-5.1.2-cv-parser-hardening-design.md | Drop infix + introduce sub-step 5.1.2 for hardening |
step-5-phase-1-cv-parser-hardening-impl.md | step-5.1.2-cv-parser-hardening-impl.md | Same |
step-5-phase-4-industry-filter-design.md | step-5.4-industry-filter-design.md | Drop infix |
7 file renames. All cross-references updated in: SOT §2 / §4 / §6 / §7, CLAUDE.md, PLANS-LOG.md, outputs/engine-map-2026-06-11.html, _internal/engine-map-audit-2026-06-11.md, grant/scope.md, context/current-data.md, and every active plan file’s body.
What was NOT touched
_archive/**— historical, never edited.plans/meta-2026-06-03-nomenclature-reorg.md— historical mapping doc; its “Phase A → Step 4” content is preserved verbatim because it documents what the old vocabularies meant.STATE-LOG.mdpast entries — append-only.- The literal word “phase” where it appears as generic English (e.g. “phase out”, “the next phase of work” colloquially) — only the noun “Phase” used as a build-system unit was replaced.
Vocabulary swap reference
| Old | New |
|---|---|
| ”Phase 5.1” / “Phase 5.4” (as a build unit) | “Step 5.1” / “Step 5.4" |
| "Sub-phase" | "Sub-step" |
| "Step + Phase / Sub-phase" | "Step (decimal-numbered)“ |
Filename step-N-phase-M- | Filename step-N.M- (or step-N.M.K- for sub-step) |
Commit prefix feat(step-3-phase-1): | Commit prefix feat(step-3.1): |
Discipline going forward
- In conversation: say “Step 5.1,” “Step 5.1.1.” Never “Phase 5.1.”
- In commit messages:
feat(step-3.1): …,fix(step-5.1.2): …. Notstep-3-phase-1. - In new plan files: filename pattern
step-N.M[.K]-<name>-<design|impl>.md. Sub-step (.K) only when distinct work-units justify it. - When in doubt about an existing Phase reference: check this doc + meta-2026-06-03-nomenclature-reorg.md. If it’s a live ref, update it. If it’s audit-trail historical content, leave it.
Why this matters
Ben’s framing: “I want to be able to see at a glance what the file is about from the name.” The old step-5-phase-1-cv-parser-design.md had two layers of redundancy:
- “step-5-phase-1” is just
5.1with extra words. - “phase” implies sub-step but never specifies sub-sub-step (no place for the hardening distinction).
The new step-5.1.1-cv-parser-design.md is shorter, encodes the hierarchy in the number, and leaves room for sub-step splits where the work genuinely diverges.