V2 Folder Governance

Canonical policy for publishable versus non-publishable folder lanes in v2, legacy workspace retirement, and cleanup planning.

V2 Folder Governance

This document is the canonical governance policy for v2/ folder structure.

It defines which v2/ paths are publishable docs, where maintainer-only working material must live, and how legacy workspace buckets are reviewed and retired.

Canonical Target Model

Lane	Canonical path	Purpose
Publishable section root	v2/<section>/index.mdx, portal.mdx, navigator.mdx	Section entry points intended for docs routing and live preview.
Publishable content tree	v2/<section>/<publishable-subtree>/...	User-facing docs pages such as concepts, guides, references, resources, setup, or equivalent section IA.
Active non-publishable working lane	v2/<section>/_workspace/	Maintainer-only plans, research, reviews, handoff notes, and draft prototypes that must not behave like docs pages.
Section-local retirement lane	v2/<section>/x-deprecated/	Previously publishable pages pending redirect, migration, or removal.
Global frozen archive lane	v2/x-archived/<section>/	Frozen historical material retained for reference only.

Section-Root Contract

Allowed publishable section-root files are:

• index.mdx
• portal.mdx
• navigator.mdx

Section roots must not accumulate ad hoc planning notes, reports, or review files beside publishable pages. If material is not meant to route or preview as docs content, it belongs in _workspace/, x-deprecated/, or v2/x-archived/.

_workspace/ Contract

_workspace/ is the only approved active non-publishable working folder under v2/<section>/.

Approved subfolders:

Subfolder	Use
notes/	Loose planning notes, todo files, and ad hoc reference material.
plans/	Active restructuring plans, execution plans, migration matrices, and implementation notes.
research/	Research notes, evidence packs, claim inventories, and working references.
research/sources/	Source bundles, imported references, verification snapshots, and supporting evidence files.
reviews/	Review notes, critique passes, and cleanup recommendations.
drafts/	Page-shaped prototypes not yet promoted into the publishable tree.
handoff/	Product, stakeholder, or authoring handoff material.
context-data/	Contextual data files imported from external tools or prior migrations (e.g. renamed from _contextData_/).
staging/	Content under active evaluation before promotion or deletion (e.g. renamed from _move_me/).
archive/	Retired pages and reference material no longer actively maintained. 90-day TTL.
deprecated/	Previously publishable pages pending redirect, migration, or removal.

Naming rules inside _workspace/:

• Use plain kebab-case directory names (e.g. context-data/, not _contextData_/)
• Legacy names (_archive/, _contextData/, _contextData_/, _move_me/, x-archived/, x-deprecated/) must not be introduced again; existing instances are migrated through approved rename waves
• Loose files directly inside _workspace/ (not in a subfolder) are acceptable only as temporary scratch; they should be moved into the appropriate subfolder within 30 days

File-Type Rules

• Publishable pages are .mdx.
• Workspace notes, reports, and review artifacts are .md by default.
• _workspace/drafts/ may contain .mdx when a page-shaped prototype is intentionally non-routable during development.

Routing and Linking Rules

The canonical publishability contract is:

1. docs.json must never point to _workspace/**, x-deprecated/**, or v2/x-archived/**.
2. Publishable pages must not import from or link to non-publishable lanes except explicit maintainer-only references that are excluded from Mint/runtime.
3. portal.mdx and navigator.mdx are publishable section entry points, not workspace files.
4. .mintignore, file-selection helpers, and audits enforce this contract, but they are not the canonical source of truth by themselves.

Legacy Naming Retirement Rules

The following legacy workspace patterns are inventory-only and must not be introduced again after this policy lands:

• _contextData
• _contextData_
• _context_data_
• _plans-and-research
• section-level review.md
• x-resources
• TO-ADD
• _archive
• any other ad hoc planning or research bucket inside publishable trees

Existing legacy folders are cleaned through review and approved move waves, not by silent suppression or one-off exceptions.

Transition and Cleanup Workflow

This policy starts with documentation plus a recommendation-only cleanup matrix. No v2/ files move until a human reviews the recommendations.

Generator:

node operations/scripts/generators/governance/reports/generate-v2-folder-governance-cleanup-matrix.js --as-of 2026-03-16

Generated artifacts:

• workspace/reports/repo-ops/v2-folder-governance-cleanup-matrix.md
• workspace/reports/repo-ops/v2-folder-governance-cleanup-matrix.json

The matrix inventories current v2/ legacy workspace buckets, stray .md files, deprecated/archive folders, and similar non-publishable material. Locale trees are governed now but default to later move-wave review unless a human explicitly promotes them.

i18n Trees

v2/cn/, v2/es/, v2/fr/ are translation mirror trees governed separately from the standard content section rules.

• i18n trees do not have _workspace/ directories. Do not create them.
• i18n content is not subject to standard _workspace/ normalisation passes.
• Stale or incomplete translations follow the same deprecation path as their English counterparts, governed by the English page lifecycle.
• These trees are not touched by standard workspace governance unless a specific i18n migration is explicitly approved.

Follow-on Workstreams

Workstream A: Enforcement and Selection Updates

• Update .mintignore to exclude the canonical non-publishable lanes.
• Add transitional ignore coverage for current legacy names such as _contextData.
• Update shared file-selection helpers and generators that still treat workspace artifacts as normal v2 docs content.
• Ensure docs navigation checks fail when a routed page resolves into an ignored or non-publishable lane.
• Ensure scoped Mint generation inherits the same ignore contract.

Workstream B: Approved Moves

• Execute only the file moves approved in the cleanup matrix.
• Normalize section trees to the _workspace, x-deprecated, and v2/x-archived contract.
• Retire legacy workspace folder names after their contents have been moved.
• Regenerate affected indexes or catalogs and rerun validators after each approved move wave.