Skip to content

Move the spec into the frame and concept chapters, with no change of meaning #374

Open

Description

@ExtraToast

Parent

Rewrite the spec and the compiler in place, release 1.0.0, and hand over every Project

What to build

The specification is reorganised into the layout Decide the chapter layout of the rewritten spec settled: a pipeline frame (00, 10, 14, 15, 20, 30, 40, 55, 60) and seven concept chapters (11 Processes, 12 Exposure, 13 Data, 16 Dependencies, 17 Secrets and access, 18 Placement, 19 Observability). After it, a reader finds one concept in one chapter, and every later pull request edits one chapter.

This pull request moves text and changes no meaning. It lands right after the model-driven implementation is deleted and before any rewrite.

Acceptance criteria

  • Chapters 11, 12, 13, 17, 18 and 19 exist. Every surviving chapter keeps its number and file name.
  • Chapter 50 is gone and its number is not reused: switchover, expand and contract, and a provider that moves are in chapter 55, and the lock lifecycle is in chapter 40.
  • The stage-specific parts of chapter 20 are rehomed: the migration in 13, the Move in 55, the Vault policy job and the path plan in 17.
  • Each concept chapter holds its Platform-side vocabulary (tiers in 12, the engine catalog and durability policy in 13, the hardening policy in 11). Chapter 14 keeps what belongs to the document as a whole and gains an index naming the chapter that defines each Platform field.
  • Diagram sources sit in a diagrams directory beside the chapters, named by chapter and linked from it.
  • Chapter 60's procedures sit in a handover runbook and a setup runbook under the documentation tree, and the chapter links to them.
  • The diff holds moves, link fixes and pointer fixes only: no sentence changes what it says.
  • Every tool that reads a chapter by path still finds what it reads.
  • npm run lint:links and npm run lint:adrs pass, and every normative: pointer resolves.

Blocked by

Activity

  1. added
    type: docsDocumentation-only change.
    area: deployhomelab-deploy, deploy-v2, manifests, and rollout flow.
    priority: P2Medium; normal planned work.
    status: blockedCannot move forward until an external dependency is resolved.
    on Oct 12, 2026
  2. self-assigned this
    on Oct 27, 2026
  3. ExtraToast commented on Oct 27, 2026

    @ExtraToast
    ContributorAuthor

    Resume here (2026-10-27)

    State: not started.

    Next step: after #655, move the spec into frame and concept chapters with no change of meaning, in one PR.

    Blocked by: #655 (ordering, so the examples settle first).

    Decisions:

    • No change of meaning. Every rule keeps its wording and its error code.
    • The PR body lists every old anchor with its new one. Comments in the estate and delivery repos cite deploy-kit anchors, and the release session updates them from that list. Send them the list when the PR merges.

    Gotchas:

    • npm run lint:links checks the in-repo anchors. ADRs, code comments (spec/v1/NN-*.md#anchor), test names and RENDER-GAPS cite chapters too.
    • docs/mde and emf/ must not change.
    • The diagrams in spec/v1/diagrams are named by chapter number. Rename them only if their chapter is renumbered, and keep scripts/diagrams/class-diagram.py's chapter arguments in step.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area: deployhomelab-deploy, deploy-v2, manifests, and rollout flow.priority: P2Medium; normal planned work.status: blockedCannot move forward until an external dependency is resolved.type: docsDocumentation-only change.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions