20260913-2344-documentation-standard Define the documentation standard and target directory structure

status: completed
createdAt: 2026-09-13 23:44
approvedAt: 2026-09-14 01:30
relatedTask: 20260913-2341-documentation-standard

Context

The repository is a documentation package for a marine power-distribution product company: business and product governance, per-product specifications, research, vendor catalogues, evidence archives, and PMA project records, published as a VitePress site on Cloudflare Workers. It holds 189 Markdown pages under bizplan/ and docs/, 19 PDFs, 21 CSVs, two Python scripts, two SVG diagrams with JSON sources, and one unpublished vendor-manual folder. Every area has a reachable index.md with breadcrumbs, and the 2026-09-10 organisation pass already fixed the reading routes and dead links. What remains is structural: the package grew by accretion and carries several parallel conventions.

Findings, by area:

Filename casing. Four schemes coexist: bizplan/BUSINESS-PLAN.md (upper-case), bizplan/product/core/P01-core-design.md (ID prefix plus kebab), bizplan/research/04a-czone-product-matrix.md (number prefix plus kebab) next to bizplan/research/pdm-industry-landscape.md (bare kebab), and docs/architecture.md (kebab).
Research numbering. The 01–11 series has gaps (09, 10), a duplicate 08 on two different reports, and letter suffixes (04a–04e, 06a, 06b) that encode a parent-child relation the directory does not show. Fourteen later reports are unnumbered. Whether a report is the current proposal, supporting evidence, or a superseded alternative is expressed only in research/index.md and in hand-written notices in the first paragraph; nothing on the page is machine-readable.
Vendor catalogues. Two layouts serve the same document type: research/vendors/ is a flat directory of 57 PDM records, while research/air-key-vendors/{gateway,switch,keypad}/ is nested by category. Both use the same six-section template. The Air/Key landscape report sits at the research root, one level above its catalogue.
Product headers. Thirty-three product documents use three header conventions. The 2026-08 hardware set opens with 治理摘要 / 生命周期状态 / 设计附录 / 最后更新; the 2026-09-10 Air/Key set opens with 版本 R0.x / 治理摘要 / 总交付要求 / 设计附录 and has no update date or lifecycle field; P09 opens with 版本 / 依据 / 状态. Status values are written six ways (规格草案 *(t)*, spec-draft *(t)*, 草案 *(t)*, draft *(t)*, concept, 概念 *(t)*) and mix half-width and full-width punctuation.
Product document kinds. Directory index tables label document types ad hoc (产品入口, 供应商交付 · Air, Level 2 · Air, Level 1). Beyond spec and design appendix, the package already contains supplier guides, platform-option comparisons, a device evaluation, a commissioning package, a reference board, a data model, an integration spec, an application architecture, a protocol evaluation, and a customer-facing note. None of these kinds is defined anywhere, so each new document invents its own header and label.
Frontmatter. Only the 22 directory index pages carry YAML frontmatter, and only a title. Status, version, update date, and supersession live in prose lists that cannot be validated.
Governance self-references. PRODUCT-PLAN.md, ASSUMPTIONS.md, and OPEN-QUESTIONS.md still say an English counterpart exists under the same filename; only BUSINESS-PLAN.en.md exists.
Project records. docs/task/ and docs/plan/ mix the canonical <timestamp>-<slug> IDs with four legacy records: REPO-001 (pending since 2026-08-23, unassigned), RESEARCH-008 and PLAN-024 (pending and draft since 2026-08-26, owner /root), and yacht-circuit-evidence-20260907T1402Z (in progress since 2026-09-07, owner marine-research/session-20260907, whose deliverables are already published under research/). The task index has irregular blank lines between entries. docs/decisions/ is referenced by AGENTS.md and docs/index.md but does not exist. The changelog is a single 714-line file with 134 entries and three tags in use ([progress], [decision], [BUG-P1]).
Repository root. s7-200g2/ holds two Siemens PDFs unrelated to any published page and is excluded from the build; tmp/ exists untracked. .gitignore ignores bsp-control/, which is not in the tree.
Tooling that already exists and should be reused. .vitepress/config.mts builds the breadcrumb map from directory index.md titles, copies non-Markdown assets under 25 MiB, and treats a dead link as a build failure unless the target exists on disk. Breadcrumb.vue shows the theme can render page metadata. The quality gate is git diff --check plus bun run docs:build.
Constraints. Clean URLs such as /bizplan/product/core/P01-core are published; PMA requires English filenames and forbids renaming existing tracking IDs unless requested; bizplan/ content is Chinese and docs/ is English by recorded decision; task 20260914-0010, plans 20260910-0717, 20260913-0331, and 20260913-2340 belong to other sessions and must not be touched by a migration.

Proposal

The standard is one English document, docs/documentation-standard.md, referenced from AGENTS.md, docs/architecture.md, and the Chinese area indexes. It has nine parts, summarised here in full so it can be written without further design. The target directory structure is part 4. Migration is part 9 and is split into five phases, each a separate task.

1. Document areas and kinds

Every page belongs to exactly one area and one kind. The kind is declared in frontmatter and shown in the directory index table.

Area	Directory	Language	Kinds allowed
Governance	`bizplan/governance/`	zh, `.en.md` variants	`governance`, `guide`
Product packages	`bizplan/product/<line>/`	zh	`spec`, `design`, `guide`, `brief`, `evaluation`, `foundation`
Research	`bizplan/research/{market,industry,engineering}/`	zh	`report`, `proposal`, `review`
Vendor catalogues	`bizplan/research/vendors/{pdm,gateway,switch,keypad}/`	zh	`catalog`, `report` (landscape)
Evidence archives	`bizplan/research/{data,sources}/`	n/a	CSV, PDF, scripts, `manifest.csv`, `SHA256SUMS`
Project records	`docs/`	en	PMA task, plan, decision, changelog, architecture, standard, templates
Unpublished references	`refs/`	n/a	third-party manuals kept out of the site

Kind definitions:

governance: a controlled planning document whose figures other documents cite (business plan, product plan, market model, commercial model, compliance matrix, assumptions register, open questions).
spec: a product Level 1 target specification; the only kind that may set Level 1 values.
design: a product Level 2 document (design appendix, data model, integration spec, application architecture, commissioning package, reference board). Must not change Level 1 values.
guide: an external-facing delivery document for suppliers and contract manufacturers (requirements, acceptance, quotation input); also the internal PPT build guide under governance.
brief: an external-facing product description for customers, installers, dealers, and sales (what it is, what it does, what it does not do, how it fits the system). Never a requirement source.
evaluation: a non-binding comparison or device evaluation (platform options, chip evaluation, protocol evaluation). Never a decision record.
foundation: a cross-product technical baseline (X01 CAN protocol, X02 config schema).
report: a research report on market, industry, certification, or technology.
proposal: an engineering proposal awaiting adoption through the PMA workflow; does not revise controlled specifications.
review: an assessment of an external or historical document.
catalog: one supplier record with the six fixed sections (company, product family, procurement and price, openness, relation to YBO, sources).
index: a directory entry page.

2. Frontmatter schema

Every Markdown page under bizplan/ carries YAML frontmatter. Pages under docs/task/ and docs/plan/ keep the PMA format and are exempt; other docs/ pages carry title only.

---
title: YBO Core —— 目标规格        # rendered title; breadcrumb label on index pages
kind: spec                          # one value from part 1
status: draft                       # draft | active | superseded | archived
updated: 2026-09-13                 # last content change, YYYY-MM-DD
version: R0.3                       # required for governance, spec, design, guide, foundation
product: P01                        # product kinds only; the product-line ID
level: 1                            # spec = 1, design = 2; omitted otherwise
lifecycle: spec-draft               # spec only: concept | spec-draft | evt | dvt | pvt | released
evidenceDate: 2026-09-08            # catalog and report only
supersededBy: ../engineering/yacht-24-channel-125a-power-spec.md   # required when status is superseded
---

Rules:

status is the document maturity: draft (being written or not yet adopted), active (current and citable), superseded (replaced; supersededBy required and the first paragraph names the successor), archived (kept for record only, not linked from indexes).
lifecycle is the product maturity and lives only on the Level 1 spec, using the vocabulary already defined in bizplan/product/index.md. Level 2 documents do not repeat it.
version follows the existing conventions: governance v1.x; product R0.x while draft, R1.0 when frozen for a gate. The version changes only when a numbered value or requirement changes; typo fixes bump updated only.
A theme component DocMeta.vue, mounted like Breadcrumb.vue, renders kind, status, version, updated, and a superseded banner above the H1. Hand-written status and date lines are removed from prose. Hand-written relation lines stay (see part 5).

3. Filename rules

ASCII lower-case kebab-case, .md, no spaces; English words even when the content is Chinese. Language variants use .en.md.
Product packages: P<nn>-<product>[-<slot>[-<aspect>]].md, where <slot> is one of the fixed package slots in part 4a and <aspect> is used only when a slot legitimately holds more than one file. The upper-case product ID token is the one accepted exception to lower-case, because it is the product's identifier in PRODUCT-PLAN.md and in published URLs. Evaluations live in evaluations/<slug>.md inside the package and carry no product prefix. Shared foundations keep X<nn>-<slug>.md.
Research: <slug>.md inside a topic directory. No numeric prefixes. Ordering is the index table's job.
Vendor catalogues: <vendor-slug>.md; one record per supplier, filed under its primary category; cross-category products are cross-referenced from the other category index.
Evidence: data/<topic>/<table>.csv, sources/<topic>/<document>.pdf plus manifest.csv and SHA256SUMS per topic, as today.
Project records: PMA formats unchanged. Existing legacy IDs are not renamed; they are closed or completed in place (part 9, phase 2).

4. Target directory structure

/
├── index.md                          home (zh)
├── AGENTS.md, CLAUDE.md -> AGENTS.md
├── bizplan/
│   ├── index.md
│   ├── governance/                   controlled planning documents
│   │   ├── index.md
│   │   ├── business-plan.md, business-plan.en.md
│   │   ├── product-plan.md
│   │   ├── market-model.md, commercial-model.md
│   │   ├── compliance-matrix.md, assumptions.md, open-questions.md
│   │   └── ppt-build-guide.md
│   ├── product/                      one package per product (part 4a)
│   │   ├── index.md
│   │   ├── diagrams/                 SVG plus JSON source
│   │   ├── shared/                   X01, X02
│   │   ├── core/ sense/ mate/ ac/ studio/ control/ view/ eye/ tag/
│   │   │   ├── index.md
│   │   │   ├── P<nn>-<product>.md            spec (Level 1)
│   │   │   ├── P<nn>-<product>-design.md     design (Level 2), or -design-<aspect>.md when split
│   │   │   ├── P<nn>-<product>-guide.md      supplier guide (external)
│   │   │   ├── P<nn>-<product>-brief.md      product brief (external)
│   │   │   └── evaluations/<slug>.md         non-binding evaluations
│   │   └── switch/                   a line with several products: line files plus one sub-package each
│   │       ├── index.md, P05-switch.md, P05-switch-brief.md
│   │       ├── air/ key/ air-hub/    each a full package as above
│   └── research/
│       ├── index.md
│       ├── market/                   market size, competitors, certification (4 reports)
│       ├── industry/                 marine digital switching, PDM industry, marine vs automotive (11 reports)
│       ├── engineering/              yacht circuits, vehicle PDM, high-current platform, MCU reviews (12 reports and proposals)
│       ├── vendors/
│       │   ├── index.md              catalogue entry: four categories and the landscape report
│       │   ├── air-key-landscape.md
│       │   ├── pdm/                  57 records (from vendors/)
│       │   └── gateway/ switch/ keypad/   (from air-key-vendors/)
│       ├── data/                     unchanged
│       └── sources/                  unchanged
├── docs/                             PMA records (en)
│   ├── index.md, architecture.md, changelog.md
│   ├── documentation-standard.md     this standard
│   ├── templates/                    one file per kind; excluded from the site
│   ├── decisions/                    index.md plus <YYYY-MM-DD>-<slug>.md
│   └── task/  plan/                  unchanged
├── refs/                             unpublished third-party manuals (from s7-200g2/)
├── scripts/lint-docs.mjs             documentation lint
└── .vitepress/                       config, theme, public/_redirects

4a. Product package

A product package is the unit of the product area. One package per product ID; a product line with several products (P05 Switch) holds line-level files plus one sub-package per product. Every package has the same slots, so a reader can predict the path of any product document and adding a product means copying one skeleton.

Slot	File	Kind	Audience	Required
Entry	`index.md`	`index`	everyone	always
Specification	`P<nn>-<product>.md`	`spec`	internal engineering, governance	always
Design	`P<nn>-<product>-design.md`, or `-design-<aspect>.md` when hardware, software, and data model are separate	`design`	internal engineering, contract design	from `spec-draft`
Supplier guide	`P<nn>-<product>-guide.md`	`guide`	suppliers, contract manufacturers	before `EVT` when the product is outsourced
Product brief	`P<nn>-<product>-brief.md`	`brief`	customers, installers, dealers, sales	always (a `draft` stub is acceptable at `concept`)
Evaluations	`evaluations/<slug>.md`	`evaluation`	internal engineering	optional

Slot rules:

Nothing else may live in a package. A document that fits no slot is either an evaluation, a research report (move to research/), or a decision (record in docs/decisions/).
The entry page states positioning, tier, lifecycle, and the slot table with each file's status; it is the only place the package is inventoried.
The spec is the only requirement source. The design must not change Level 1 values; the guide restates requirements for a supplier and adds acceptance and quotation scope; the brief restates capability for a buyer and adds nothing.
PRODUCT-PLAN and the product area index register the package by ID and directory only.
Evaluations are never cited as requirements; a spec cites an evaluation only in its open-items chapter.
docs/templates/product-package/ holds the full skeleton (index.md, spec with the 16- or 11-chapter template, design, guide, brief) with P<nn>-<product> placeholders. Adding a product is: copy the skeleton, rename, add the row in PRODUCT-PLAN and product/index.md.
The lint checks each package against this table using the spec's lifecycle, and fails on any file outside the slot pattern.

Mapping of today's files onto the slots (phase 3 renames, all redirected):

Package	Today	Becomes
core	`P01-core.md`, `P01-core-design.md`	unchanged; add `P01-core-brief.md`
sense	`P02-sense.md`, `P02-sense-design.md`	unchanged; add brief
mate	`P03-mate.md`, `P03-mate-hub.md`, `P03-mate-hub-design.md`, `P03-mate-software.md`, `P03-mate-data-model.md`	`P03-mate.md` absorbs the two Level 1 halves; `P03-mate-design-hardware.md`, `P03-mate-design-software.md`, `P03-mate-design-data-model.md`; add brief
ac	`P04-ac-interface.md`, `P04-ac-commissioning.md`, `P04-ac-board-16.md`	`P04-ac.md`, `P04-ac-design-commissioning.md`, `P04-ac-design-board-16.md`; add brief
switch (line)	`P05-switch.md`	`P05-switch.md`; add `P05-switch-brief.md`
switch/air	`P05-air-switch.md`, `-design.md`, `-platform-options.md`, `-esp32h2-evaluation.md`, `P05-air-supplier-guide.md`	`P05-air.md`, `P05-air-design.md`, `P05-air-guide.md`, `evaluations/platform-options.md`, `evaluations/esp32h2.md`
switch/key	`P05-key.md`, `P05-key-design.md`, `P05-key-supplier-guide.md`	`P05-key.md`, `P05-key-design.md`, `P05-key-guide.md`
switch/air-hub	`P05-air-hub.md`, `-design.md`, `-platform-options.md`	`P05-air-hub.md`, `P05-air-hub-design.md`, `evaluations/platform-options.md`; guide shared with air via a relation line
studio	`P07-studio.md`, `P07-studio-architecture.md`	`P07-studio.md`, `P07-studio-design.md`; add brief
control	`P09-control-protocol-evaluation.md`, `P09-control-ecosystem-access.md`	`P09-control.md` (new spec, from the evaluation's positioning chapter), `evaluations/protocol-platforms.md`, `P09-control-brief.md`
view	`P10-view.md`, `P10-view-design.md`	unchanged; add brief
eye	`P11-eye.md`, `P11-eye-integration.md`	`P11-eye.md`, `P11-eye-design.md`; add brief
tag	`P12-tag.md`, `P12-tag-design.md`	unchanged; add brief

Whether the Air and Air Hub sub-packages are created as proposed depends on plan 20260913-2340 (another session, in progress), which consolidates the Air and Air Hub documents into two files; phase 3 is sequenced after it and maps whatever it produces onto the slots.

What moves and what does not:

Product directories keep their paths; 17 product files are renamed onto the slot names and redirected, and 10 brief stubs are added.
Eight governance files move into bizplan/governance/ and drop upper-case. PRODUCT-PLAN.md alone is linked from roughly 80 pages; links are rewritten mechanically and the old URLs redirect.
Research reports move into three topic directories and lose their number prefixes. The 04a–04e matrices become industry/czone-product-matrix.md and so on, linked from the parent report and listed under it in the topic index.
The two vendor catalogues merge under research/vendors/ with four category directories. The 57 PDM records move one level down.
s7-200g2/ becomes refs/s7-200g2/; srcExclude and BREADCRUMB_SKIP change accordingly.

5. Page layout rules

H1 is the document title, identical to frontmatter title.
Directly after the H1, a relations list with fixed labels in fixed order, only the lines that apply: 产品入口, 治理摘要, Level-1 规格, 设计附录, 总交付要求, 引用的基础文件, 依据, 适用产品, 取代说明. Labels use a full-width colon. Status, version, and date lines are removed because DocMeta renders them.
A superseded document opens its first paragraph with the successor link; status: superseded and supersededBy make the same statement machine-readable.
Chapter templates stay as defined today: 16 numbered chapters for hardware specs, 11 for software and concept products, six fixed sections for catalogues. The design and guide kinds get a short fixed skeleton in docs/templates/.
Every controlled document (governance, spec, design, guide, foundation) ends with ## 变更记录 as a table 日期 | 版本 | 变更 | 记录, the last column linking the task or changelog entry.
Chinese pages use full-width punctuation consistently; numbers, units, and identifiers keep half-width characters with a space between a CJK character and a Latin token, matching the majority of the existing text. The lint does not enforce punctuation.

6. Index-page rules

Every page-bearing directory has an index.md with title, kind: index, one scope paragraph, and one document table.
The document table has the columns 文档 | 类型 | 状态 | 内容, where 类型 and 状态 repeat the frontmatter values in Chinese labels defined once in the standard (规格 / 设计 / 指南 / 评估 / 说明 / 基础 / 报告 / 提案 / 评审 / 目录; 草案 / 现行 / 已取代 / 归档).
A page appears in exactly one directory index. Parent indexes link to child directories, not to grandchildren. Archived pages are not listed.
The lint fails when a page is missing from its directory index, when a listed file does not exist, or when the table's 类型 or 状态 disagrees with the page's frontmatter.

7. Cross-reference rules

Relative Markdown links only, resolved from the containing file; no bare filenames in backticks as references. Governing figures cite PRODUCT-PLAN by section (§P1, §6).
A Level 2 document cites its Level 1 spec in the relations list; a spec cites its governance section; a research proposal cites the spec it would change and states that it does not change it until adopted.
A superseded page is linked only from its successor and from the index's historical table.
Retired task and plan IDs link to their changelog entry, as today.

8. Quality gate

scripts/lint-docs.mjs (Bun, no dependencies) checks: frontmatter present and valid for every bizplan/**/*.md; kind and status in vocabulary; updated is an ISO date not in the future; version present where required; supersededBy present and resolvable when status: superseded; lifecycle only on kind: spec; filenames match part 3; every page listed once in its directory index with matching 类型 and 状态; no page under bizplan/ outside a directory with an index.md; no numeric prefix in research/.
package.json gains "docs:lint": "bun scripts/lint-docs.mjs". AGENTS.md sets the quality-gate command to bun run docs:lint && bun run docs:build && git diff --check.
.github/workflows/deploy.yml runs the lint before the build.
The lint has no test framework behind it; it is verified by running it against the migrated tree and against a deliberately broken fixture in tmp/. Adding a test harness is offered, not assumed.

9. Migration phases

Each phase is its own PMA task, approved separately, and lands as one commit. Every move uses git mv; every rename is followed by a mechanical link rewrite, a _redirects entry from the old clean URL to the new one, bun run docs:build (dead links fail the build), and a rendered-link scan as done on 2026-09-10.

Phase	Content	Files touched (approx.)	Depends on
1 Standard and tooling	Write `docs/documentation-standard.md`, `docs/templates/` (the `product-package/` skeleton plus report, proposal, catalog, decision), `DocMeta.vue`, `scripts/lint-docs.mjs` in report-only mode, `docs/decisions/index.md`; update `AGENTS.md`, `docs/architecture.md`, `docs/index.md`, `package.json`, `.vitepress/config.mts`	16	approval of this plan
2 Project records	Resolve the four legacy records by `task-state.sh close` or `complete` with the user's confirmation; normalise blank lines in both indexes; fix the three stale English-counterpart sentences in governance files; remove the dead `bsp-control/` ignore	10	phase 1
3 Product packages	Rename 17 product files onto the slot names and create the three switch sub-packages; add 10 brief stubs; add frontmatter to all product pages and indexes; replace the three header conventions with the relations list; rebuild each package `index.md` as the slot table; rewrite links in citing pages and write `_redirects`; make the lint blocking for `bizplan/product/`	about 75	phase 1, plan 20260913-2340
4 Research and vendors	Create `market/`, `industry/`, `engineering/`; move and rename 27 reports; merge the catalogues under `vendors/{pdm,gateway,switch,keypad}`; move the landscape report; add frontmatter to all 130 pages; rewrite links in roughly 60 citing pages; write `_redirects`; make the lint blocking for `bizplan/research/`	about 200	phase 1
5 Governance and root	Move eight governance files into `bizplan/governance/` with lower-case names; rewrite links in roughly 80 pages; move `s7-200g2/` to `refs/`; write `_redirects`; make the lint blocking repository-wide	about 95	phases 3 and 4

Phases 3 and 4 are independent of each other. Phase 5 is last because it touches the most-cited files and is the one the owner is most likely to defer.

Risks

Published URL churn. Phases 3, 4, and 5 change about 180 URLs, including 17 product pages that were previously stable. Cloudflare Workers static assets honour a _redirects file in the output directory; VitePress copies .vitepress/public/ into the build, so the file is .vitepress/public/_redirects. Verify redirect support on the first deploy of phase 4 before phase 5; the fallback is a small redirect map in a Worker script.
Link rewrites are mechanical but broad. A missed link fails the build, which is the desired failure mode; a link that resolves to the wrong file does not. The rendered-link scan from the 2026-09-10 pass is reused to compare link targets before and after.
Concurrent work. Task 20260914-0010 and plans 20260910-0717, 20260913-0331, and 20260913-2340 are in progress in other sessions and touch bizplan/product/switch/, bizplan/product/core/, and .vitepress/theme/. Phase 3 waits for 20260913-2340 (it reshapes the very Air and Air Hub files the switch sub-packages are built from) and coordinates with the others; phase 1 touches .vitepress/theme/index.ts, which 20260913-0331 may also edit.
Brief stubs are new content. Ten product briefs do not exist today. Phase 3 creates them as draft stubs holding only the positioning paragraph copied from the spec; writing real customer-facing text is separate editorial work, not a migration step.
Control has no spec. P09 today has an evaluation and a customer note but no Level 1 document. The slot table requires one; phase 3 seeds P09-control.md from the evaluation's positioning chapter and marks it concept, without inventing requirements.
Frontmatter and title. VitePress uses title for the page <title> and the breadcrumb map reads it; adding it to every page changes browser titles from the H1 text to the frontmatter text. Setting them identical avoids drift.
Frontmatter and search. Adding frontmatter does not change the indexed body text; DocMeta renders outside the Markdown content, so status labels are not indexed. Confirm after phase 1.
Legacy record closure needs the owner's word. Closing RESEARCH-008 / PLAN-024 and the yacht evidence task asserts they are superseded or done. The plan lists them for confirmation instead of deciding.
Chinese-language standard. The standard is English per repository rule; authors of Chinese content must read English rules. Each Chinese area index keeps a short Chinese pointer to the standard and the label vocabulary, so day-to-day authoring does not require the English text.

Scope

This plan itself changes nothing outside docs/task/ and docs/plan/. Approval authorises phase 1 only; phases 2 to 5 each open a task and a compact proposal before implementation. Total footprint after all phases: about 27 new files (standard, templates, lint, component, ten brief stubs, one Control spec), about 180 moves, and frontmatter or link edits in essentially every Markdown page under bizplan/.

Out of scope: changing any technical claim, figure, or requirement; translating content; splitting docs/changelog.md; adding a test framework; redesigning the site theme beyond DocMeta.

Alternatives

A. Rules only, no moves. Write the standard, frontmatter, lint, and templates; keep every path. Removes the header and status inconsistencies and gives a gate, but leaves four casing schemes, the duplicate 08, and two catalogue layouts in place, so new authors keep copying the nearest example. Recommended only if URL stability outweighs structure.
B. Flat research with renamed files. Drop number prefixes but keep research/ flat. Fewer moves than the proposal, but the directory would hold 30 reports plus four subdirectories with no visible grouping, and breadcrumbs could not show the topic. The index would remain the only structure.
C. Split by language instead of by area. A zh/ and en/ tree with VitePress locales. Rejected on 2026-09-10 when the site went Chinese-first with one English exception; nothing has changed.
D. Generate index tables from frontmatter. A build step could write the 文档 | 类型 | 状态 | 内容 tables. It removes one class of lint failure but makes the index pages non-editable and hides the human-written 内容 column behind another field. The lint-and-check approach keeps indexes hand-written and consistent; generation can be revisited if drift becomes frequent.
E. Keep governance files at bizplan/ root, lower-cased only. Halves the phase 5 link rewrite but leaves eight loose files beside two directories. The dedicated governance/ directory gives them an index, a breadcrumb, and a kind, matching every other area.

Annotations

2026-09-14 owner: products must be uniform too. Every product needs the same document set (specification, description, external-facing files), and adding a product must mean adding one product package, so the structure is predictable. Response: added part 4a (fixed package slots, skeleton template, lint check per lifecycle), the brief kind, the slot mapping of today's files, and resized phase 3.
2026-09-14 01:30 owner: approved all five phases at once ("开始全部处理") and asked that the other pending plans be completed as written. 2026-09-14 03:20: all phases delivered; see the changelog entry of the same time.