veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
141 lines
5.4 KiB
Markdown
141 lines
5.4 KiB
Markdown
---
|
|
kind: spec
|
|
status: active
|
|
---
|
|
|
|
# Documentation Structure README Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Replace the starter `docs/README.md` with the normative documentation structure, placement rules, source-of-truth policy, and Obsidian-compatible navigation conventions approved for Mosaic Stack.
|
|
|
|
**Architecture:** Keep `docs/README.md` as the root documentation atlas and authoring contract. Use audience books for current user, administrator, and developer content; keep API contracts and operational artifacts in dedicated directories; retain `_old_structure/` as a read-only migration quarantine. Do not move or rewrite existing documentation in this slice.
|
|
|
|
**Tech Stack:** Markdown, YAML front matter examples, Obsidian wikilinks, relative Markdown links, Prettier.
|
|
|
|
---
|
|
|
|
### Task 1: Write the documentation structure contract
|
|
|
|
**Files:**
|
|
|
|
- Modify: `docs/README.md`
|
|
- Reference: `docs/plans/2026-08-10-docs-information-architecture-design.md`
|
|
|
|
**Step 1: Confirm the approved design and current transition constraints**
|
|
|
|
Verify that the README preserves these decisions:
|
|
|
|
- `docs/mosaic-stack/` is not a target content directory.
|
|
- `docs/README.md` is the documentation atlas and placement contract.
|
|
- Existing files are not moved or rewritten yet.
|
|
- `_old_structure/` is read-only migration quarantine.
|
|
- Root control files, audience books, API, reports, tasks, plans, scratchpads, releases, archive, and assets have distinct responsibilities.
|
|
|
|
**Step 2: Replace the starter README**
|
|
|
|
Write `docs/README.md` with these sections:
|
|
|
|
1. Purpose and scope.
|
|
2. Reader entry points.
|
|
3. Complete target directory tree, including the optional `.obsidian/` vault configuration boundary and the workflow-only `plans/` directory.
|
|
4. Root control document responsibilities.
|
|
5. Guide book responsibilities and chapter rules.
|
|
6. Artifact directory responsibilities.
|
|
7. Placement matrix for agents.
|
|
8. Source-of-truth and precedence rules.
|
|
9. Page naming and front matter conventions.
|
|
10. Obsidian wikilink and Git-hosted Markdown link conventions.
|
|
11. Authoring workflow for new or changed documentation.
|
|
12. Migration rules for `_old_structure/`, legacy root files, and repository references.
|
|
13. Current transitional exceptions and explicit non-goals.
|
|
|
|
Use future target paths as a blueprint, but clearly label directories that are not populated yet so readers do not mistake the blueprint for completed migration.
|
|
|
|
**Step 3: Preserve the existing Obsidian configuration boundary**
|
|
|
|
Document `.obsidian/` as optional vault metadata only. Do not place Markdown content, scratchpads, reports, or source-of-truth files under it, and do not modify its existing files in this task.
|
|
|
|
**Step 4: Keep the README portable**
|
|
|
|
Use ordinary relative Markdown links for indexes and Git-hosted navigation. Use Obsidian wikilinks for graph-oriented relationships such as `Related`, `Depends on`, and `Referenced by`. Do not make a current navigation path depend solely on a Git-host-incompatible wikilink.
|
|
|
|
**Step 5: Review the resulting document**
|
|
|
|
Check that an agent can answer all of these without inspecting another file:
|
|
|
|
- Where does a user guide go?
|
|
- Where does an admin runbook go?
|
|
- Where does architecture or an RFC go?
|
|
- Where does an API contract go?
|
|
- Where does an active scratchpad go?
|
|
- Where does a review or QA report go?
|
|
- Where does an approved design or implementation plan go?
|
|
- Which files are normative, working notes, evidence, or historical?
|
|
- What may be added directly under `docs/`?
|
|
|
|
**Step 6: Commit only the README**
|
|
|
|
Because `docs/GETTING_STARTED.md` is an unrelated pre-staged deletion, stage and commit only `docs/README.md`:
|
|
|
|
```bash
|
|
git add docs/README.md
|
|
git commit --only docs/README.md -m "docs: codify documentation structure"
|
|
```
|
|
|
|
Expected: the commit contains only the README change; the existing staged deletion and orchestrator state remain outside the commit.
|
|
|
|
### Task 2: Verify the README-only change
|
|
|
|
**Files:**
|
|
|
|
- Verify: `docs/README.md`
|
|
|
|
**Step 1: Run Markdown formatting validation**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
pnpm exec prettier --check docs/README.md
|
|
```
|
|
|
|
Expected: Prettier reports the file is formatted.
|
|
|
|
**Step 2: Run whitespace validation**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git diff --check HEAD^ -- docs/README.md
|
|
```
|
|
|
|
Expected: no whitespace errors.
|
|
|
|
**Step 3: Validate required structural anchors**
|
|
|
|
Run a focused search or script confirming the README names:
|
|
|
|
- `PRD.md`, `TASKS.md`, and `SITEMAP.md`;
|
|
- `USER-GUIDE/`, `ADMIN-GUIDE/`, `DEVELOPER-GUIDE/`, and `API/`;
|
|
- `reports/`, `tasks/`, `plans/`, `scratchpads/`, `releases/`, `archive/`, and `assets/`;
|
|
- `_old_structure/` as read-only quarantine;
|
|
- `docs/mosaic-stack/` as retired/non-authoring;
|
|
- Obsidian wikilinks and Git-compatible Markdown links.
|
|
|
|
Expected: all anchors are present and no section instructs agents to create content under `docs/mosaic-stack/`.
|
|
|
|
**Step 4: Confirm scope isolation**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git status --short
|
|
git show --stat --oneline HEAD
|
|
```
|
|
|
|
Expected: the new commit contains only `docs/README.md`; pre-existing `.mosaic/orchestrator/*`, `docs/GETTING_STARTED.md`, and `docs/.obsidian/` states remain untouched.
|
|
|
|
**Step 5: Record verification evidence**
|
|
|
|
Update the task scratchpad at `docs/scratchpads/DOCS-IA-001.md` with commands, results, known transitional gaps, and the next migration slice. Do not modify active `docs/TASKS.md`; its single-writer policy belongs to the orchestrator.
|