Nomenclature unification — Step + Phase / Sub-phase

Source: plans/meta-2026-06-03-nomenclature-reorg.md · synced 2026-06-12

Nomenclature unification — Step + Phase / Sub-phase

Why this exists

The Source of Truth carried five overlapping nomenclatures (9 Steps, Phases A–E, Stages A.1–A.5, Sprints 1a..4, AD1/AD2/AD3). They mapped inconsistently across §2, §4, §5 and §7. Build state was per-step; scope phasing was A–E; timeline mixed all three plus a column for the old sprint names. The result: even the client and the operator could not tell which “phase” a piece of work was in.

This reorg locks two nomenclatures, retires the rest, and aligns every other workspace doc + the docs-site to them.

Decisions locked

1. Two-layer vocabulary

Layer	Use	Range
Step	The unit of work tracked end-to-end. Steps 1–9 are the pipeline a JD goes through at runtime. Steps 10–12 are non-pipeline build tracks.	1–12
Phase / Sub-phase	The build hierarchy inside a step. A step contains phases; a phase may contain sub-phases. Each phase / sub-phase corresponds to one or more plans.	N.M (Phase) · N.M.K (Sub-phase)

AD1 / AD2 / AD3 (the three Annex 3 deliverables) remain as grant-side labels. They are not a build vocabulary — they are deliverable IDs the steps map to.

2. Steps 1–12


Pipeline (1–9) — what each JD goes through at runtime
  Step 1 — JD ingested
  Step 2 — JD parsed
  Step 3 — JD normalised + tagged
  Step 4 — Scraping / ads
  Step 5 — CV parsed + normalised + matched 1:1
  Step 6 — Layer 1 hard-fit filter
  Step 7 — Layer 2 deep assessment
  Step 8 — Shortlist (4 fit groups)
  Step 9 — Personalised outreach

Non-pipeline build tracks (10–12) — what wraps the pipeline
  Step 10 — Productisation surface
  Step 11 — Audit prep
  Step 12 — Infra

3. Per-step phase map (canonical)

Step	Phases
Step 1 — JD ingested	1.1 JD upload + text extraction
Step 2 — JD parsed	2.1 JD parser (Claude tool-use → ParsedJD)
Step 3 — JD normalised	3.1 Tag-vocab bootstrap · 3.2 JD normaliser build
Step 4 — Scraping / ads	4.1 Apify candidate scraping · 4.2 Apollo enrichment · 4.3 Anymail Finder · 4.4 BD employer scraping
Step 5 — CV parsed + matched	5.1 CV parser (✅) · 5.2 CV normaliser · 5.3 LLM inference match · 5.4 Industry-expert filter
Step 6 — Layer 1	6.1 Rubric loader + composite scorer
Step 7 — Layer 2	7.1 Adjacency resolver · 7.2 Evidence-grounded LLM
Step 8 — Shortlist	8.1 Layer 3 verdict synthesis
Step 9 — Outreach	9.1 Personalisation engine · 9.2 Email send · 9.3 LinkedIn sequencing · 9.4 Response handling
Step 10 — Productisation	10.1 Multi-tenant Supabase RLS · 10.2 Marketing landing · 10.3 Signup + onboarding · 10.4 Stripe (test mode) · 10.5 Demo tenants · 10.6 Admin
Step 11 — Audit prep	11.1 Project report (Calibre letterhead) · 11.2 Training materials · 11.3 Recordings + attendance · 11.4 Productivity measurement
Step 12 — Infra	12.1 Docs site · 12.2 Manifest → sync pipeline · 12.3 Dev environment · 12.4 Documentation governance

4. Retired vocabularies

Retired	Replacement
Phase A (underlying logic)	Steps 1–3, 5–8
Phase B (sourcing)	Step 4
Phase C (outreach)	Step 9
Phase D (productisation)	Step 10
Phase E (audit prep)	Step 11
Stage A.1 (CV parser)	Step 5, Phase 5.1
Stage A.2 (vocab bootstrap)	Step 3, Phase 3.1
Stage A.3 (CV normaliser + JD parser + JD normaliser)	Step 3 Phase 3.2 + Step 2 Phase 2.1 + Step 5 Phase 5.2
Stage A.4 (matching engine)	Step 5 Phase 5.3, 5.4 + Step 6 Phase 6.1
Stage A.5 (Layer 2 + 3)	Step 7 + Step 8
Step 3a / 3b	Phase 3.1 / 3.2
Step 5a / 5b	Phase 5.3 / 5.4
Sprint 1a / 1b / 2 / 3 / 4	(no replacement — sprints retired entirely)

5. Plan-file naming convention

Three name patterns:

Pattern	Use	Example
`step-N-phase-M-<name>.md`	A plan that targets one step’s phase. Multiple plans may share the same `step-N-phase-M-` prefix when they cover sub-phases of the same phase.	`step-3-phase-1-vocab-bootstrap-design.md`
`pipeline-<name>.md`	A blueprint covering multiple pipeline steps (e.g. the JD↔CV matching design).	`pipeline-1.1+2.1+3.2+6.1+7.1+7.2+8.1-matching-engine-design.md`
`amendment-<name>.md`	A cross-cutting amendment that ripples through several plans / schemas.	`amendment-3.2+5.2+6.1-taxonomy-3level.md`
`meta-YYYY-MM-DD-<name>.md`	A governance / process plan (this doc is one).	`meta-2026-06-03-nomenclature-reorg.md`

6. Plan-file rename map

Old	New	Status retained
`2026-05-19-cv-parser-schema-design.md`	`step-5-phase-1-cv-parser-design.md`	✅ Shipped
`2026-05-19-cv-parser-implementation.md`	`step-5-phase-1-cv-parser-impl.md`	✅ Shipped
`2026-05-19-title-normaliser-design.md`	`step-5-phase-2-cv-normaliser-design.md`	⚠️ Superseded (schema only)
`2026-05-20-parser-hardening-design.md`	`step-5-phase-1-cv-parser-hardening-design.md`	✅ Shipped
`2026-05-20-parser-hardening-implementation.md`	`step-5-phase-1-cv-parser-hardening-impl.md`	✅ Shipped
`2026-05-23-jd-cv-matching-design.md`	`pipeline-1.1+2.1+3.2+6.1+7.1+7.2+8.1-matching-engine-design.md`	🟡 Active
`2026-05-23-jd-cv-matching-implementation.md`	`pipeline-1.1+2.1+3.2+6.1+7.1+7.2+8.1-matching-engine-impl.md`	🟡 Active
`2026-05-25-step-3a-vocab-bootstrap-design.md`	`step-3-phase-1-vocab-bootstrap-design.md`	📝 Draft
`2026-05-25-step-5b-industry-filter-design.md`	`step-5-phase-4-industry-filter-design.md`	📝 Draft
`2026-05-25-taxonomy-3level-amendment.md`	`amendment-3.2+5.2+6.1-taxonomy-3level.md`	🟢 Approved

Renames done via git mv to preserve history. Original date stays in each plan’s frontmatter date: field.

7. Plan-body preservation rule

The body of each renamed plan is not rewritten. A plan documents the decision as it was made on that date. Rewriting Step 3a → Phase 3.1 inside the body would falsify the audit trail.

Each renamed plan receives a short banner block at the top mapping the old terminology to the new (one-line note). The body stays intact.

Files this reorg touches

Rewritten (current docs):

SOURCE-OF-TRUTH.md — §2 retitled “The 12-Step System”; §4 (scope-phasing) deleted; §5 expanded to 12 steps with phase hierarchy; §7 timeline rewritten as per-step Gantt; sections renumbered.
plans/PLANS-LOG.md — register grouped by Step → Phase.
grant/architecture.md — module diagram refs updated to new step/phase IDs.
grant/audit-trail.md — “Phase D” references → “Step 10”; 9-step references → 12-step where appropriate.
CLAUDE.md — workspace doc references updated where they cite old phases.
STATE-LOG.md — historical entries left intact; current-state references updated.
context/current-data.md — sprint references updated.
outputs/2026-05-25-pipeline-walkthrough.md — phase references updated.

Renamed (body preserved):

All 10 plan files per §6 rename map.

Regenerated (no manual edits):

All of docs-site/content/ — regenerated by scripts/sync-docs-site.py.

Tooling updated:

scripts/sync-docs-site.py — SOT_SECTION_PAGES keys + methodology_meta slugs renamed:
- 2 → 12-step-system (was 9-step-pipeline)
- 4 key removed (was scope-phasing)
- 5 → build-state (numbering shift — was key 5, becomes key 4)
- 7 → timeline (numbering shift — was key 7, becomes key 6)

Out of scope this session

Splitting pipeline-1.1+2.1+3.2+6.1+7.1+7.2+8.1-matching-engine-design.md and pipeline-1.1+2.1+3.2+6.1+7.1+7.2+8.1-matching-engine-impl.md into per-step plans. The two blueprints retain their integration view; per-phase plans can be carved out later if needed.
Producing missing plans for Step 4, Step 9, Step 10, Step 11. These are flagged in PLANS-LOG as 🔴 No plan and addressed when their phases open.

Verification

python scripts/inventory-site-manifest.py returns zero unclassified files.
python scripts/sync-docs-site.py writes docs-site/content/methodology/12-step-system.md and removes 9-step-pipeline.md + scope-phasing.md.
Browser check: docs-site Methodology tab shows the four pages (12-Step System, Taxonomy, Build State, Timeline) in that order.
git log --follow on at least one renamed plan returns the pre-rename history.