From 90054745f044e3642dcf98b63af62d50dd00c1e6 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 21:42:52 +0200 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Document=20archite?= =?UTF-8?q?cture=20and=20memory=20boundaries?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 4 ++ ...ment-architecture-and-memory-boundaries.md | 51 +++++++++++++++++++ .../agentic-development/decisions/index.md | 17 +++++++ .../Capabilities/agentic-development/index.md | 1 + .../Capabilities/deployment/designs/index.md | 18 +++++++ src/docs/Capabilities/deployment/index.md | 2 +- .../Ways-of-Working/Documentation-Model.md | 26 ++++++++++ src/zensical.toml | 9 +++- 8 files changed, 126 insertions(+), 2 deletions(-) create mode 100644 src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md create mode 100644 src/docs/Capabilities/agentic-development/decisions/index.md create mode 100644 src/docs/Capabilities/deployment/designs/index.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23c45ed..4a65770 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,6 +78,10 @@ index and drill down to the right page. Three conventions make that work. `src/zensical.toml`, and fills every index in place. CI runs the same script with `-Check` and fails if an index is out of date. +Choose a page's home by subject first, then by the artifact that answers the reader's +question. The [Documentation Model](https://msxorg.github.io/docs/Ways-of-Working/Documentation-Model/#architecture-and-classification) +defines those artifact tiers and the deliberate use of minimal OKF-style front matter. + Links are validated the same way: `.github/scripts/Test-DocumentationLink.ps1` checks that every relative link and heading anchor across the docs resolves, and `.github/scripts/Test-CrossRepositoryLink.ps1` resolves every link into another MSX diff --git a/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md new file mode 100644 index 0000000..62938f2 --- /dev/null +++ b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md @@ -0,0 +1,51 @@ +--- +title: Document architecture and memory boundaries +description: The topic-and-artifact documentation model, minimal OKF-style metadata, and separate durable memory repository. +--- + +# Document architecture and memory boundaries + +## Context + +MSX needs documentation that humans and agents can navigate cheaply, thin agent +configuration that points to canonical knowledge, and a shared place for +durable lessons. Issue [MSXOrg/docs#10](https://github.com/MSXOrg/docs/issues/10) +proposed Diataxis, the Open Knowledge Format (OKF), and a writable `brain/` +area in this repository to meet those needs. + +## Decision + +MSX uses the [Documentation Model](../../../Ways-of-Working/Documentation-Model.md) +as the documentation architecture: + +- Paths are topic- and scope-oriented, and every area is navigated through + `index.md`. +- The spec, design, guide, reference, decision-record, and research artifact + tiers classify content by the reader's need. +- Pages use the minimal OKF-style model: Markdown, YAML `title` and + `description` front matter, one primary concept per page, and stable paths. +- `MSXOrg/docs` remains the reviewed, pull-request-only canonical knowledge + base. Durable working knowledge belongs in the separate private + `MSXOrg/memory` repository; session notes remain local and ignored. + +MSX does not add Diataxis quadrant directories or `diataxis` metadata. The +artifact tiers already route the same reader needs while keeping related +subject matter together. MSX also does not adopt strict OKF conformance fields +or per-area `log.md` files: the only metadata queried by navigation is title +and description, and Git history is the authoritative change log. + +## Consequences + +Contributors file a page by subject and artifact tier, then run the index +generator. Readers and agents traverse the same indexes without loading an +unrelated quadrant. Tooling validates the metadata it consumes and validates +links, while review keeps page boundaries and cross-references coherent. + +Agents propose changes to canonical documentation through pull requests. +Agents commit durable, factual lessons to `MSXOrg/memory` under its +[memory-writing rules](../design.md#memory-writing-rules); they never use this +public documentation repository as a low-ceremony dump. + +This decision resolves the architecture questions in +[MSXOrg/docs#10](https://github.com/MSXOrg/docs/issues/10). Future changes to +these boundaries require a new decision record that supersedes this one. diff --git a/src/docs/Capabilities/agentic-development/decisions/index.md b/src/docs/Capabilities/agentic-development/decisions/index.md new file mode 100644 index 0000000..4d64238 --- /dev/null +++ b/src/docs/Capabilities/agentic-development/decisions/index.md @@ -0,0 +1,17 @@ +--- +title: Agentic Development decisions +description: Immutable records of one-way-door choices in the agentic development framework. +--- + +# Agentic Development decisions + +These records explain choices that constrain the framework. A later decision +supersedes an earlier one; it does not rewrite it. + + + +| Page | Description | +| --- | --- | +| [Document architecture and memory boundaries](document-architecture-and-memory-boundaries.md) | The topic-and-artifact documentation model, minimal OKF-style metadata, and separate durable memory repository. | + + diff --git a/src/docs/Capabilities/agentic-development/index.md b/src/docs/Capabilities/agentic-development/index.md index 8cd8142..a314d49 100644 --- a/src/docs/Capabilities/agentic-development/index.md +++ b/src/docs/Capabilities/agentic-development/index.md @@ -22,5 +22,6 @@ A repository adopts the framework by carrying a short router and the client rout | [Agent Interaction](agent-interaction.md) | How humans and agents coordinate through issues, labels, and pull requests, and why intent and implementation are kept in separate artifacts. | | [Advisory Agents](advisory-agents.md) | The pattern for automation that analyses work and publishes its conclusion as advice, without deciding, relabelling, or committing. | | [Conformance](conformance.md) | What a repository must provide to be conformant with the agentic development framework, what it may add, and the duplication checks that keep the router thin. | +| [Agentic Development decisions](decisions/index.md) | Immutable records of one-way-door choices in the agentic development framework. | diff --git a/src/docs/Capabilities/deployment/designs/index.md b/src/docs/Capabilities/deployment/designs/index.md new file mode 100644 index 0000000..a70afcb --- /dev/null +++ b/src/docs/Capabilities/deployment/designs/index.md @@ -0,0 +1,18 @@ +--- +title: Deployment designs +description: How the deployment contract is delivered for each service-provider and CI/CD-platform combination. +--- + +# Deployment designs + +Each page in this section delivers the [Deployment spec](../spec.md) for one +service-provider and CI/CD-platform combination. Add a design here without +changing the technology-agnostic contract. + + + +| Page | Description | +| --- | --- | +| [Deploying Azure from GitHub](azure-from-github.md) | How the deployment spec is delivered with Azure as the service provider and GitHub as the CI/CD platform, using Terraform to compute and apply the approved effect. | + + diff --git a/src/docs/Capabilities/deployment/index.md b/src/docs/Capabilities/deployment/index.md index 8e3cd01..4514e7b 100644 --- a/src/docs/Capabilities/deployment/index.md +++ b/src/docs/Capabilities/deployment/index.md @@ -29,4 +29,4 @@ combination adds a design; it never changes the spec. | Design | Service provider | CI/CD platform | Description | | --- | --- | --- | --- | -| [Deploying Azure from GitHub](designs/azure-from-github.md) | Azure | GitHub | GitHub Actions and Terraform deploy Azure and Entra resources with passwordless identity, approving the code change together with its per-environment effect. | +| [Designs](designs/index.md) | — | — | Deployment designs, one for each service-provider and CI/CD-platform combination. | diff --git a/src/docs/Ways-of-Working/Documentation-Model.md b/src/docs/Ways-of-Working/Documentation-Model.md index a39b96d..54e6407 100644 --- a/src/docs/Ways-of-Working/Documentation-Model.md +++ b/src/docs/Ways-of-Working/Documentation-Model.md @@ -176,6 +176,32 @@ being long. describe. Laziness is a design constraint — the less a reader must travel, the more they actually read. +## Architecture and classification + +The documentation tree is organized **by scope and subject**, then by the +artifact that answers the reader's question. A reader starts at the root +`index.md`, chooses the relevant topic, and follows that topic's index inward. +This keeps related material together without requiring a reader to decide +whether they need a tutorial, guide, reference, or explanation before they can +find the subject. + +The artifact tiers provide the second classification: + +| Reader need | Owning artifact | +| --- | --- | +| Understand why a capability exists and what it guarantees | Spec | +| Understand how the capability is delivered | Design | +| Perform a task against a capability | Guide | +| Look up stable facts or values | Reference | +| Understand a one-way-door choice | Decision record | +| Revisit point-in-time findings | Research | + +This maps the useful reader needs behind Diataxis without imposing a second, +parallel taxonomy in paths or front matter. A page has one home under its +subject and links to adjacent artifacts rather than being duplicated across +quadrants. [Document architecture and memory boundaries](../Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md) +records that decision and the corresponding OKF and memory boundaries. + ## For humans and agents The same pages serve both. A contributor reads the index, follows the diff --git a/src/zensical.toml b/src/zensical.toml index 21bcc05..087c278 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -152,7 +152,10 @@ nav = [ {"Deployment" = [ "Capabilities/deployment/index.md", {"Spec" = "Capabilities/deployment/spec.md"}, - {"Deploying Azure from GitHub" = "Capabilities/deployment/designs/azure-from-github.md"}, + {"Designs" = [ + "Capabilities/deployment/designs/index.md", + {"Deploying Azure from GitHub" = "Capabilities/deployment/designs/azure-from-github.md"}, + ]}, ]}, {"VS Code Extension Framework" = [ "Capabilities/vscode-extension-framework/index.md", @@ -175,6 +178,10 @@ nav = [ {"Agent Interaction" = "Capabilities/agentic-development/agent-interaction.md"}, {"Advisory Agents" = "Capabilities/agentic-development/advisory-agents.md"}, {"Conformance" = "Capabilities/agentic-development/conformance.md"}, + {"Decisions" = [ + "Capabilities/agentic-development/decisions/index.md", + {"Document Architecture and Memory Boundaries" = "Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md"}, + ]}, ]}, ]}, {"Dictionary" = "Dictionary/index.md"}, From 765e9d421980551f89013b36c567292e8f7352ed Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 21:48:24 +0200 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Use=20preferred=20?= =?UTF-8?q?changelog=20spelling?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../decisions/document-architecture-and-memory-boundaries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md index 62938f2..24ff815 100644 --- a/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md +++ b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md @@ -32,7 +32,7 @@ MSX does not add Diataxis quadrant directories or `diataxis` metadata. The artifact tiers already route the same reader needs while keeping related subject matter together. MSX also does not adopt strict OKF conformance fields or per-area `log.md` files: the only metadata queried by navigation is title -and description, and Git history is the authoritative change log. +and description, and Git history is the authoritative changelog. ## Consequences From 838eb0522154e711cf61cc757e1fedccb34e3317 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 21:54:55 +0200 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Keep=20architectur?= =?UTF-8?q?e=20decision=20evergreen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../document-architecture-and-memory-boundaries.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md index 24ff815..0981d59 100644 --- a/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md +++ b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md @@ -7,11 +7,10 @@ description: The topic-and-artifact documentation model, minimal OKF-style metad ## Context -MSX needs documentation that humans and agents can navigate cheaply, thin agent -configuration that points to canonical knowledge, and a shared place for -durable lessons. Issue [MSXOrg/docs#10](https://github.com/MSXOrg/docs/issues/10) -proposed Diataxis, the Open Knowledge Format (OKF), and a writable `brain/` -area in this repository to meet those needs. +MSX documentation is navigable cheaply by humans and agents, agent +configuration points to canonical knowledge, and durable lessons have a shared +home. The architecture establishes those boundaries without duplicating +documentation across classifications or repositories. ## Decision @@ -46,6 +45,4 @@ Agents commit durable, factual lessons to `MSXOrg/memory` under its [memory-writing rules](../design.md#memory-writing-rules); they never use this public documentation repository as a low-ceremony dump. -This decision resolves the architecture questions in -[MSXOrg/docs#10](https://github.com/MSXOrg/docs/issues/10). Future changes to -these boundaries require a new decision record that supersedes this one. +Changes to these boundaries use a new decision record that supersedes this one.