From 9c91d1b62b9a3ae78bb0c55e74e1e82c0c6853a1 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 12 Nov 2026 16:26:57 +0100 Subject: [PATCH 1/3] Coding standards lead with their rules and contracts --- src/docs/Coding-Standards/GitHub-Actions.md | 23 ++++++++----------- src/docs/Coding-Standards/Markdown.md | 6 ++--- src/docs/Coding-Standards/Naming.md | 2 +- src/docs/Coding-Standards/Natural-Language.md | 2 +- .../Coding-Standards/PowerShell/Messaging.md | 4 ++-- .../PowerShell/Requires-Modules.md | 2 +- .../PowerShell/Version-Constraints.md | 2 +- src/docs/Coding-Standards/PowerShell/index.md | 8 +++---- src/docs/Coding-Standards/Terraform.md | 2 +- src/docs/Coding-Standards/Testing.md | 2 +- src/docs/Coding-Standards/TypeScript.md | 2 +- src/docs/Coding-Standards/YAML.md | 4 ++-- 12 files changed, 27 insertions(+), 32 deletions(-) diff --git a/src/docs/Coding-Standards/GitHub-Actions.md b/src/docs/Coding-Standards/GitHub-Actions.md index 4b532f4..8b2c2de 100644 --- a/src/docs/Coding-Standards/GitHub-Actions.md +++ b/src/docs/Coding-Standards/GitHub-Actions.md @@ -5,16 +5,14 @@ description: Workflow authoring — SHA pinning, least-privilege permissions, OI # GitHub Actions -This standard defines how authors write GitHub Actions workflows across the -ecosystem. Workflows run with access to credentials and can publish artifacts. -Workflow authors apply the application-code standards and the supply-chain and -least-privilege controls below. +GitHub Actions workflows can access credentials and publish artifacts. +Workflow authors across the ecosystem apply the application-code standards and +the supply-chain and least-privilege controls below. -This standard builds on the [language-agnostic baseline](index.md). For the +Workflow-authoring rules extend the [language-agnostic baseline](index.md). For the threat model behind action pinning and vendoring, see [Security → Supply chain](Security.md#supply-chain). -This standard is the canonical workflow-authoring reference for that security -control. +The workflow-specific requirements below apply that supply-chain control. ## Pin actions according to ownership @@ -89,7 +87,6 @@ major without individual pin-update pull requests. The [Dependency Updates](../Capabilities/dependency-updates/design.md) capability defines the schedule, cooldown, and merge policy. -This section defines the Actions-specific requirements. ### Audit and synchronize pins manually @@ -551,7 +548,6 @@ Read `needs:` and `if:` together during review. Steps in a job run in sequence by default. Each step starts after the preceding step finishes. -The rest of this section uses that sequential model. **Concurrent steps** run within a single job through these workflow keywords: - `background: true` starts a step asynchronously and continues to the @@ -979,15 +975,15 @@ Their configuration derives from the rules above, which are the source of truth: Its [ShellCheck integration](https://github.com/rhysd/actionlint/blob/main/docs/checks.md#check-shellcheck-integ) checks inline Bash and sh `run:` scripts when enabled and ShellCheck is available. It does not check PowerShell or Python through ShellCheck. -- **[zizmor](https://docs.zizmor.sh/)** audits workflow security, flagging the - failures this standard exists to prevent: unpinned actions, excessive - `permissions`, template injection from untrusted input, `secrets: inherit`, +- **[zizmor](https://docs.zizmor.sh/)** audits workflow security, flagging + unpinned actions, excessive `permissions`, template injection from untrusted + input, `secrets: inherit`, and persisted credentials. Both run through [super-linter](https://github.com/super-linter/super-linter) on every push and pull request. -The linters do not detect every violation of this standard. +The linters do not detect every workflow-authoring violation. Review the authoring rules as well as the lint results. For conditional dependencies, follow the [skipped-job guidance](#a-skipped-job-in-needs-skips-everything-downstream). @@ -1369,4 +1365,3 @@ one. The [Merge Automation](../Capabilities/merge-automation/index.md) capability defines that end-to-end pattern. -This section defines its authoring requirements. diff --git a/src/docs/Coding-Standards/Markdown.md b/src/docs/Coding-Standards/Markdown.md index 77cd2f8..c313d50 100644 --- a/src/docs/Coding-Standards/Markdown.md +++ b/src/docs/Coding-Standards/Markdown.md @@ -7,11 +7,11 @@ description: GitHub Flavored Markdown authoring rules enforced by the shared mar Documentation across the ecosystem uses [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) and a **single shared `markdownlint` configuration**. Repositories consume this configuration rather than define separate formatting rules. -This standard covers the **syntax and style rules** the linter enforces. For how documentation lives next to the thing it describes, see the [Documentation](Documentation.md) baseline standard and [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md). +Markdown linting enforces **syntax and style rules**. For how documentation lives next to the thing it describes, see the [Documentation](Documentation.md) baseline standard and [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md). ## The shared configuration is the source of truth -The rules below come from `.github/linters/.markdown-lint.yml`. Markdownlint uses this configuration through super-linter at PR time and on the assembled artifact. Both runs use the **same** configuration. A successful local run covers only the examined content and enabled rules. The configuration file, not this page, is authoritative if they differ. +The rules below come from `.github/linters/.markdown-lint.yml`. Markdownlint uses this configuration through super-linter at PR time and on the assembled artifact. Both runs use the **same** configuration. A successful local run covers only the examined content and enabled rules. The configuration file is authoritative when a rule description differs. Check locally before opening a PR: @@ -64,7 +64,7 @@ These rules are disabled or widened so they do not flag valid documentation — ## Links are checked -Repositories validate the links this standard requires. This repository runs two checks on every pull request and on every push to `main`. Each check covers a different link scope. +Repositories validate relative links and in-scope cross-repository links. This repository runs two checks on every pull request and on every push to `main`. Each check covers a different link scope. **Inside a repository** — `Test-DocumentationLink.ps1` resolves every relative target and every heading anchor against the checkout. It needs no network. It fails when a target or anchor does not resolve. diff --git a/src/docs/Coding-Standards/Naming.md b/src/docs/Coding-Standards/Naming.md index 656576e..891635d 100644 --- a/src/docs/Coding-Standards/Naming.md +++ b/src/docs/Coding-Standards/Naming.md @@ -38,7 +38,7 @@ Follow the **language's conventions**, and apply them consistently within a code Solution-owned settings MUST use `.settings.yml` as their conventional filename, where `` identifies the owning solution. One naming shape makes both the owner and the file's purpose discoverable. -Each solution documents its settings location. This standard does not impose a shared directory or change settings schemas, defaults, or precedence. +Each solution documents its settings location. The filename convention does not impose a shared directory or change settings schemas, defaults, or precedence. Tool-mandated manifests, lockfiles, workflow filenames, and YAML files that are not solution-owned settings follow their tool's contract, not this settings-filename convention. diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md index 32d0a67..6c61dd3 100644 --- a/src/docs/Coding-Standards/Natural-Language.md +++ b/src/docs/Coding-Standards/Natural-Language.md @@ -7,7 +7,7 @@ description: Language choice and en-US writing for user and developer interactio Natural language gives humans and agents instructions and information. It serves user and developer interactions, issues, pull requests, documentation, prompts, comments, help, error messages, and release notes. Write it with the same care as code: clear, testable, consistent, and easy to change. -This standard defines which language each artifact is written in, and how English prose is written in the MSX ecosystem. The project dialect is **American English (`en-US`)**. +The project dialect is **American English (`en-US`)**. Reader-facing English MUST follow [ASD-STE100 Issue 9](https://doi.org/10.5281/zenodo.23666006) writing practices and use American English (`en-US`). diff --git a/src/docs/Coding-Standards/PowerShell/Messaging.md b/src/docs/Coding-Standards/PowerShell/Messaging.md index 155435f..d5c58d5 100644 --- a/src/docs/Coding-Standards/PowerShell/Messaging.md +++ b/src/docs/Coding-Standards/PowerShell/Messaging.md @@ -96,12 +96,12 @@ Invoke-RepositoryOperation ## Relationship to other messaging -This standard covers the two main diagnostic channels. For context: +Other message streams serve different purposes: - **`Write-Information`** — user-facing information outside troubleshooting. Use it for important operational summaries that should always be visible without `-Verbose`. The default `$InformationPreference` is `SilentlyContinue`, which hides these messages. `-InformationAction Continue` displays them without changing the preference. For example, "Migration complete: 42 items processed." - **`Write-Warning`** — a condition the operator should know about but that did not stop the operation; reserved for genuine warnings, not verbose narration. - **`Write-Error`** — reports a non-terminating error by default. `-ErrorAction Stop` makes the error terminating. `$ErrorActionPreference = 'Stop'` does the same unless a command-level error action overrides it. Use `[PSCustomObject]` with `-TargetObject` for structured context, or supply an error record with `-ErrorRecord`. -- **Logging (event logs, files)** — persistent audit; separate from these streams and outside the scope of this standard. +- **Logging (event logs, files)** — persistent audit, separate from these streams and their selection rules. Use each stream for its intended audience so operators and maintainers can find the messages they need. diff --git a/src/docs/Coding-Standards/PowerShell/Requires-Modules.md b/src/docs/Coding-Standards/PowerShell/Requires-Modules.md index 3c3a688..f17548a 100644 --- a/src/docs/Coding-Standards/PowerShell/Requires-Modules.md +++ b/src/docs/Coding-Standards/PowerShell/Requires-Modules.md @@ -5,7 +5,7 @@ description: Valid `#Requires -Modules` version specifications — minimum, majo # Module Requirements -Scripts and test files declare module dependencies with [`#Requires -Modules`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_requires). The value is a module name or a **module-specification hashtable**. This page defines the version-specification forms and when to use them. [Security → Supply chain](../Security.md#supply-chain) explains the rationale. [Scripts](Scripts.md) and [Functions](Functions.md) define placement within each construct. +Scripts and test files declare module dependencies with [`#Requires -Modules`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_requires). The value is a module name or a **module-specification hashtable**. [Security → Supply chain](../Security.md#supply-chain) explains the rationale. [Scripts](Scripts.md) and [Functions](Functions.md) define placement within each construct. ## Valid version specifications diff --git a/src/docs/Coding-Standards/PowerShell/Version-Constraints.md b/src/docs/Coding-Standards/PowerShell/Version-Constraints.md index 4734876..4cd9106 100644 --- a/src/docs/Coding-Standards/PowerShell/Version-Constraints.md +++ b/src/docs/Coding-Standards/PowerShell/Version-Constraints.md @@ -7,7 +7,7 @@ description: "Express module and package version constraints as NuGet version ra A version constraint specifies which dependency versions are acceptable. PowerShell exposes several interfaces: an `Install-PSResource` call, a `#Requires` line, a module manifest, or a `.csproj`. These interfaces do not all accept the same string. Express constraints in **one** notation: the [NuGet version range](https://learn.microsoft.com/nuget/concepts/package-versioning#version-ranges). The install tooling ([PSResourceGet](https://learn.microsoft.com/powershell/module/microsoft.powershell.psresourceget/)) and .NET package references use it natively. It follows [SemVer](https://semver.org/) and makes minimums, maximums, exact pins, and ranges explicit for review. -This page applies the [Dependencies](../Dependencies.md) standard to PowerShell. That standard defines the locking spectrum and the balance between update speed and supply-chain risk. This page defines the PowerShell syntax for each constraint. It extends the [PowerShell standard](index.md), builds on [Security → Supply chain](../Security.md#supply-chain), and pairs with [Dependency Updates](../../Capabilities/dependency-updates/index.md) for pin maintenance. +The [Dependencies](../Dependencies.md) standard defines the locking spectrum and the balance between update speed and supply-chain risk. PowerShell constraint syntax extends the [PowerShell standard](index.md), builds on [Security → Supply chain](../Security.md#supply-chain), and pairs with [Dependency Updates](../../Capabilities/dependency-updates/index.md) for pin maintenance. ## The rule diff --git a/src/docs/Coding-Standards/PowerShell/index.md b/src/docs/Coding-Standards/PowerShell/index.md index 8f27d5d..c818e4f 100644 --- a/src/docs/Coding-Standards/PowerShell/index.md +++ b/src/docs/Coding-Standards/PowerShell/index.md @@ -7,7 +7,7 @@ description: Cross-platform PowerShell 7 — the conventions shared by every scr PowerShell is the tool for operational automation: platform API calls, cross-platform task orchestration, and tool integration. The target is **PowerShell 7 LTS**, the cross-platform `pwsh`. Use PowerShell's advanced-function features rather than plain scripts. -This standard builds on the [language-agnostic baseline](../index.md). Where the two overlap, the baseline rules apply and this standard adds PowerShell-specific conventions. This page contains the shared conventions. Separate pages define documentation requirements, formatting, and section structure for functions, classes, and scripts. +PowerShell-specific conventions extend the [language-agnostic baseline](../index.md). Where the rules overlap, the baseline rules apply. Functions, classes, and scripts have additional documentation, formatting, and section-structure requirements. @@ -48,7 +48,7 @@ These hold for all PowerShell, whatever the construct: ## Formatting -These rules define the layout. [PSScriptAnalyzer](#toolchain) checks the configured rules; its settings derive from this standard, not the reverse. Write code to the rules and let the formatter apply them: +These rules define the layout. [PSScriptAnalyzer](#toolchain) checks the configured rules; its settings derive from these rules, not the reverse. Write code to the rules and let the formatter apply them: - **One True Brace Style (OTBS).** Put the opening brace on the statement line and the closing brace on its own line. Always brace control blocks, even a single statement. Do not put a blank line directly after `{` or before `}`. Put `else` / `elseif` / `catch` / `finally` on the line with the preceding closing brace. - **Indent with four spaces, never tabs**, and indent comment-based help to align with the function it documents. @@ -80,7 +80,7 @@ Beyond the basics, these language-specific habits keep PowerShell correct and fa ## Toolchain -The toolchain checks this standard in CI; it does not define it. The rules above are the source of truth. Tool configurations derive from them: +The PowerShell rules are the source of truth. The toolchain checks them in CI with configurations derived from those rules: -- **[PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer)** is the linter and formatter. Its settings derive from this standard. Use the formatter rather than formatting code by hand. +- **[PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer)** is the linter and formatter. Its settings derive from the PowerShell rules. Use the formatter rather than formatting code by hand. - **[Pester](https://pester.dev/)** is the test framework; test files are named `*.Tests.ps1`. See [PowerShell Testing](Testing.md) for module test layouts. diff --git a/src/docs/Coding-Standards/Terraform.md b/src/docs/Coding-Standards/Terraform.md index 49c044b..5278344 100644 --- a/src/docs/Coding-Standards/Terraform.md +++ b/src/docs/Coding-Standards/Terraform.md @@ -7,7 +7,7 @@ description: Stack layout, version pinning, state and secrets, and the fmt/valid Terraform provisions cloud infrastructure as code. Infrastructure changes follow the same review and approval gates as application code. See [Decision before change](../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change). -This standard builds on the [language-agnostic baseline](index.md). Where the two overlap, the baseline rules apply and this standard adds Terraform-specific conventions. +Terraform-specific conventions extend the [language-agnostic baseline](index.md). Where the rules overlap, the baseline rules apply. ## Stack layout diff --git a/src/docs/Coding-Standards/Testing.md b/src/docs/Coding-Standards/Testing.md index 66be727..042b7aa 100644 --- a/src/docs/Coding-Standards/Testing.md +++ b/src/docs/Coding-Standards/Testing.md @@ -5,7 +5,7 @@ description: Prove supported behavior through real entry points and APIs, with j # Testing -Tests are executable specifications. They define intended behavior, verify its implementation, and detect regressions. This page owns the testing policy; language standards and agent skills build on it or link to it rather than define another one. +Tests are executable specifications. They define intended behavior, verify its implementation, and detect regressions. Language standards and agent skills extend or link to the shared testing policy rather than define separate policies. ## Test supported behavior diff --git a/src/docs/Coding-Standards/TypeScript.md b/src/docs/Coding-Standards/TypeScript.md index 4e0c25b..41cab43 100644 --- a/src/docs/Coding-Standards/TypeScript.md +++ b/src/docs/Coding-Standards/TypeScript.md @@ -7,7 +7,7 @@ description: ES modules, strict-mode typing, pinned dependencies, and the Pretti TypeScript is the language for Node-based tooling, GitHub Actions written in JavaScript, and **VS Code extensions**. Target the **latest stable TypeScript** on **Node.js Active LTS**. Use **ES modules** and require the compiler's strict mode. -This standard builds on the [language-agnostic baseline](index.md). Where the two overlap, the baseline rules apply and this standard adds TypeScript-specific conventions. +TypeScript-specific conventions extend the [language-agnostic baseline](index.md). Where the rules overlap, the baseline rules apply. ## Project shape diff --git a/src/docs/Coding-Standards/YAML.md b/src/docs/Coding-Standards/YAML.md index f0e8609..e0f51bb 100644 --- a/src/docs/Coding-Standards/YAML.md +++ b/src/docs/Coding-Standards/YAML.md @@ -9,8 +9,8 @@ YAML defines workflows, linter configurations, dependency manifests, and deploym descriptors. Valid YAML syntax can still produce unintended values. Use linting rather than visual review alone. -This standard builds on the [language-agnostic baseline](index.md). Where the two -overlap, the baseline rule applies and this standard adds YAML-specific conventions. +YAML-specific conventions extend the [language-agnostic baseline](index.md). +Where the rules overlap, the baseline rule applies. ## Use `.yml` consistently From 3e0dba6b116a01ebb3e81ee1733cc5f08c636c20 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 12 Nov 2026 16:31:43 +0100 Subject: [PATCH 2/3] Workflow and navigation prose describes the work --- src/docs/Dictionary/index.md | 2 +- src/docs/Initiatives/index.md | 4 ++-- src/docs/Vision/index.md | 2 +- src/docs/Ways-of-Working/Branching-and-Merging.md | 4 ++-- .../Comparative-Review-Orchestration.md | 11 +++++------ .../Continuous-Delivery-And-Release.md | 1 - src/docs/Ways-of-Working/Continuous-Practices.md | 2 -- src/docs/Ways-of-Working/DevOps-Reference.md | 4 ---- src/docs/Ways-of-Working/Issues/Process/Lifecycle.md | 2 +- src/docs/Ways-of-Working/Issues/Process/index.md | 2 +- src/docs/Ways-of-Working/Issues/Types/index.md | 2 +- src/docs/Ways-of-Working/Issues/index.md | 2 -- src/docs/Ways-of-Working/Organization-Standard.md | 8 ++++---- src/docs/Ways-of-Working/PR-Format.md | 2 +- .../Principles/Engineering-Practices.md | 2 +- src/docs/Ways-of-Working/Principles/index.md | 2 +- src/docs/Ways-of-Working/Repository-Standard.md | 4 ++-- src/docs/Ways-of-Working/Repository-Type-Property.md | 2 +- .../Workflow-Stages/Maintain-Guidance.md | 4 ++-- src/docs/Ways-of-Working/Workflow-Stages/index.md | 2 +- src/docs/Ways-of-Working/Workflow.md | 2 +- src/docs/Ways-of-Working/index.md | 4 ++-- src/docs/index.md | 2 +- 23 files changed, 31 insertions(+), 41 deletions(-) diff --git a/src/docs/Dictionary/index.md b/src/docs/Dictionary/index.md index f7880e3..814b82e 100644 --- a/src/docs/Dictionary/index.md +++ b/src/docs/Dictionary/index.md @@ -5,7 +5,7 @@ description: Shared terms and definitions for the MSX ecosystem. # Dictionary -This dictionary defines shared terms for readers and agents across the MSX ecosystem. Ecosystem-specific terms link to their detailed documentation. +Readers and agents use shared terms across the MSX ecosystem. Ecosystem-specific terms link to their detailed documentation. ## Terms diff --git a/src/docs/Initiatives/index.md b/src/docs/Initiatives/index.md index 42dfe46..4e2357b 100644 --- a/src/docs/Initiatives/index.md +++ b/src/docs/Initiatives/index.md @@ -11,7 +11,7 @@ Each **initiative** is a product that applies the vision through a framework, re Initiatives inherit the vision, principles, ways of working, and coding standards from this site. Products can change or retire without changing these shared principles. -These pages describe the target roles and contracts of the initiatives. They do not establish which products or controls are deployed. +Target-state roles and contracts are not evidence of deployed products or controls. @@ -39,4 +39,4 @@ Each initiative references these principles instead of restating them. Ideas beg ## A living map -Each initiative links to the [Vision](../Vision/index.md) for its purpose and shared principles. Initiative pages describe the corresponding products and link to their canonical documentation. +Each initiative follows the [Vision](../Vision/index.md) for its purpose and shared principles. Product details remain in the initiative's canonical documentation. diff --git a/src/docs/Vision/index.md b/src/docs/Vision/index.md index 421ccb0..87ed521 100644 --- a/src/docs/Vision/index.md +++ b/src/docs/Vision/index.md @@ -7,7 +7,7 @@ description: The mission and the philosophy of easy, fast, and safe. MSX exists to make great software delivery the **default** — easy, fast, and safe — for every developer and every agent. -This page states the **why** behind MSX. Products, languages, and tools change; the mission remains stable. The [Ways of Working](../Ways-of-Working/index.md), [Coding Standards](../Coding-Standards/index.md), and [Initiatives](../Initiatives/index.md) follow this mission. +Products, languages, and tools change; the mission remains stable. The [Ways of Working](../Ways-of-Working/index.md), [Coding Standards](../Coding-Standards/index.md), and [Initiatives](../Initiatives/index.md) follow this mission. ## Start with Why diff --git a/src/docs/Ways-of-Working/Branching-and-Merging.md b/src/docs/Ways-of-Working/Branching-and-Merging.md index f28a85f..b3f44ff 100644 --- a/src/docs/Ways-of-Working/Branching-and-Merging.md +++ b/src/docs/Ways-of-Working/Branching-and-Merging.md @@ -92,8 +92,8 @@ It adds unnecessary work where every merge already releases the change. The protected branch's ruleset defines the conditions each pull request must satisfy before merge. These include **required status checks**, **required approvals**, and any other configured requirement, such as conversation resolution or signed commits. A pull request cannot merge until all required conditions are satisfied, regardless of its readiness state. -The ruleset is configured in repository settings, not in these files. -This section defines what the ruleset must enforce; it does not configure those settings. +The ruleset configuration lives in repository settings. +Written requirements do not configure or enforce those settings. Use auto-merge by default. A ready pull request with auto-merge enabled squash-merges only after every required condition is satisfied. diff --git a/src/docs/Ways-of-Working/Comparative-Review-Orchestration.md b/src/docs/Ways-of-Working/Comparative-Review-Orchestration.md index 02a2fd1..1ff48a1 100644 --- a/src/docs/Ways-of-Working/Comparative-Review-Orchestration.md +++ b/src/docs/Ways-of-Working/Comparative-Review-Orchestration.md @@ -9,17 +9,16 @@ A comparative review compares a target with authoritative reference sources. Examples include a repository against a standard, an implementation against a sibling implementation, or a capability against its specification. -This playbook gives humans and agents the same process for review evidence and -small, independently actionable issues. Source evidence distinguishes required -changes from accepted differences. +Humans and agents use the same evidence process to produce small, independently +actionable issues. Source evidence distinguishes required changes from accepted +differences. The target, references, and domain are **inputs**. The process does not depend on a particular target or domain. ## Purpose and scope -Reviewers follow this playbook to frame, execute, and close a comparative review. -Its scope includes: +A comparative review includes: - Explicit review inputs **before** investigation starts. - Small, independently fixable issues based on evidence. @@ -172,4 +171,4 @@ Each of these MUST hold at closeout: - [Issue Planning](Issues/Process/Planning.md) — how the filed issues are sized and ordered afterwards. - [Definition of Ready and Done](Definition-of-Ready-and-Done.md) — the readiness bar a filed issue must clear. - [Review Etiquette](Review-Etiquette.md) — the tone and severity conventions the findings are written in. -- [Spec-Driven Development Templates](Spec-Driven-Development-Templates.md) — the orchestration playbook skeleton this page is an instance of. +- [Spec-Driven Development Templates](Spec-Driven-Development-Templates.md) — the canonical orchestration playbook structure. diff --git a/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md b/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md index c22c19b..aa61485 100644 --- a/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md +++ b/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md @@ -10,7 +10,6 @@ release describe different automation boundaries. These boundaries determine whe human approval is required, what the pipeline can do automatically, and when a change is complete. -This page defines those boundaries and their design decisions. [Continuous Practices](Continuous-Practices.md) describes the wider family of always-on practices and the origin of each term. diff --git a/src/docs/Ways-of-Working/Continuous-Practices.md b/src/docs/Ways-of-Working/Continuous-Practices.md index 3821b05..12ea792 100644 --- a/src/docs/Ways-of-Working/Continuous-Practices.md +++ b/src/docs/Ways-of-Working/Continuous-Practices.md @@ -5,8 +5,6 @@ description: The Continuous X family, Continuous AI, and the DevOps Dojo pillars # Continuous Practices -This page describes the "Continuous X" practices, how Continuous AI extends them, and their sources. - ## 1. The "Continuous X" Practices ### Microsoft DevOps Dojo's eight pillars (White Belt) diff --git a/src/docs/Ways-of-Working/DevOps-Reference.md b/src/docs/Ways-of-Working/DevOps-Reference.md index 716c9e4..559c3b0 100644 --- a/src/docs/Ways-of-Working/DevOps-Reference.md +++ b/src/docs/Ways-of-Working/DevOps-Reference.md @@ -5,10 +5,6 @@ description: A curated reading list and the principles behind the way of working # DevOps Reference -This reference connects DevOps sources, frameworks, and engineering practices. - ---- - ## 1. Essential Reading List ### The Canon (Books) diff --git a/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md b/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md index e4f0b0c..395222f 100644 --- a/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md +++ b/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md @@ -5,7 +5,7 @@ description: How issue bodies, types, readiness, and relationships evolve throug # Issue Lifecycle -[Workflow](../../Workflow.md) is the sole definition of the Capture, Refine, Plan, Build, Review, Ship, and Operate phases. This page maps only how an issue's body, native type, readiness, and relationships evolve while work passes through those phases. +[Workflow](../../Workflow.md) is the sole definition of the Capture, Refine, Plan, Build, Review, Ship, and Operate phases. An issue's body, native type, readiness, and relationships evolve with those phases as follows. | Workflow phase | Issue evolution | | --- | --- | diff --git a/src/docs/Ways-of-Working/Issues/Process/index.md b/src/docs/Ways-of-Working/Issues/Process/index.md index ee4ad40..2e5b006 100644 --- a/src/docs/Ways-of-Working/Issues/Process/index.md +++ b/src/docs/Ways-of-Working/Issues/Process/index.md @@ -5,7 +5,7 @@ description: How issue bodies, planning, lifecycle, and native relationships sup # Issue Process -How issue bodies, planning, lifecycle, and native relationships support delivery. +Issue bodies, planning, lifecycle, and native relationships support delivery. diff --git a/src/docs/Ways-of-Working/Issues/Types/index.md b/src/docs/Ways-of-Working/Issues/Types/index.md index f56b94a..2ff47cd 100644 --- a/src/docs/Ways-of-Working/Issues/Types/index.md +++ b/src/docs/Ways-of-Working/Issues/Types/index.md @@ -5,7 +5,7 @@ description: The operational issue hierarchy from delivery work to strategic agg # Issue Types -How native issue types organize delivery and aggregation. +Native issue types organize delivery and aggregation. diff --git a/src/docs/Ways-of-Working/Issues/index.md b/src/docs/Ways-of-Working/Issues/index.md index 7f78e47..e5f0cab 100644 --- a/src/docs/Ways-of-Working/Issues/index.md +++ b/src/docs/Ways-of-Working/Issues/index.md @@ -5,8 +5,6 @@ description: How issues are formatted and organized across the MSX ecosystem. # Issues -Guidance for how issues are formatted and organized across the MSX ecosystem. - Start with [Issue Planning](Process/Planning.md) to separate Epic/PBI consumer expectations from Task/Bug technical delivery plans, then follow the native type and process pages below. diff --git a/src/docs/Ways-of-Working/Organization-Standard.md b/src/docs/Ways-of-Working/Organization-Standard.md index b921a09..db72526 100644 --- a/src/docs/Ways-of-Working/Organization-Standard.md +++ b/src/docs/Ways-of-Working/Organization-Standard.md @@ -5,9 +5,9 @@ description: What every initiative organization must define centrally so humans # Organization Standard -An MSX initiative organization contains repositories that share one way of working. This standard defines what each repository can expect from the organization. It identifies the source of truth and the files that the organization must manage consistently. +An MSX initiative organization contains repositories that share one way of working. Each repository can expect a shared source of truth and files that the organization must manage consistently. -This page owns the **why** and **what**. Initiative repositories own the implementation design: how they distribute files, which automation enforces the contract, and how exceptions are handled. +Organization requirements cover the **why** and **what**. Initiative repositories own the implementation design: how they distribute files, which automation enforces the contract, and how exceptions are handled. ## Required organization docs @@ -188,8 +188,8 @@ canonical standards. ## Where this connects - [Repository Standard](Repository-Standard.md) — the repository-level contract every repository must satisfy. -- [Repository Type Property](Repository-Type-Property.md) — the concrete `Type` custom-property mechanism that implements "repository types" and "required custom properties, branch protection" from this page. -- [Repository Governance](../Capabilities/repository-governance/index.md) — the classification, ruleset, required-file, exemption, and reconciliation machinery that puts this standard in force. +- [Repository Type Property](Repository-Type-Property.md) — the concrete `Type` custom-property mechanism for repository types, required custom properties, and branch protection. +- [Repository Governance](../Capabilities/repository-governance/index.md) — the classification, ruleset, required-file, exemption, and reconciliation machinery that enforces organization requirements. - [Repository Segmentation](Repository-Segmentation.md) — where a repository's boundary falls, which is what gets classified. - [Automation Labels](Automation-Labels.md) — the label vocabulary organization automation reads and writes. - [Documentation Model](Documentation-Model.md) — why specs own why and what, while designs own implementation. diff --git a/src/docs/Ways-of-Working/PR-Format.md b/src/docs/Ways-of-Working/PR-Format.md index c741204..d393ac8 100644 --- a/src/docs/Ways-of-Working/PR-Format.md +++ b/src/docs/Ways-of-Working/PR-Format.md @@ -23,7 +23,7 @@ requires it. [Resource documentation](Documentation-Model.md#current-product-gui describes supported target-state behavior and usage, not release-specific transitions or history. -This page owns the title and description format. The +The title and description use a shared format. The [Contribution Workflow](Contribution-Workflow.md) owns draft, assignment, review, and handoff mechanics; [Branching and Merging](Branching-and-Merging.md) owns branches, commits, and integration. diff --git a/src/docs/Ways-of-Working/Principles/Engineering-Practices.md b/src/docs/Ways-of-Working/Principles/Engineering-Practices.md index e891a3a..2c0a929 100644 --- a/src/docs/Ways-of-Working/Principles/Engineering-Practices.md +++ b/src/docs/Ways-of-Working/Principles/Engineering-Practices.md @@ -47,7 +47,7 @@ Documentation states the **supported target state** in the present tense. Reader A documented target-state contract is not evidence that implementation or enforcement exists. -This applies to this site, every README, and every specification. A pull request description explains the result rather than the steps used to produce it. +Shared guidance, every README, and every specification follow these evergreen rules. A pull request description explains the result rather than the steps used to produce it. ## Intent is the source of truth diff --git a/src/docs/Ways-of-Working/Principles/index.md b/src/docs/Ways-of-Working/Principles/index.md index 96213c7..7882be4 100644 --- a/src/docs/Ways-of-Working/Principles/index.md +++ b/src/docs/Ways-of-Working/Principles/index.md @@ -47,6 +47,6 @@ children: they help a reader find a page and do not claim that a child implement or governs its parent. The prohibition applies to normative dependency links, which would couple a stable principle to the changing things that apply it. -This layer explains *why* a principle applies. Standards and specifications identify the principles they follow. Readers discover those relationships from the applying layer instead of a duplicate list here. +Principles explain *why* a belief applies. Standards and specifications identify the principles they follow. Readers discover those relationships from the applying layer instead of a duplicate list in the principles. A principle MAY name another principle. References between principles are horizontal and do not create a dependency on an implementation. diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md index daf2257..46e07ac 100644 --- a/src/docs/Ways-of-Working/Repository-Standard.md +++ b/src/docs/Ways-of-Working/Repository-Standard.md @@ -9,9 +9,9 @@ A repository is the smallest unit of ownership in the MSX ecosystem. It must exp The Repository Standard is the default for every governed repository across the MSX Enterprise, regardless of initiative, organization, or technology. It defines the baseline contract a repository must meet to be understandable, secure, and maintainable on its own. -Initiative standards operate at the same altitude as this standard, not beneath it. An initiative such as PSModule adds to and adjusts these defaults for its repository types rather than merely implementing them. A repository inherits every rule this standard sets unless its initiative explicitly changes it; where an initiative standard adds or overrides a rule, the initiative standard governs that initiative's repositories. +Initiative standards operate at the same altitude as the ecosystem repository standard, not beneath it. An initiative such as PSModule adds to and adjusts these defaults for its repository types rather than merely implementing them. A repository inherits every baseline rule unless its initiative explicitly changes it; where an initiative standard adds or overrides a rule, the initiative standard governs that initiative's repositories. -This page defines the repository-level contract. Initiative documentation defines implementation details such as exact file templates, managed-file source paths, and rollout automation. +Initiative documentation owns implementation details such as exact file templates, managed-file source paths, and rollout automation. Which natural language each repository artifact is written in follows [Natural Language](../Coding-Standards/Natural-Language.md). diff --git a/src/docs/Ways-of-Working/Repository-Type-Property.md b/src/docs/Ways-of-Working/Repository-Type-Property.md index f591f67..82f6cf6 100644 --- a/src/docs/Ways-of-Working/Repository-Type-Property.md +++ b/src/docs/Ways-of-Working/Repository-Type-Property.md @@ -11,7 +11,7 @@ rules. One GitHub organization **custom property named `Type`** provides the classification mechanism. Its repository values determine which organization-wide rulesets and controls apply. -This page defines the **mechanism**: property declaration, ruleset conditions, +The classification **mechanism** uses property declarations, ruleset conditions, and safe condition changes. [Repository Types](../Capabilities/repository-governance/design-types.md) defines the individual values. [Repository Governance](../Capabilities/repository-governance/spec.md) defines the controls they select. diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md b/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md index 6c3c3ff..48394ab 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md @@ -5,7 +5,7 @@ description: Maintain the canonical Workflow stage procedures and the thin repos # Maintain Workflow Guidance -Maintain the canonical [Workflow](../Workflow.md), the stage procedures in this section, and the per-repository pointer files that lead to the documentation root. Every pointer file stays thin. This maintenance path keeps the indexes, workflow, procedures, and pointers coherent; it does not encode process knowledge in configuration. +Maintain the canonical [Workflow](../Workflow.md), its stage procedures, and the per-repository pointer files that lead to the documentation root. Every pointer file stays thin. This maintenance path keeps the indexes, workflow, procedures, and pointers coherent; it does not encode process knowledge in configuration. ## Enter this maintenance path when @@ -46,4 +46,4 @@ A repository never carries a copy of the workflow. Its `AGENTS.md` and client ro ## Where this connects - [Agentic Development](../../Capabilities/agentic-development/index.md) — the pointer model this maintains. -- [Documentation Model](../Documentation-Model.md) — how these pages stay evergreen. +- [Documentation Model](../Documentation-Model.md) — evergreen workflow guidance. diff --git a/src/docs/Ways-of-Working/Workflow-Stages/index.md b/src/docs/Ways-of-Working/Workflow-Stages/index.md index 9615069..44a3786 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/index.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/index.md @@ -5,7 +5,7 @@ description: Procedures for each stage of the canonical Workflow, reached throug # Workflow Stages -The canonical [Workflow](../Workflow.md) owns the process, stage routing, and transitions. This section contains only the procedure for each stage: its entry condition, boundary, actions, and handoff. Humans and agents follow the same pages. +The canonical [Workflow](../Workflow.md) owns the process, stage routing, and transitions. Stage procedures define each stage's entry condition, boundary, actions, and handoff. Humans and agents follow the same procedures. The default discovery trail is [Home](../../index.md) → [Ways of Working](../index.md) → [Workflow](../Workflow.md) → this stage index → the resolved procedure. A task that clearly names its action may use the [Workflow routing table](../Workflow.md#find-the-current-stage) as a shortcut. diff --git a/src/docs/Ways-of-Working/Workflow.md b/src/docs/Ways-of-Working/Workflow.md index 8bbdd3b..1369752 100644 --- a/src/docs/Ways-of-Working/Workflow.md +++ b/src/docs/Ways-of-Working/Workflow.md @@ -47,7 +47,7 @@ flowchart TD ## Find the current stage -Start from this page after following the documentation indexes: [Home](../index.md) → [Ways of Working](index.md) → Workflow. Infer the current stage from the work and its artifacts, then use the [stage procedure index](Workflow-Stages/index.md) or the direct links below. A stage is a part of this workflow, not a separate agent, skill, or instruction set. +Follow the documentation indexes: [Home](../index.md) → [Ways of Working](index.md) → Workflow. Infer the current stage from the work and its artifacts, then use the [stage procedure index](Workflow-Stages/index.md) or the direct links below. A stage is a part of this workflow, not a separate agent, skill, or instruction set. | Current work or prompt | Enter | Continue until | | --- | --- | --- | diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md index d1d2f37..c97980e 100644 --- a/src/docs/Ways-of-Working/index.md +++ b/src/docs/Ways-of-Working/index.md @@ -5,9 +5,9 @@ description: Shared principles, processes, and conventions for MSX contributors # Ways of Working -This section defines the shared principles, processes, and conventions for work across the MSX ecosystem. +Shared principles, processes, and conventions apply across the MSX ecosystem. -Use it to plan work, open issues, write commit messages, and review pull requests. +Use them to plan work, open issues, write commit messages, and review pull requests. ## Contents diff --git a/src/docs/index.md b/src/docs/index.md index cd5be8d..aa48f02 100644 --- a/src/docs/index.md +++ b/src/docs/index.md @@ -35,7 +35,7 @@ Contributors use failures to improve the system, not to assign blame. ## What this is **MSX** defines shared guidance for its GitHub organizations and repositories. -This site is the canonical source for the vision, principles, and ways of working that each MSX organization, repository, and agent inherits. +MSXOrg/docs is the canonical source for the vision, principles, and ways of working that each MSX organization, repository, and agent inherits. - The **why**: the [Vision](Vision/index.md) defines the mission and principles. - The **how**: the [Ways of Working](Ways-of-Working/index.md) and [Coding Standards](Coding-Standards/index.md) define shared processes and coding rules. From 51db56a3425f3b9a43cbc77b49f18720b09fdf8b Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 12 Nov 2026 16:40:23 +0100 Subject: [PATCH 3/3] Capability documentation leads with behavior and scope --- .../agentic-development/AGENTS.template.md | 6 +++--- .../Capabilities/agentic-development/conformance.md | 8 ++++---- src/docs/Capabilities/agentic-development/design.md | 4 ++-- .../agentic-development/plugin-distribution.md | 7 +++---- src/docs/Capabilities/agentic-development/spec.md | 4 ++-- src/docs/Capabilities/dependency-updates/design.md | 2 +- .../deployment/designs/azure-from-github.md | 2 +- src/docs/Capabilities/deployment/designs/index.md | 4 ++-- src/docs/Capabilities/deployment/spec.md | 2 +- .../downstream-release-propagation/design.md | 2 +- src/docs/Capabilities/merge-automation/design.md | 2 +- .../Capabilities/powershell-on-github/design.md | 6 +++--- .../release-management/accept-moved-release-tags.md | 5 ++--- .../release-management/design-publishing-targets.md | 4 ++-- src/docs/Capabilities/release-management/design.md | 8 ++++---- .../Capabilities/repository-governance/design.md | 13 ++++++------- .../vscode-extension-framework/design.md | 6 +++--- .../Capabilities/vscode-extension-framework/spec.md | 6 +++--- 18 files changed, 44 insertions(+), 47 deletions(-) diff --git a/src/docs/Capabilities/agentic-development/AGENTS.template.md b/src/docs/Capabilities/agentic-development/AGENTS.template.md index 8d31ad0..dfa43e7 100644 --- a/src/docs/Capabilities/agentic-development/AGENTS.template.md +++ b/src/docs/Capabilities/agentic-development/AGENTS.template.md @@ -5,9 +5,9 @@ description: The repository-level agent router template and the guidance for app # AGENTS.md Template -This document explains the repository-level `AGENTS.md` template. It is not -itself the router that agents load. Copy the contents of the fenced `markdown` -block into an `AGENTS.md` at the repository root. +A repository-level `AGENTS.md` router uses the fenced `markdown` block below, +not the surrounding guidance. Copy that block into an `AGENTS.md` at the +repository root. The router reads repository-local guidance first, initiative-specific guidance next, and central organization guidance last. diff --git a/src/docs/Capabilities/agentic-development/conformance.md b/src/docs/Capabilities/agentic-development/conformance.md index 343c9d8..1ee89ad 100644 --- a/src/docs/Capabilities/agentic-development/conformance.md +++ b/src/docs/Capabilities/agentic-development/conformance.md @@ -5,9 +5,9 @@ description: What a repository must provide to be conformant with the agentic de # Conformance -Conformance defines the required files, context resolution, and duplication limits for a -repository. This page states the baseline it MUST provide, what it MAY add, and how to -identify a deviation. +Conformance checks assess a repository's required files, context resolution, and +duplication limits. A conformant repository MUST meet the baseline and MAY add +the scoped extensions below. These checks assess structure and content. Documentation quality requires review; file and content inspection establishes whether agent context resolves correctly. @@ -95,7 +95,7 @@ That answer depends on the same context being assessed. ## Where this connects -- [Spec](spec.md) — the requirements this checklist measures against. +- [Spec](spec.md) — agentic-development conformance requirements. - [Design](design.md) — the mechanisms each baseline item refers to. - [MCP Servers](mcp-servers.md) — the shared tool layer the **Uniform** level requires. - [Plugin Distribution](plugin-distribution.md) — the pointer discipline the duplication checks apply to intents. diff --git a/src/docs/Capabilities/agentic-development/design.md b/src/docs/Capabilities/agentic-development/design.md index b26d9b5..6311cb3 100644 --- a/src/docs/Capabilities/agentic-development/design.md +++ b/src/docs/Capabilities/agentic-development/design.md @@ -265,13 +265,13 @@ Copilot code review uses the head-branch versions of `AGENTS.md`, client routes, ## Where this connects -- [Spec](spec.md) — the requirements this design delivers. +- [Spec](spec.md) — agentic development requirements. - [MCP Servers](mcp-servers.md) — the shared tool layer every runtime declares in its own format. - [Plugin Distribution](plugin-distribution.md) — how named intents are packaged and kept pointer-based. - [Runtime Integration](runtime-integration.md) — what each runtime shape supplies, and why it never supplies process. - [Agent Interaction](agent-interaction.md) — how agents and humans coordinate through platform artifacts. - [Advisory Agents](advisory-agents.md) — agents that produce advice rather than commits. - [Conformance](conformance.md) — the checklist a repository is measured against. -- [Agentic Development framework](index.md) — the framework this design delivers. +- [Agentic Development framework](index.md) — organization-scoped documentation and agent context. - [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why spec and design are split. - [README-Driven Context](../../Ways-of-Working/Readme-Driven-Context.md) — why local repository context remains the front door. diff --git a/src/docs/Capabilities/agentic-development/plugin-distribution.md b/src/docs/Capabilities/agentic-development/plugin-distribution.md index 766f0c9..a60f342 100644 --- a/src/docs/Capabilities/agentic-development/plugin-distribution.md +++ b/src/docs/Capabilities/agentic-development/plugin-distribution.md @@ -9,8 +9,7 @@ Recurring workflows can have **named intents**. Examples include "review this pu "open an issue for this", and "wrap up and hand off". Each intent points to a documented procedure. -Runtimes expose an intent as a command, skill, named agent, or plugin. This page defines what -that packaged entry point can contain. +Runtimes expose an intent as a command, skill, named agent, or plugin. ## An intent is a pointer @@ -79,8 +78,8 @@ The body stays a short route with runtime mechanics. ## Marketplace structure and skill boundaries The [Plugin Marketplaces design](design-plugin-marketplaces.md) owns marketplace ownership, -repository layout, plugin identities, and skill granularity. This page describes named-intent -distribution and links to those structural rules. +repository layout, plugin identities, and skill granularity. Named-intent +distribution follows those structural rules. For consumer upgrades, `msx-ways-of-working-consumer-upgrades` is the shared pointer to [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md). diff --git a/src/docs/Capabilities/agentic-development/spec.md b/src/docs/Capabilities/agentic-development/spec.md index 67aaaa3..bec87de 100644 --- a/src/docs/Capabilities/agentic-development/spec.md +++ b/src/docs/Capabilities/agentic-development/spec.md @@ -110,7 +110,7 @@ This is the order in which context is **read**, nearest first. It is not the ord - [Plugin Distribution](plugin-distribution.md) — how named intents stay pointers to documentation. - [Agent Interaction](agent-interaction.md) — issues, labels, and pull requests as the coordination substrate. - [Advisory Agents](advisory-agents.md) — the pattern for automation that advises without deciding. -- [Conformance](conformance.md) — how a repository is measured against this spec. -- [Agentic Development](index.md) — the framework this specification defines. +- [Conformance](conformance.md) — repository checks against the framework's requirements. +- [Agentic Development](index.md) — organization-scoped agent context. - [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — how specs and designs are written and kept evergreen. - [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) — the Markdown and frontmatter model used for knowledge pages. diff --git a/src/docs/Capabilities/dependency-updates/design.md b/src/docs/Capabilities/dependency-updates/design.md index 451ab4a..e0670db 100644 --- a/src/docs/Capabilities/dependency-updates/design.md +++ b/src/docs/Capabilities/dependency-updates/design.md @@ -159,7 +159,7 @@ fresh output is drift. Generation MUST preserve surfaces marked ## Where this connects -- [Spec](spec.md) — the requirements this design delivers. +- [Spec](spec.md) — dependency-update requirements. - [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) — the procedure that turns an update proposal into verified adoption. - [Repository Governance](../repository-governance/design.md#drift-detection-and-reconciliation) — the reconciliation that compares generated configuration against what is committed. - [Release Management](../release-management/design.md) — the conditional release decision and output for an update pull request. diff --git a/src/docs/Capabilities/deployment/designs/azure-from-github.md b/src/docs/Capabilities/deployment/designs/azure-from-github.md index 5f317a1..499c993 100644 --- a/src/docs/Capabilities/deployment/designs/azure-from-github.md +++ b/src/docs/Capabilities/deployment/designs/azure-from-github.md @@ -5,7 +5,7 @@ description: How the deployment spec is delivered with Azure as the service prov # Deploying Azure from GitHub -This design defines how one combination satisfies the [Deployment spec](../spec.md): +The deployment workflow satisfies the [Deployment spec](../spec.md) with **Azure** (including Microsoft Entra ID) as the service provider, **GitHub** as the CI/CD platform, and **Terraform (open source)** as the change engine. The computed resource effect is a **saved Terraform plan**. Each environment has its diff --git a/src/docs/Capabilities/deployment/designs/index.md b/src/docs/Capabilities/deployment/designs/index.md index c1405bd..8e7b5ae 100644 --- a/src/docs/Capabilities/deployment/designs/index.md +++ b/src/docs/Capabilities/deployment/designs/index.md @@ -5,8 +5,8 @@ description: How the deployment contract is delivered for each service-provider # Deployment designs -Each page describes how one service-provider and CI/CD-platform combination -satisfies the [Deployment spec](../spec.md). Add a design here without changing +Each service-provider and CI/CD-platform combination uses a separate design to +satisfy the [Deployment spec](../spec.md). Additional combinations do not change the technology-independent contract. diff --git a/src/docs/Capabilities/deployment/spec.md b/src/docs/Capabilities/deployment/spec.md index 52baa54..896c4ca 100644 --- a/src/docs/Capabilities/deployment/spec.md +++ b/src/docs/Capabilities/deployment/spec.md @@ -225,5 +225,5 @@ Feature: Deployment approves and applies the effect, not just the code - [Designs](index.md) — how these requirements are delivered for a specific service provider and CI/CD platform. -- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why this spec holds only the why and the what. +- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — the separation between capability requirements and implementation details. - [PR Format](../../Ways-of-Working/PR-Format.md) — the review that approves the change and its effect. diff --git a/src/docs/Capabilities/downstream-release-propagation/design.md b/src/docs/Capabilities/downstream-release-propagation/design.md index 1cfde54..6b1b863 100644 --- a/src/docs/Capabilities/downstream-release-propagation/design.md +++ b/src/docs/Capabilities/downstream-release-propagation/design.md @@ -306,7 +306,7 @@ review, merged, or met its applicable ## Where this connects -- [Spec](spec.md) — the requirements this design delivers. +- [Spec](spec.md) — downstream release propagation requirements. - [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) — the complete-range adoption procedure used by each dependent. - [Release Management](../release-management/design.md) — produces the release and note this consumes. - [GitHub Actions](../../Coding-Standards/GitHub-Actions.md) — SHA pinning, least-privilege permissions, explicit secret passing. diff --git a/src/docs/Capabilities/merge-automation/design.md b/src/docs/Capabilities/merge-automation/design.md index f7f8653..e02ce34 100644 --- a/src/docs/Capabilities/merge-automation/design.md +++ b/src/docs/Capabilities/merge-automation/design.md @@ -110,7 +110,7 @@ Scope the app's approval to the eligible set the ruleset permits it to satisfy. ## Where this connects -- [Spec](spec.md) — the requirements this design delivers. +- [Spec](spec.md) — merge automation requirements. - [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#gate-merges-with-a-named-status-check) — authoring the named checks this consumes. - [Dependency Updates](../dependency-updates/design.md) — the auto-merge policy this generalizes. Dependency update PRs are the canonical eligible set. - [Release Management](../release-management/design.md) — the release a merge triggers on an invoked route. diff --git a/src/docs/Capabilities/powershell-on-github/design.md b/src/docs/Capabilities/powershell-on-github/design.md index 1b923c8..f01c39d 100644 --- a/src/docs/Capabilities/powershell-on-github/design.md +++ b/src/docs/Capabilities/powershell-on-github/design.md @@ -5,8 +5,8 @@ description: Reusable modules, actions, and the Process-PSModule framework imple # Design -This design implements the [capability requirements](spec.md) through reusable -modules, actions, and the `Process-PSModule` framework. +Reusable modules, actions, and the `Process-PSModule` framework implement the +[capability requirements](spec.md). ## Capability model @@ -25,7 +25,7 @@ The model has two paths: ## Operating pattern - Keep component-level details in initiative/module docs. -- Keep reusable architecture and decision rationale here. +- Keep reusable architecture and decision rationale with the capability. - Link initiative pages to this capability as canonical context. ## Current canonical references diff --git a/src/docs/Capabilities/release-management/accept-moved-release-tags.md b/src/docs/Capabilities/release-management/accept-moved-release-tags.md index 5179c87..296a8af 100644 --- a/src/docs/Capabilities/release-management/accept-moved-release-tags.md +++ b/src/docs/Capabilities/release-management/accept-moved-release-tags.md @@ -5,9 +5,8 @@ description: Refresh an owned moving release alias locally and configure Git to # Accept moved release tags -Use this guide for an MSX-owned producer's intentionally moving Git tag, such as -`v3` or `v3.4`. Refresh the tag when your local clone still resolves it to an -older release. +For an MSX-owned producer's intentionally moving Git tag, such as `v3` or `v3.4`, +refresh the tag when your local clone still resolves it to an older release. Do not use this procedure for exact version tags such as `v3.4.2`. Exact version tags are immutable. A moved exact tag is a producer integrity incident, not a diff --git a/src/docs/Capabilities/release-management/design-publishing-targets.md b/src/docs/Capabilities/release-management/design-publishing-targets.md index b9efa58..bd3330b 100644 --- a/src/docs/Capabilities/release-management/design-publishing-targets.md +++ b/src/docs/Capabilities/release-management/design-publishing-targets.md @@ -11,8 +11,8 @@ passes every target the same frozen version, retained artifact, note envelope, and release-intent identity. Targets differ in native version syntax, prerelease channels, deletion, and -consumer resolution. This page makes those differences explicit so adding a -destination does not change the [release-management specification](spec.md). +consumer resolution. Each destination's contract records those differences +without changing the [release-management specification](spec.md). ## Publishing-target contract diff --git a/src/docs/Capabilities/release-management/design.md b/src/docs/Capabilities/release-management/design.md index b97eaf2..e41ada8 100644 --- a/src/docs/Capabilities/release-management/design.md +++ b/src/docs/Capabilities/release-management/design.md @@ -5,9 +5,9 @@ description: Durable release intents, lifecycle transitions, recovery, withdrawa # Release Management — Design -This page realizes the [release-management specification](spec.md) through -shared, GitHub-native release mechanics, including native producer pipelines. -It defines the durable lifecycle and input contract. The immutable producer +Release management satisfies the [release-management specification](spec.md) +through shared, GitHub-native mechanics, including native producer pipelines. +These mechanics use a durable lifecycle and input contract. The immutable producer revision's documented interface and verified behavior establish conformance. Documentation alone does not make a lifecycle control or setting available. @@ -675,7 +675,7 @@ controls, and conformance evidence before relying on them. A configuration example or normative requirement is not proof that an older producer implements it. Version-specific implementation deltas and required adoption actions belong in that producer's PR/release record, not a parallel status or migration history -in this design. +in the shared lifecycle contract. For an incomplete release, an operator MUST NOT work around a partial release by rerunning against changed metadata or rebuilding under the diff --git a/src/docs/Capabilities/repository-governance/design.md b/src/docs/Capabilities/repository-governance/design.md index f5a57bb..b7312cf 100644 --- a/src/docs/Capabilities/repository-governance/design.md +++ b/src/docs/Capabilities/repository-governance/design.md @@ -10,8 +10,8 @@ rulesets**, and **reconciliation**. The property carries the declaration. Organization rulesets read it, and reconciliation compares live configuration with the declared requirements. -This design defines the reconciliation contract. Delivery records provide -evidence that an implementation and its enforcement satisfy this contract. +Delivery records provide evidence that an implementation and its enforcement +satisfy the reconciliation contract. ```mermaid flowchart LR @@ -39,8 +39,7 @@ branch-model and layering obligations The property mechanism — how conditions target it, why conditions are written as exclusions, and how an existing condition is migrated onto it without dropping coverage — is owned by [Repository Type -Property](../../Ways-of-Working/Repository-Type-Property.md). This design does not -restate it. +Property](../../Ways-of-Working/Repository-Type-Property.md). Moving an organization from a single-select property to a multi-select `Type` property is a schema change the platform does not perform in place. The migration @@ -153,8 +152,8 @@ names. The [Repository Standard](../../Ways-of-Working/Repository-Standard.md#required-files) owns the file list, its conditional contribution rule, and which type adds to -it. This design owns only the enforcement: reconciliation checks required local -files on the default branch and resolves effective contribution guidance under +it. Reconciliation checks required local files on the default branch and +resolves effective contribution guidance under the [contribution rule](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), at **Block** severity for the files that make a repository contributable and **Report** severity for the rest. @@ -239,7 +238,7 @@ change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before ## Where this connects -- [Spec](spec.md) — the requirements this design delivers. +- [Spec](spec.md) — repository governance requirements. - [Repository Types](design-types.md) — the catalog the rulesets select on. - [Repository Type Property](../../Ways-of-Working/Repository-Type-Property.md) — the property mechanism and condition migration. - [Repository Standard](../../Ways-of-Working/Repository-Standard.md) — the required-file sets reconciliation checks. diff --git a/src/docs/Capabilities/vscode-extension-framework/design.md b/src/docs/Capabilities/vscode-extension-framework/design.md index b0e33b0..0a46cfd 100644 --- a/src/docs/Capabilities/vscode-extension-framework/design.md +++ b/src/docs/Capabilities/vscode-extension-framework/design.md @@ -5,8 +5,8 @@ description: How the VS Code extension framework is built — a shared reusable # VS Code Extension Framework — Design -The [spec](spec.md) defines the framework's behavior. The design combines a -**shared reusable workflow** with a **template repository**. It follows the +The framework combines a **shared reusable workflow** with a **template repository** +to meet the [spec](spec.md). It follows the organization's `Process-*` / `Template-*` convention, which [Process-PSModule](https://github.com/PSModule/Process-PSModule) uses for PowerShell modules. @@ -244,7 +244,7 @@ The template defines the following repository structure. It follows ## Where this connects -- [Spec](spec.md) — the requirements this design delivers. +- [Spec](spec.md) — VS Code extension lifecycle requirements. - [Release Management](../release-management/design.md) — the versioning and publication rules that the VSIX pipeline follows. - [Dependency Updates](../dependency-updates/design.md) — how the extension's dependencies stay current. - [Merge Automation](../merge-automation/spec.md) — how the pipeline's named status checks gate the merge. diff --git a/src/docs/Capabilities/vscode-extension-framework/spec.md b/src/docs/Capabilities/vscode-extension-framework/spec.md index a3f589a..f9b3087 100644 --- a/src/docs/Capabilities/vscode-extension-framework/spec.md +++ b/src/docs/Capabilities/vscode-extension-framework/spec.md @@ -51,7 +51,7 @@ dependencies current. A plain Node package that is not a VS Code extension is outside this scope. Documentation for a specific extension lives in that extension's repository. -This capability documents the framework itself. +The shared capability owns the framework requirements and design. ## Requirements @@ -66,7 +66,7 @@ This capability documents the framework itself. - **Optional marketplace publication.** When configured, the pipeline also publishes the same VSIX to an extension marketplace (the VS Code Marketplace and/or Open VSX). Marketplace publication is opt-in and MUST NOT be a prerequisite for the GitHub-Release install path. - **A prerelease from an open pull request.** A prerelease VSIX MUST be obtainable from an open pull request for tests before merge. It never becomes the latest stable version. - **A named status check per merge-blocking stage.** Every stage that must hold a pull request surfaces a named status check, so [Merge Automation](../merge-automation/spec.md) can gate the merge on it. -- **Documentation travels with the extension.** Each extension's user documentation lives in its own repository. The framework builds and publishes that documentation. There is no separate internal-versus-user split. This capability contains the framework's own documentation. +- **Documentation travels with the extension.** Each extension's user documentation lives in its own repository. The framework builds and publishes that documentation. There is no separate internal-versus-user split. Framework documentation belongs to the shared capability. - **Dependencies kept current.** The extension's pinned dependencies — npm packages and pinned Actions — are kept current and secure through [Dependency Updates](../dependency-updates/spec.md). - **Standard GitHub primitives only.** The framework uses pull requests, labels, releases, environments, and GitHub Actions. It uses no external release tooling beyond `gh` and the editor's own packaging and publishing CLIs. @@ -86,6 +86,6 @@ This capability documents the framework itself. - [Release Management](../release-management/spec.md) — the versioning and release mechanics this framework drives. - [Dependency Updates](../dependency-updates/spec.md) — how the extension's dependencies stay current. - [Merge Automation](../merge-automation/spec.md) — how the framework's status checks gate the merge. -- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why this spec defines requirements and an extension's docs live in its own repository. +- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — capability requirements and repository-local extension documentation. - [TypeScript](../../Coding-Standards/TypeScript.md) — the language standard extensions are written to. - [GitHub Actions](../../Coding-Standards/GitHub-Actions.md) — how the pipeline that delivers this is authored.