docs: restructure docs/ into frozen references + docs/work/mvp, and add a housekeeping skill to prevent drift

[Wahbeh-Mohammad]

Summary

The docs/ tree has no stated structure. Four trees grew there for four different
purposes. Nothing says which tree owns what. Nothing keeps CLAUDE.md and README.md
in agreement with the code. This issue does two things:

1. Give docs/ a documented structure, and move the existing files into it once.
2. Add a housekeeping skill that probes the tree, reports drift, and repairs it.

This is a follow-up to #56. Land the knowledge-lookup work first. The housekeeping
skill reads bun run knowledge --topic documentation for its own rules, so it depends
on that CLI staying stable.

---

Background

CLAUDE.md has drifted. Nobody has asked for it to stay current, and no gate checks
it. Nine phases have shipped since it was written. The measured drift is listed below.
The same problem applies to README.md, which is still two lines and has a spelling
error.

There is also no as-built documentation. The repository has a normative specification
and a pre-implementation design document. It has no document that describes the code
that exists today. dexpace/python-sdk solved this with a flat docs/ tree. We copy
that shape.

---

Current state

Measured on branch mvp at d8217af. 139 files under docs/.

Path	Content	Size
docs/knowledge/	39 topic files, plus INDEX.md and SOURCES.md	509 KB
docs/product-spec/	20 chapters, 3 appendices	568 KB
docs/product-spec.md	table of contents for the directory above	6 KB
docs/sdk-design-nodejs/	10 chapters	96 KB
docs/sdk-design-nodejs.md	table of contents for the directory above	3 KB
docs/superpowers/specs/	24 files	—
docs/superpowers/plans/	39 files	—
docs/open-items.md	the running register, sections A through N	111 KB
open-items.md (repository root)	a second register, Phase 5a only, 9 findings	9 KB
README.md (repository root)	2 lines	44 B

Measured drift in CLAUDE.md

CLAUDE.md states	Actual
"Two published packages today" — @dexpace/core and @dexpace/codec-json	9 publishable packages and 2 private ones. Missing: logging-pino, logging-debug, body-file, transport-shared, transport-fetch, transport-undici, rx
The API section names 2 committed reports	9 reports exist. bun run api verifies all 9
The gate list has 7 commands	CI runs 8. verify:sse-37 is a blocking step at .github/workflows/ci.yml:60 and does not appear in CLAUDE.md
"518 KB across 39 topic files"	509 KB across 39 topic files
The documentation hierarchy table has 4 rows	It omits docs/open-items.md, the largest single file in the tree

Other defects

• packages/core/README.md does not exist. @dexpace/core is the flagship package.
  The harvested styleguide requires a README on every publishable package
  (bun run knowledge --topic documentation).
• The two open-items.md files are one register that was split. docs/open-items.md
  states the gap itself: "Two phases are shipped but were never registered here: 4c
  (stage-based pipeline) and 5a (retry)." The root file holds the missing Phase 5a
  content. It landed in cba4721 and was never merged in.
• Section letters in docs/open-items.md are cited from source comments. Nine
  references exist in packages/core/src/, for example docs/open-items.md H12 at
  packages/core/src/seams/index.ts:11 and docs/open-items.md K11 at
  packages/core/src/index.ts:248. A merge must append a new letter. It must not
  renumber the existing ones.
• Heading style in docs/open-items.md is inconsistent. Sections A through G use
  ## A.; sections H through N use ## Section H —.
• docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md is 112 KB and
  holds ## Open Findings — Phase 4b Validation Review and
  ## Open Findings — Phase 4c Validation Review. These belong in open-items.md.
• docs/ has no index file.
• README.md contains the spelling error "paltform".

---

Target structure

docs/
  README.md              <- new. Index of this tree. States what each entry owns.
  assets/                <- new. Vendored wordmark SVG files.
  knowledge/             <- frozen. Owned by knowledge-harvest.
  product-spec/          <- frozen. Normative.
  product-spec.md        <- frozen. Table of contents for product-spec/.
  sdk-design-nodejs/     <- frozen. Pre-implementation design.
  sdk-design-nodejs.md   <- frozen. Table of contents for sdk-design-nodejs/.
  sdk-documentation/     <- new. As-built documentation of the shipped code.
  open-items.md          <- stays. The running register.
  deferred-items.md      <- new. Split out of open-items.md.
  deviations.md          <- stays at this level. See note below.
  work/
    mvp/
      roadmap-design.md
      checkpoint-scaffold-through-phase3a.md
      scaffold/
      phase-1/ … phase-10/

Rules

• Frozen trees. knowledge/, product-spec/, sdk-design-nodejs/ and their two
  sibling table-of-contents files are read-only to the housekeeping skill. The skill
  reads them. It never writes to them.
• work/ holds process records. Design documents, plans, checklists, decisions,
  test evidence, and notes taken while doing the work. One directory for each unit of
  delivery.
• work/mvp/ holds everything delivered so far. All work to date is the MVP. Later
  efforts get sibling directories under work/.
• One directory for each whole phase. phase-3/ holds 3a and 3b. phase-6/
  holds 6a, 6b, 6c, and the segmentation design that covers all three. Sub-phases
  do not get their own top-level directory.
• Registers stay at the docs/ root. open-items.md, deferred-items.md, and the
  deviation record are cross-phase. They are not process records and they are not
  as-built documentation. dexpace/python-sdk does the same, with deviations.md and
  conformance-ledger.md at its docs/ root.
• docs/superpowers/ stays as the write target. The Superpowers brainstorming and
  writing-plans skills hard-code that path
  (writing-plans/SKILL.md:18, brainstorming/SKILL.md:100). Do not fight it. The
  housekeeping skill collects from docs/superpowers/ and moves the files into
  docs/work/. Collection is part of its normal run.

Phase mapping

The 63 files under docs/superpowers/ map as follows.

Target	Source files
work/mvp/roadmap-design.md	2026-07-23-nodejs-sdk-v1-roadmap-design.md
work/mvp/checkpoint-scaffold-through-phase3a.md	the checkpoint plan
work/mvp/scaffold/	the 3 scaffold-milestone files
work/mvp/phase-1/	phase1 design, plan, checklist
work/mvp/phase-2/	phase2 design, plan, checklist
work/mvp/phase-3/	phase3a and phase3b files
work/mvp/phase-4/	phase4a, phase4b, phase4c, and the shared checklist
work/mvp/phase-5/	phase5a, phase5b, phase5c files
work/mvp/phase-6/	phase6a, phase6b, phase6c, and phase6-segmentation
work/mvp/phase-7/	phase7a, phase7b, and phase7-segmentation
work/mvp/phase-8/	phase8a, phase8b, and phase8-segmentation
work/mvp/phase-9/	phase9 design, plan, checklist
work/mvp/phase-10/	phase10 design and plan

Keep the YYYY-MM-DD- prefix on each file name. It carries ordering that the
directory name does not.

---

Work items

1. Migration commit

One commit. git mv only, so history follows each file.

Fix the one link that breaks: test/node-conformance/README.md:3 points at
docs/superpowers/plans/2026-07-25-checkpoint-scaffold-through-phase3a.md:341.

Two references need no change. scripts/changeset.mjs:7 is a comment.
scripts/knowledge.test.mjs:127 is a test fixture string. Leave the .changeset/
files alone. They are frozen history.

Update CLAUDE.md at lines 133, 226, and 232.

2. Register consolidation

• Merge the root open-items.md into docs/open-items.md as a new lettered section.
  Do not renumber sections A through N.
• Move ## Open Findings blocks out of the roadmap design document and into
  docs/open-items.md.
• Split the deferred items into docs/deferred-items.md. The roadmap document has a
  ## Deferred Items Log section; that is the seed.
• Normalize heading style across the whole register.

3. docs/sdk-documentation/

Model on dexpace/python-sdk/docs/, which is flat and already proven:

architecture.md  http.md  pipelines.md  bodies.md  auth.md  errors.md
quality-gates.md  write-a-transport.md  write-a-serde.md
write-a-paging-strategy.md  write-a-response-handler.md

State the boundary in writing. This tree does not restate what
packages/*/etc/*.api.md and the TSDoc blocks already carry. Those two are generated
and gate-verified; a third copy would drift. This tree holds what they cannot express:
how the packages compose, which package to install for which job, and worked examples
that cross a package boundary.

4. docs/README.md

An index. One row for each entry in docs/. Each row says what the entry owns, who
writes to it, and whether the housekeeping skill may touch it.

5. Root README.md

Rewrite against dexpace/python-sdk/README.md. Keep the same section order: wordmark,
title, badges, one-paragraph statement, package table, quick start, architecture
diagram, core surface table, highlights, development, conventions, contributing,
security, license.

Fix "paltform".

Vendor the wordmark into docs/assets/, the way python-sdk does. The canonical
source is dexpace/morphic:

https://raw.githubusercontent.com/dexpace/morphic/main/docs/assets/dexpace-wordmark-dark.svg
https://raw.githubusercontent.com/dexpace/morphic/main/docs/assets/dexpace-wordmark-light.svg

A vendored copy survives a rename in morphic and works offline. The .github profile
repository links the raw URL instead; that is correct for a profile page and wrong for
a repository README.

Note one gap. The python-sdk README links to CONTRIBUTING.md,
CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, and LICENSE.md. This repository
has none of them, and its licence file is LICENSE, without an extension. Either add
the files or drop the sections. Do not ship dead links.

6. packages/core/README.md

Write it. The harvested styleguide states the bar: the top of the README gets a new
engineer from zero to one working call in about 30 seconds, without reading source.
Use packages/transport-fetch/README.md as the model. It is the strongest README in
the workspace.

While there, level the weak ones. packages/logging-debug/README.md is 387 bytes and
packages/logging-pino/README.md is 399 bytes.

7. The housekeeping skill

.claude/skills/housekeeping/. It runs in two stages.

Probe. Read-only. Report only. It checks:

• Files sitting in docs/superpowers/ that belong under docs/work/.
• Files at the repository root that belong under docs/.
• Claims in CLAUDE.md against the repository: package count and names, the script
  list in package.json, the blocking steps in .github/workflows/ci.yml, the
  committed API reports, and the docs/ tree itself.
• Claims in README.md against the same sources.
• A README on every publishable package.
• Broken relative links inside docs/, CLAUDE.md, and the package READMEs.
• Open-item or deferral text that has appeared in a specification document instead of
  the register.

Apply. Only after the probe reports. It performs the git mv calls, updates
CLAUDE.md and README.md, and refreshes docs/README.md.

It may write to: docs/README.md, docs/sdk-documentation/, docs/work/,
CLAUDE.md, README.md, and the package READMEs.

It must never write to: docs/knowledge/, docs/product-spec/,
docs/sdk-design-nodejs/, docs/product-spec.md, or docs/sdk-design-nodejs.md.

It takes its documentation rules from the corpus, not from its own opinion:

bun run knowledge --topic documentation    # 21 harvested styleguide rules

---

Out of scope

• Any change to the content of knowledge/, product-spec/, or sdk-design-nodejs/.
• Adding CONTRIBUTING.md, CODE_OF_CONDUCT.md, or SECURITY.md. Track these
  separately if the README is to link them.
• Wiring the skill into CI. It is a manual tool for now, like bun run test:scripts.

---

Acceptance criteria

• docs/ matches the target structure above.
• Every moved file kept its history. The migration used git mv only.
• docs/README.md exists and lists every entry in docs/.
• One open-items.md remains. It sits at docs/. Section letters A through N are
  unchanged, and every source-comment citation still resolves.
• docs/deferred-items.md exists.
• No specification document holds an open-items or deferral section.
• docs/sdk-documentation/ exists and states its boundary against
  etc/*.api.md and TSDoc.
• README.md follows the python-sdk shape, shows the wordmark, and has no dead
  links.
• packages/core/README.md exists.
• CLAUDE.md names all 9 publishable packages, lists all 8 verification gates
  including verify:sse-37, and its documentation hierarchy table covers the whole
  of docs/.
• .claude/skills/housekeeping/SKILL.md exists, probes before it applies, and
  refuses to write to the three frozen trees.
• Every gate in .github/workflows/ci.yml still passes.
  Run node .claude/skills/ci-preflight/run-ci.mjs --clean.

---

Open decisions

1. docs/assets/ adds a sixth entry to docs/. Confirm it, or reference the morphic
   raw URL instead and add no directory.
2. Naming: docs/sdk-documentation/ against docs/guide/. python-sdk uses plain
   docs/, which is not available here because this repository already uses docs/
   for four other trees.
3. The deviations record. docs/sdk-design-nodejs/10-deliberate-deviations-from-the-reference-contract.md
   sits inside a frozen tree and is cited from CLAUDE.md:164. Decide whether it moves
   to docs/deviations.md, or stays and is linked from docs/README.md.

---

Depends on #56.