📖 [Docs]: Framework guidance now supports safe agentic delivery - #160
Merged
Conversation
Describe the project boundary as any adopting GitHub organization, keeping MSXOrg and PSModule as the concrete examples and a placeholder row for the general case.
Specification and design remain the required pair. Beneath them, implementation docs, guides, references, and research each get a defined altitude, a home in the capability folder, and a test for when a tier is warranted. Requirements now carry their own behavioral scenarios, so acceptance criteria hold only cross-cutting behavior. Large capabilities decompose into a core spec plus feature addenda with independent, append-only numbering. Authoring conventions add the impersonal-voice and enduring-problem rules, and the template suite moves to its own page and covers every tier.
The bump label is now required with no default, so an unlabelled pull request fails closed instead of quietly releasing a patch. Build-once becomes a stated invariant with a four-stage pipeline behind it: the version is resolved before the artifact is built, so it is the artifact's identity rather than metadata, and recovery is a re-run rather than a repair. Publishing gains a target contract with six documented dimensions and a new page carrying it, GitHub Releases as the reference target, plus sliding tags, all-or-nothing multi-target publication, and consumer update policies. Downstream propagation now offers task-first and issue-first delegation with idempotency per model, and the promotion merge model documents the standing draft pull request.
Add a repository-governance capability that states what governance guarantees and how classification selects the controls a repository inherits: a multi-select Type property whose values divide into branch model, layering, and exemption; per-type rulesets and required files; and automated drift detection with reconciliation as the enforcement concept. Convert the Type property page to multi-select with composition, validation, and a safe migration path. Add an automation-labels page covering label ownership, namespacing, and reserved vocabularies. Give dependency updates manifest-derived coverage, configurable cadence with a cooldown, per-ecosystem grouping, and a review posture that follows the update level.
…n patterns Memory is now scoped by horizon: user-wide lessons, per-repository facts, and session notes that are git-ignored so a scratchpad cannot be inherited as knowledge. Durable entries are committed as they are written. Context currency is re-established at the start of every session rather than once per machine, with each runtime attaching the same idempotent bootstrap at its own lifecycle point. Adds the shared tool layer, named-intent distribution, agent interaction on durable artifacts, the advisory-agent pattern, and a conformance checklist.
Segmentation states that a repository's boundary is also where its governance is decided, and that a repository needing two branch models is mis-segmented rather than ambiguously classified. The organization standard states that mandatory file sets derive from classification, and that every standard is paired with continuous observation so that silent deviation is not a possible outcome.
The pages that require impersonal third person were themselves written in the first person. Restated as facts that stand without a narrator.
Marius Storhaug (MariusStorhaug)
force-pushed
the
docs-frameworks-refresh
branch
from
August 9, 2026 15:12
c5c84ff to
9f457eb
Compare
Add a runtime integration page covering the four obligations a runtime must meet — entry file, lifecycle point, tool declaration, and identity — described by runtime shape rather than by product name so the guidance does not expire with any particular client.
Bind wrap up, park, triage, and handoff to procedures defined once in the standard, so every runtime references the definition instead of embedding its own copy. Add the phrase table to the workspace template as a route.
The rule that specs link up and principles never link down was stated only in Spec-Driven-Development, so the lower layer defined the higher layer's obligations. Principles/index.md now states what a principle is, the test that keeps the layer small, and why references point one way only; Spec-Driven-Development links to that contract instead of owning it. The vision cascade gains the Principles and Capabilities layers, which were absent from the diagram despite Capabilities being a whole documentation area, and states the upward-reference rule that makes the upper layers stable.
Secure by default existed only as a coding standard, and fleet management only as a process page, so both practices were being applied without the belief that justifies them stated anywhere above them. Secure by default joins Software Design as smart defaults applied to risk: the safe configuration is the one requiring no decision, and relaxing it is explicit, local, and reviewable. Fleet management joins Engineering Practices as everything-as-code applied to a population of repositories: membership derives from a declared property, desired state is expressed once, and drift is reconciled continuously rather than assumed absent.
The principles pages both addressed the reader as a group and linked down into the process pages that conform to them, contradicting two rules the same documentation set states. Prose is now impersonal throughout, and the references into Ways-of-Working, Coding-Standards, and Vision are removed; the relationship stays discoverable from below, where the conforming page names the principle it obeys.
The spec-driven development authoring conventions require documentation to be written impersonally, but the vision, dictionary, ways-of-working, and coding standards pages still addressed the reader or spoke as a team. Statements that depend on who is speaking read as opinion and go stale when roles change. Restate them as facts about the system. Reader-voice prompts in the README section template and quoted counter-examples stay as they are, because the voice is the point in both cases.
The template suite already carried a decision record skeleton and three pages referred to decision records in passing, but the artifact tiers table did not list them. Nothing stated when one is required or where it lives, so the skeleton had no rule behind it. Add decision records to the tiers table with a section defining the trigger: a choice is recorded when it is a one-way door, meaning reversal costs materially more than choosing differently now. Records are immutable — a later decision is a new record that supersedes the earlier one, so the template gains a supersession field. Give the tier a home in the documentation model alongside the other tiers.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
changed the title
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
August 9, 2026 16:20
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Aug 9, 2026
markdownlint's MD051 recognises a custom heading anchor only when the braces contain no surrounding whitespace. With the spaced form the heading keeps its slugified anchor, so same-page references such as [FR1](#fr1) -- the form Spec-Driven-Development.md tells authors to use -- are reported as broken link fragments, and a spec written by following that page fails the linter the ecosystem runs in CI. Convert 16 occurrences: 2 in the Spec-Driven-Development.md prose that introduces the form, and 14 in deployment/spec.md. Both forms render identically under Python-Markdown's attr_list, which this site enables, so the published output is unchanged. Test-DocumentationLink.ps1 matches the id with \s* around the brace contents, so it resolves either form. Two pages this commit used to touch have moved on: #158 retired process-psmodule/spec.md with the rest of that capability's pages, and #160 moved the specification templates out to Spec-Driven-Development-Templates.md. The anchors that arrived with #160, there and in its new worked example, are converted in the commit that follows this one. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Aug 9, 2026
#160 moved the specification skeletons out to Spec-Driven-Development-Templates.md and added a worked requirement example to Spec-Driven-Development.md. Both were written with the spaced brace form, which was still what the standard taught at the time and which nothing in CI would have caught, since MD051 was disabled. These six anchors sit inside fenced code blocks, so neither markdownlint nor Test-DocumentationLink.ps1 examines them and no check was failing. They matter because they are the text an author copies: the skeleton is the vector that carried the broken form into PSModule/Markdown#33 in the first place. A template that disagrees with the rule the same standard now enforces is the defect this branch exists to remove. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Aug 9, 2026
…own linter (#144) Requirement anchors in specifications now use the one form that both the documentation site and the Markdown linter understand, so a specification written by copying the template out of [Spec-Driven Development Templates](https://msxorg.github.io/docs/Ways-of-Working/Spec-Driven-Development-Templates/) lints clean with no hand-editing afterwards — in this repository and in any repository that inherits the standard without inheriting this one's linter configuration. ## Fixed: References to requirements no longer report as broken links The Requirements section tells authors to give each requirement an explicit anchor and to reference it as `[FR1](#fr1)`. Written with spaces inside the braces, that anchor is invisible to [markdownlint](https://github.com/DavidAnson/markdownlint) rule [MD051](https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md): the heading keeps its slugified anchor instead, and same-page references to the identifier resolve to nothing. Following the page therefore produced a document that failed the linter the ecosystem runs in CI. Anchors are now written without the inner spaces: ```markdown ### FR1 — <what the capability does, behavioral, testable, no technology> {#fr1} ``` Nothing else about the form changes. The anchor is still the identifier alone, still append-only, and still referenced as `[FR1](#fr1)` on the same page and `[FR1](spec.md#fr1)` across pages. Both brace forms render identically under [Python-Markdown's `attr_list`](https://python-markdown.github.io/extensions/attr_list/), which this site enables, so the published pages are byte-for-byte the same as before. The specification that still used the spaced form has been converted, along with every skeleton in the templates page, so what an author copies matches the rule the standard now enforces. ## Changed: A reference to a heading that does not exist now fails the build MD051 was switched off in this repository precisely because it could not read the spaced anchors, with a script covering the gap instead. With the anchors converted, the rule is on again and a link to a heading that does not exist fails the lint job like any other error. Contributors get that caught in CI rather than discovering it as a dead link on the published site. ## Changed: The Markdown standard now documents the anchor form and the rule that enforces it The anchor syntax previously appeared only in Spec-Driven Development, framed as a convention for specifications — which is how the broken form came to be copied into pages and repositories that had nothing to do with specifications. It is now written down in the [Markdown standard](https://msxorg.github.io/docs/Coding-Standards/Markdown/) as a rule for any heading on any page, together with the limitation worth knowing: the linter checks same-file fragments only, so a clean lint run does not prove that a cross-file `spec.md#fr1` link resolves. Custom heading anchors are not defined by original Markdown, CommonMark, or GFM; this site gets `{#id}` from its enabled Python-Markdown `attr_list` extension, so the braces render literally in GitHub's file view but become the heading ID on the published site. --- <details> <summary>Technical details</summary> Six commits, each independently reviewable: 1. **`31d41cd` — the anchors.** Mechanical conversion of `{ #id }` to `{#id}`, 16 occurrences over 2 files — the Spec-Driven-Development prose that introduces the form (2, on one line) and `deployment/spec.md` (14, FR1–FR10 and NFR1–NFR4). No rewording, no restructuring, no reflowing. 2. **`7b21fee` — the linter disable that the spaced form caused.** `MD051: false` removed from `.github/linters/.markdown-lint.yml`. Gated, not assumed: the line was removed first and `markdownlint-cli2` v0.23.2 (markdownlint v0.41.1) run with that real configuration over every tracked Markdown file, reporting `0 issues`. Clean, so the removal stands. Had it surfaced unrelated findings, the disable would have been restored with a corrected comment and the findings tracked separately rather than fixed in passing. 3. **`a2c9a0d` — the checker's own help.** The three `{ #id }` examples in the comment-based help and parsing comment of `.github/scripts/Test-DocumentationLink.ps1` now show `{#id}`. Examples only; the matching expression is untouched. The colon-prefixed `{: #id ... }` in the same comment is left as it was — the expression genuinely tolerates that variant, so converting it would have made the help wrong. 4. **`f5fa802` — the standard that should have carried the rule.** `src/docs/Coding-Standards/Markdown.md` states that the shared configuration is the source of truth and then enumerates the rules in two tables; MD051 was in neither. It had been disabled in the config and never recorded, so the page was already out of step before this branch. Commit 2 made that omission live — the rule now fails the build for every page, not just specifications — so the page gains an MD051 row in **Enforced rules**, the anchor syntax as one bullet in **Style beyond the linter**, and the same-file limitation stated once. Verified MD051 is not present in **Relaxed on purpose**; it was not, so nothing was removed. 5. **`1a7c25c` — the anchors that arrived while this branch waited.** [#160](#160) moved the skeletons out to `Spec-Driven-Development-Templates.md` and added a worked requirement example, both written in the spaced form — which was still what the standard taught, and which nothing would have caught while MD051 was disabled. Six anchors converted: 5 in the new templates page, 1 in the new example. All six sit inside fenced code blocks, so neither markdownlint nor `Test-DocumentationLink.ps1` examines them and no check was failing; they matter because a skeleton is the text an author copies, and that is the vector that carried the broken form into PSModule/Markdown#33. 6. **`9a66332` — whose syntax this actually is.** The page opens by saying documentation is authored in GitHub Flavored Markdown, and commit 4 then made `{#id}` an enforced rule — but GFM defines no attribute syntax, and neither does CommonMark nor Gruber's original. The construct belongs to individual flavors: PHP Markdown Extra and Python-Markdown, kramdown's inline attribute lists, Pandoc. This site gets it from `attr_list`. Verified against the renderers rather than their documentation — GitHub's `POST /markdown` with `mode=gfm` returns `<h3>FR1 {#fr1}</h3>`, and the same literal output for `{ #fr1 }` and `{: #fr1 }`, while Python-Markdown 3.10.2 with `attr_list` turns all three into `<h3 id="fr1">`. The rule now says so where it is stated, so an author who sees braces in a repository file view knows that is expected rather than a mistake, and knows `{#id}` wins as an intersection of implementations rather than by any specification. **Rebased twice while waiting for review**, each time onto current `main` with no content from the incoming work reverted: - [#158](#158) retired the `process-psmodule` pages in favour of that capability's canonical site, deleting a file this branch had edited. A modify/delete conflict, resolved by keeping the deletion — the 11 anchors converted there went with the page. - [#160](#160) rewrote Spec-Driven-Development and replaced its inline templates with a link to the new templates page. A content conflict, resolved by taking `main`'s prose in full; the template conversions this branch used to carry now apply to the new page instead, in commit 5. **How much MD051 was actually catching.** MD051 validates *same-file* fragments only, and skips fenced code blocks entirely. Across the spaced anchors on this branch, exactly 2 references were being reported — `[FR8](#fr8)` and `[FR9](#fr9)`, both in `deployment/spec.md`. Cross-file references of the `spec.md#fr1` form were never checked by MD051 at all and depend on `Test-DocumentationLink.ps1`, which is why that script remains the broader of the two checks and stays in CI. This is the measurement that makes removing the disable safe: there were only ever two findings to clear, and they are cleared. The reach of the defect was in what the templates *taught* downstream repositories, not in the volume of errors produced here. **Why `{#id}` and not `{: #id }`.** `attr_list` accepts `{#fr1}`, `{ #fr1 }` and `{: #fr1 }`; markdownlint understands only the unspaced one, so it is the single form that satisfies the renderer and CI at once. `Test-DocumentationLink.ps1` matches with `\{\s*:?\s*#([-\w]+)[^}]*\}\s*$`, where `\s*` permits zero spaces, so the converted anchors resolve under the existing checker with no change to it. **Verification** after the second rebase, using only tooling the repository already provides: - `Test-DocumentationLink.ps1` — `All documentation links resolve (119 file(s) scanned)`, exit 0. - `Update-DocumentationIndex.ps1 -Check` — exit 0, no diff. - `markdownlint-cli2` with `.github/linters/.markdown-lint.yml`, MD051 now enabled, across all 128 tracked Markdown files — `0 issues`. - `Invoke-PesterSuite.ps1` — 54 passed, 0 failed, across 4 suites. **Implementation plan progress** — all five steps of #141 are delivered here: the documentation conversions, the linter-configuration removal with its gate, and the comment-based help examples. The plan's `process-psmodule/spec.md` step is satisfied by that file's removal in #158. Commits 4 and 5 are beyond the issue's plan and close drift the plan itself would otherwise have left behind. Nothing is deferred to a follow-up. **Issue convergence sweep** — scope was every open issue in `MSXOrg/docs`. #143 (naming the downstream artifacts a standard governs, so changing it has a known blast radius) is the closest match, and commit 4 is an instance of exactly that concern rather than a resolution of it — the general mechanism it asks for is not delivered here, so it takes no closing keyword. #142 (cross-repository links the Markdown standard tells authors to write) and #105 (co-locating Gherkin acceptance tests with the FR/NFR they verify) concern different surfaces. No additional issue is fully satisfied. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/**` (Markdown) | Markdown | Documentation Model, Spec-Driven Development | Aligned | | `.github/linters/**` (linter configuration) | Markdown | Repository Standard | Fixed in this PR — the configuration and the standard documenting it now agree | | `.github/scripts/**` (PowerShell) | PowerShell — Scripts, Documentation | Repository Standard | Aligned | </details> <details> <summary>Relevant issues (or links)</summary> - Resolves #141 ### Related work - References #143 - References #158 - References #160 - References PSModule/Markdown#33 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation consumers can now adopt a coherent framework for specifying, governing, releasing, and operating work with agents. The guidance defines the durable artifacts, controls, runtime contracts, and recovery paths that keep delivery safe as organizations and repositories grow.
New: Repository governance by declared type
Repositories can now declare a multi-select
Typethat separates their branch model, layering obligations, and explicit exemption. Organization-level rulesets, required files, review gates, and reconciliation follow that declaration rather than being configured repository by repository.The governance guidance defines the Standard and Infrastructure branch models; Artifact, Docs, and Memory layering; and Unmanaged as the only full exemption. It covers a coverage-preserving migration to the canonical multi-select property, controls that Memory retains while direct commits remain allowed, repository-level merged-head cleanup, explicit exemption reasons, and drift findings that name their remedy.
New: Agentic development runtime and memory contracts
Agent guidance now distinguishes organization knowledge, repository facts, and disposable session notes; refreshes context at every session start; and defines the shared tool layer, named intents, and least-privilege runtime identity.
New runtime-integration, MCP-server, plugin-distribution, advisory-agent, conformance, and interaction pages let adopters add a local, hosted, review-time, or scheduled runtime without rewriting process guidance. Session interactions such as wrap up, park, triage, and handoff now refer to one defined procedure each.
Changed: Specification and documentation artifacts
Specifications and designs remain the two required content artifacts, while each capability folder has a required
index.mdnavigation page. Implementation documents, guides, references, decision records, research, and feature addenda now have defined homes and altitude tests; templates cover every tier.Requirements own their behavioral scenarios, acceptance criteria hold only cross-cutting behavior, identifiers remain stable, and large specifications can separate core requirements from feature addenda. Documentation now also distinguishes navigation links from normative dependency links, preserves valid explicit anchors, and uses impersonal evergreen wording.
Changed: Release and dependency delivery
Release guidance now resolves version identity before building, tests and publishes the same immutable artifact, and documents target contracts, sliding tags, and consumer update policies. Retrying unchanged bytes keeps the same artifact and version; changed output creates a new version. A partial multi-target publication resumes the remaining targets with that same immutable artifact.
Downstream propagation defaults to a real Task or Bug delivery leaf before an agent opens its closing pull request. Dependency updates now classify every manifest as either natively supported or covered by a centrally managed exception, so unsupported ecosystems remain visible without requiring a repository-specific updater.
Changed: Shared standards and principles
The principles layer now owns its reference-direction contract and adds secure-by-default and fleet-management guidance. Standards, vision, dictionary, and ways-of-working pages use impersonal language; repository, automation-label, branching, review, documentation, testing, dependency, security, and language guidance are aligned with the expanded frameworks.
Technical details
mainchanges 66 files (2,915additions,363deletions). The four follow-up commits reconcile the governance migration and controls, immutable release recovery and delivery-leaf propagation, navigation versus content artifacts, and centrally managed dependency-update exceptions.Relevant issues (or links)