📖 [Docs]: Session-end standards and framework alignment is part of the workflow

[Marius Storhaug (MariusStorhaug)]

Ways of Working now names the moment where a change is reconciled against the guidance it has to live up to. At the end of an implementation session — once the work is complete and before the pull request is marked ready — the author re-reads the applicable process, coding standards, and framework documentation, reconciles the finished diff against them, and records the outcome in the pull request. Independent review then verifies that evidence instead of assuming the pass happened.

New: Standards and framework alignment pass

The Implement stage owns the canonical procedure. It runs once per session, not per commit, and reads three layers in precedence order:

1. Process — the Ways of Working pages governing the stage, including Commit Conventions, PR Format, and Branching and Merging.
2. Standards — the Coding Standards chapters that apply to the languages and file types actually changed.
3. Framework and domain documentation — what the repository's framework or product owns, published under Frameworks or in the repository itself.

Process defines the method; standards and framework documentation define the correctness details. Where layers overlap, the narrower one supplies the detail and the broader one supplies the method — a framework page never overrides a process rule it does not own.

The outcome is recorded as one row per changed surface, so it is checkable rather than a claim:

Changed surface	Standards checked	Framework docs checked	Result
src/functions/** (PowerShell)	Naming, Functions, Error Handling	Module source layout	Aligned
.github/workflows/**	GitHub Actions	Reusable workflow contract	Exception — Owner/Repo#123

A result is Aligned, Fixed in this PR, or Exception with a link. A stop rule keeps the pass from turning into a second delivery: fix what is in scope and keeps the pull request reviewable, and file a follow-up issue for anything out of scope, systemic, or shape-changing.

Changed: The Build phase and the ready gate

The canonical Workflow lists the pass as a named Build step immediately before Ready and auto-merge, and the Definition of Ready for Review adds it to the single ready checklist — so a pull request is not ready until the pass has run, its result covers every changed surface, and every exception links a follow-up issue.

Changed: What reviewers check

Review gains an explicit dimension: the evidence exists, covers every changed surface, and each exception links a real follow-up. Reviewers spot-check at least one row against the canonical standard or framework page, and a missing or hollow pass is a blocking finding.

Changed: PR Technical details

PR Format carries the evidence table in the Technical details block. It states the format and the result vocabulary only — the stage procedure still owns when and how the pass runs, so the guidance is written once and referenced everywhere.

---

Technical details

• src/docs/Ways-of-Working/Workflow-Stages/Implement.md — new step 5 defining the pass (Finalize renumbered to 6), plus operating rule 5 and a Coding Standards entry under Where this connects.
• src/docs/Ways-of-Working/Workflow.md — Build step 6 added before Ready and auto-merge, linking to the Implement anchor.
• src/docs/Ways-of-Working/Workflow-Stages/Review.md — new assessment dimension and a link back to the Implement anchor.
• src/docs/Ways-of-Working/PR-Format.md — evidence bullet and table under Technical details.
• src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md — one bullet in the Definition of Ready for Review; included because PR Format designates that page as the single ready checklist, so the gate would otherwise be described but not enforceable.
• The framework layer links to the Frameworks index rather than one initiative, keeping the guidance repository-agnostic.
• Implementation plan progress: all six steps in Document a session-end standards and framework alignment pass in Ways of Working #111 are complete; nothing deferred.

Standards and framework alignment

Changed surface	Standards checked	Framework docs checked	Result
src/docs/Ways-of-Working/** (Markdown prose)	Markdown, Natural Language, Documentation	Ways of Working — Documentation Model, Agentic Development	Aligned

Validated with pwsh .github/scripts/Test-DocumentationLink.ps1 (relative links and heading anchors resolve) and markdownlint-cli2 using .github/linters/.markdown-lint.yml (0 issues across Ways of Working). No page was added or renamed, so the documentation index generator needed no run.

Known deviation: the branch is named docs-standards-alignment-pass rather than the conventional docs/111-standards-alignment-pass, because the session's branch had already been created and renamed before the delivery issue existed.

Relevant issues (or links)

• Fixes Document a session-end standards and framework alignment pass in Ways of Working #111

[Copilot]

Pull request overview

Adds an explicit “standards and framework alignment pass” to the Ways of Working workflow, defining when it happens (session-end, before marking a PR ready), what guidance layers it reconciles against (process → standards → framework/docs), and how the outcome is recorded so reviewers can verify it.

Changes:

• Introduces a new session-end alignment-pass procedure in the Implement stage, including evidence-table format and a stop rule for out-of-scope findings.
• Updates the canonical Workflow and Definition of Ready for Review to require the alignment pass before “Ready and auto-merge”.
• Extends the Review stage and PR Format to require/check the recorded alignment evidence (including exceptions linked to follow-up issues).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/docs/Ways-of-Working/Workflow.md	Adds the alignment pass as an explicit Build step immediately before Ready/auto-merge.
src/docs/Ways-of-Working/Workflow-Stages/Review.md	Adds reviewer verification criteria for the author’s recorded alignment evidence and links back to Implement.
src/docs/Ways-of-Working/Workflow-Stages/Implement.md	Defines the canonical alignment-pass procedure, evidence table, and stop rule; updates operating rules and cross-links.
src/docs/Ways-of-Working/PR-Format.md	Adds the alignment evidence table format to the PR Technical details block and defines allowed result vocabulary.
src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md	Adds the alignment pass (with full coverage + exception linking) to the Ready-for-Review checklist gate.