Files

T

veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents

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`.

2026-08-20 19:30:25 -05:00

5.4 KiB

Raw Blame History

kind, status

kind	status
spec	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:

Purpose and scope.
Reader entry points.
Complete target directory tree, including the optional .obsidian/ vault configuration boundary and the workflow-only plans/ directory.
Root control document responsibilities.
Guide book responsibilities and chapter rules.
Artifact directory responsibilities.
Placement matrix for agents.
Source-of-truth and precedence rules.
Page naming and front matter conventions.
Obsidian wikilink and Git-hosted Markdown link conventions.
Authoring workflow for new or changed documentation.
Migration rules for _old_structure/, legacy root files, and repository references.
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:

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:

pnpm exec prettier --check docs/README.md

Expected: Prettier reports the file is formatted.

Step 2: Run whitespace validation

Run:

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:

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.

5.4 KiB Raw Blame History

Documentation Structure README Implementation Plan

Task 1: Write the documentation structure contract

Task 2: Verify the README-only change

5.4 KiB

Raw Blame History