Skip to content

Inventory nodespace-docs: what is live, what is superseded, and where each page goes #3728

Closed

Description

@malibio

Re-inventory before beginning the rebuild work. This inventory is a snapshot taken on 2026-10-11 and the docs and code keep moving: pages have been added since (development/windows-testing.md, given a row by hand), and every "Code today" cell was true of main on that date only. Before any node is written from development/docs-inventory.md (the rebuild in #3727 and its sub-issues), repeat the inventory step: re-check each page's status against the code, add rows for pages that did not exist, refresh the counts, and put the changes to the user as a decision where a destination changes. Until then, treat a row as a lead, not as a fact.

Overview

The first step of rebuilding the design record in NodeSpace (#3727): a page-by-page inventory of nodespace-docs that says what is still true, what is dead, and where each live piece belongs in the graph. Nothing is migrated here. This can be done before sync exists.

Problem Statement

Nobody knows how much of the 206 non-archived pages is live. Decisions have been superseded and amended in place, pages describe designs ahead of the code, and several pages restate the same thing. Without an inventory the rebuild cannot be sized or split.

Proposed Solution

A table, one row per page (per section for a long page), with:

  • status: live, superseded, duplicate of another page, ahead of the code, or dead;
  • for a decision record: the decision as it stands today in one or two sentences, with its amendments folded in, and the records it replaced;
  • destination: a decision node, a skill attached to the project, a reference document, a spec for work still ahead, or not migrated;
  • what it should link to (the type, the area of code, the decisions it depends on).

Then a short proposal: the collections the reference documents go in, and whether architecture and component references need anything the existing types do not give.

Documentation

  • ADR-092 §1 to §4 - the spec, plan, decision and project types the record is rebuilt in
  • ADR-094 "The shipped workflow" - standards are skills attached to a project; a node is read with what governs it
  • documentation.md - the rule that all design lives in nodespace-docs, which this work replaces

Acceptance Criteria

  • Every page under decisions/, architecture/, components/, development/ and operations/ has a row
  • strategy/ and archived/ are covered by a rule (kept or not) with the exceptions named
  • Each live decision is stated in its current form, and each superseded one names what replaced it
  • Pages that are ahead of the code are marked, with what the code does today
  • The count of decision nodes, skills and reference documents the rebuild will produce is given
  • The proposal on collections and on whether a reference type is needed is put to the user as a decision, and the answer is recorded
  • The inventory is repeated against main before any dependent issue begins: each page's status re-checked, rows added for pages that did not exist, counts refreshed, and any changed destination put to the user as a decision

Technical Specifications

Reference Files

  • nodespace-docs: decisions/ (91 files), architecture/ (35), components/ (14), development/ (19), operations/ (2), strategy/ (47), archived/ (152)
  • packages/core/src/models/core_schemas.rs - the types available

Implementation Details

  • Check a claim against the code before calling a page live; a page that reads as current may describe a target.
  • The inventory is a working document and lives in nodespace-docs until the rebuild is done.

Related Issues

Non-Goals

  • Writing any node into the graph
  • Editing the docs to fix what the inventory finds

Activity

  1. malibio commented on Oct 11, 2026

    @malibio
    CollaboratorAuthor

    For the inventory's closing proposal: architecture and component designs are a third kind of document, neither decision nor spec (#3731). The question to put to the user is not only which collections they go in, but how a spec or task links to the designs that govern it, and whether a design needs a type of its own for that link.

  2. malibio commented on Oct 11, 2026

    @malibio
    CollaboratorAuthor

    Correction to the note above: designs are connected by mentions, which are real links with backlinks, so no relationship or type has to be designed first (#3731). The inventory still marks, for each design, what in it is binding (a decision or a project standard) and what is background reachable by mention.

  3. self-assigned this
    on Oct 11, 2026
  4. malibio commented on Oct 12, 2026

    @malibio
    CollaboratorAuthor

    Inventory is in nodespace-docs: development/docs-inventory.md (commit 5fbdf6c). One row per page or section across decisions/, architecture/, components/, development/ and operations/; a rule with named exceptions for strategy/ and archived/; counts of what the rebuild produces (about 72 decision nodes, 23 skill rows, 71 reference rows, 18 spec rows). The proposal was put to Michael and the answer is recorded in the page: four collections for reference documents (Architecture, Node types, Interface, Strategy), and no new reference type for now.

  5. removed their assignment
    on Oct 13, 2026
  6. malibio commented on Nov 4, 2026

    @malibio
    CollaboratorAuthor

    Inventory done: every page in nodespace-docs has a destination in development/docs-inventory.md (decision, skill, document, none), with counts verified. Closing; the migration continues under #3727 and #3729.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions