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..0981d59 --- /dev/null +++ b/src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md @@ -0,0 +1,48 @@ +--- +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 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 + +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 changelog. + +## 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. + +Changes to these boundaries use 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"},