Repository navigation
Description
Context and request
Readers and agents need the remaining authored MSX documentation to start with its subject, not a description of the document. Continue the cleanup beyond the four pages already covered by #293.
#293 merged as e0178c9dc2cce3c09c7792ddff5b14f761a7d9e7. The accepted subject-focused rule is the default-branch source for this sweep. The requested boundary is to remove unnecessary self-description and document-maintenance boilerplate while preserving navigation metadata and all useful subject facts.
Acceptance criteria
- Inventory the remaining authored documentation through the README and section indexes, and review cleanup candidates in context.
- Remove unnecessary document self-description and maintenance notes. Rewrite useful scope or authority statements around the subject instead of deleting their meaning.
- Preserve front matter, navigation, links, anchors, runtime formats, requirements, mechanisms, alternatives, rationale, examples, diagrams, and evidence. Keep operational ownership, product versions, observation dates, decision status, and supersession where relevant.
- Leave
Documentation-Model.md,Evolutionary-Development.md,Spec-Driven-Development.md, andSpec-Driven-Development-Templates.mdundersrc/docs/Ways-of-Working/unchanged. Do not copy the subject-focused policy into other pages or manage Documentation bodies focus on their subject #293. - Keep the change limited to authored prose. Do not change product behavior, code, generated index tables, or another repository.
- Pass the applicable repository checks and record any external limitation separately from a successful check.
Technical decisions
The inventory contains 130 Markdown pages under src/docs/, with 126 remaining after the exclusions. The README, contribution guide, all section indexes, and plugin README provide the scope and navigation context. Navigation descriptions and runtime pointer/template contents remain intact.
Use small commits for related surfaces. Preserve existing headings and all machine-readable content. Use existing Markdown lint, link checks, Pester suites, and Zensical; do not add prose-string tests or new tooling. The sweep starts from the accepted #293 merge and applies its canonical subject-focused rule without changing the four excluded pages. This Task stays open for review and merge. The assigned owner verifies normal Pages publication after merge; source verification alone does not establish publication.
Implementation plan
- Read repository entry points and all section indexes; confirm the earlier pull request's live state.
- Establish the baseline: local links resolve across 130 pages, and Markdown lint examines all 130 pages without findings. Use explicit file paths because a Windows-style glob matched no files.
- Apply minimal, context-reviewed prose edits to coding standards (commit
9c91d1b). - Apply minimal, context-reviewed prose edits to ways of working and section introductions (commit
3e0dba6). - Apply minimal, context-reviewed prose edits to capability documentation (commit
51db56a). - Verify preservation of front matter, headings, link targets, code fences, generated index regions, and the four excluded files. The audit passes for all 53 changed pages, including unchanged tables, inline code, HTML anchors, and diagrams.
- Run Markdown lint (130 pages), local links (130 pages), cross-repository links (8 targets across 134 Markdown files), all six Pester suites (66 passed; none failed or skipped), and the exact Zensical 0.0.59 build (no issues).
- Inspect the complete diff, record standards alignment and issue-convergence evidence, and preserve the result in three focused commits and the draft delivery pull request. Final-commit CI is green; the explicit Copilot round approves the exact candidate with zero inline comments.
Activity
MariusStorhaug commentedon Nov 12, 2026
Source-state update: verified that #293 merged as e0178c9. The published Documentation Model now contains the accepted subject-focused rule. The sweep scope and four excluded pages are unchanged.
MariusStorhaug commentedon Nov 12, 2026
Completed the coding-standard slice in commit 9c91d1b and opened the draft delivery pull request. Changed-file Markdown lint, local links across 130 pages, and all 8 cross-repository links pass. The plan now tracks the three existing content surfaces separately; scope is unchanged.
MariusStorhaug commentedon Nov 12, 2026
Completed the workflow and section-introduction slice in commit 3e0dba6. All 23 changed files pass Markdown lint; local links still resolve across all 130 pages. Scope, source authority, target-state versus deployment evidence, and generated navigation remain intact.
MariusStorhaug commentedon Nov 12, 2026
Completed the capability slice in commit 51db56a and pushed the complete 53-page sweep. All local checks pass. The installed Zensical 0.0.50 was not accepted as pinned-toolchain evidence; an isolated session environment built the site with the required 0.0.59 and reported no issues. The preservation audit confirms unchanged front matter, headings, link targets, code fences, diagrams, tables, generated indexes, inline code, and HTML anchors across all changed pages; the four exclusions are unchanged. Final CI and the explicit Copilot review remain in progress.
MariusStorhaug commentedon Nov 12, 2026
Implementation and verification are complete at 51db56a. The draft delivery PR records the standards/domain alignment and scoped issue-convergence evidence. All final-commit CI checks pass: https://github.com/MSXOrg/docs/actions/runs/43250352973 and https://github.com/MSXOrg/docs/actions/runs/43250352618 . The explicit Copilot review approves that exact commit with zero inline comments. No additional issue fully converges. The worktree is clean and its remote branch has the same source identity. The PR remains draft; no merge or publication was performed.