📖 [Docs]: Session-end standards alignment and issue convergence gate PR readiness (#112)

Ways of Working now defines two session-end reconciliation passes that
run once when implementation is complete and before a pull request is
marked ready: standards/framework alignment and issue convergence.
Authors now finish by proving the diff aligns with governing guidance
and by checking whether the same diff already satisfies additional open
issues that should be closed on merge.

## New: Standards and framework alignment pass

The
[Implement](https://msxorg.github.io/docs/Ways-of-Working/Workflow-Stages/Implement/)
stage owns the canonical procedure. It runs once per session, not per
commit, and reads three layers in precedence order: process, standards,
then framework/domain documentation.

The outcome is recorded as one row per changed surface, with each row
marked `Aligned`, `Fixed in this PR`, or `Exception` with a linked
follow-up issue.

## New: Issue convergence sweep

The same session-end window now includes an [issue convergence
sweep](https://msxorg.github.io/docs/Ways-of-Working/Workflow-Stages/Implement/#6-issue-convergence-sweep):
a scoped search of open issues for asks the finished diff already
satisfies, beyond the issue originally linked when the branch was
opened.

The sweep is explicitly scale-aware: it starts with the issue hierarchy
(parent and sibling delivery leaves) and narrows by
component/labels/keywords/code paths rather than reading every open
issue serially.

When a convergent issue is fully satisfied, it is added to the PR's
related issues with a closing keyword so it closes on merge; when only
partially satisfied, it is linked as non-closing context and the
remaining gap stays in delivery planning. The sweep is only about
convergence and linkage; it does not rewrite or reformat issue bodies.

## Changed: The Build phase and ready gate

The canonical
[Workflow](https://msxorg.github.io/docs/Ways-of-Working/Workflow/) now
lists the convergence sweep as a dedicated Build step alongside
standards/framework alignment, immediately before Ready and auto-merge,
and the [Definition of Ready for
Review](https://msxorg.github.io/docs/Ways-of-Working/Definition-of-Ready-and-Done/)
now requires both passes before a PR can leave draft.

## Changed: Reviewer expectations and closure semantics


[Review](https://msxorg.github.io/docs/Ways-of-Working/Workflow-Stages/Review/)
now spot-checks both session-end passes and verifies that any additional
closing issue links are backed by visible convergence in the delivered
diff. [PR
Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/) and
[Repository
Standard](https://msxorg.github.io/docs/Ways-of-Working/Repository-Standard/)
now distinguish the one scoped delivery-leaf closure from additional
convergence-based closures.

---
<details>
<summary>Technical details</summary>

- `src/docs/Ways-of-Working/Workflow-Stages/Implement.md` — added **Step
6: Issue convergence sweep** between alignment and finalize, including
timing, scalable scoping guidance, convergence outcomes, and explicit
out-of-scope wording for issue-body rewrites.
- `src/docs/Ways-of-Working/Workflow.md` — Build flow now includes a
dedicated Issue convergence sweep step before Ready and auto-merge.
- `src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md` —
Ready-for-review checklist now requires the convergence sweep and
clarifies one scoped delivery-leaf closure plus optional
convergence-based closures.
- `src/docs/Ways-of-Working/PR-Format.md` — Technical details now
includes sweep evidence, and Relevant issues semantics now permit
additional closing keywords only for fully convergent issues.
- `src/docs/Ways-of-Working/Workflow-Stages/Review.md` — review flow now
verifies convergence-sweep evidence and aligns scoped-closure wording
with the new semantics.
- `src/docs/Ways-of-Working/Issues/Types/Hierarchy.md` — added a
discoverability cross-link showing hierarchy-first targeting for the
sweep.
- `src/docs/Ways-of-Working/Repository-Standard.md` — pull request
closure wording now matches the scoped+convergent closure model.
- Implementation plan progress: the standards/framework pass integration
is preserved and the issue-convergence dimension is now fully threaded
through Implement, Workflow, Ready, Review, and PR format guidance.

**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 |

**Issue convergence sweep**

| Sweep scope | Result |
| --- | --- |
| Parent/sibling issue hierarchy for `#111`, plus related
standards/workflow docs area | No additional fully convergent open
issues identified for closure in this docs-only PR |

Validation results: `pwsh .github/scripts/Test-DocumentationLink.ps1`
reported `All documentation links resolve.` and `npx markdownlint-cli2
--config .github/linters/.markdown-lint.yml` reported `Summary: 0 issues
in 0 files` for all changed documentation files in this PR.

</details>

<details>
<summary>Relevant issues (or links)</summary>

- Fixes #111

</details>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md

@@ -27,10 +27,12 @@ A pull request stays a **draft** until it is genuinely ready for other people to
 
 A pull request is ready for review when:
 
-- It closes exactly one Task or Bug, and every item in that delivery leaf's implementation plan is complete or explicitly moved to a follow-up issue.
+- It closes one scoped Task or Bug delivery leaf, and every item in that leaf's implementation plan is complete or explicitly moved to a follow-up issue. Additional issues may be closed only when the [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) confirms the finished diff already delivers them.
 - Native dependencies are current and every prerequisite the change relies on has landed; the pull request is not used to bypass a blocked-by edge.
 - All required checks are green — not just tests that pass locally. CI is complete, not in progress.
 - The automated review loop has converged — a clean [Copilot round](Contribution-Workflow.md#the-copilot-review-loop) with no unresolved review threads.
+- The [standards and framework alignment pass](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass) has run against the finished change, its result covers every changed surface in the pull request, and every exception links a follow-up issue.
+- The [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) has run against scoped open issues, and every fully convergent issue is linked in the pull request with a closing keyword.
 - The title, release-note description, and exactly one change-type label are finalized. See [PR Format](PR-Format.md).
 
 If any item is open, the pull request stays a draft. Marking it ready with known-open work shifts the author's unfinished job onto reviewers — the opposite of what the signal means.

src/docs/Ways-of-Working/Issues/Types/Hierarchy.md

@@ -64,3 +64,5 @@ Change type when decomposition reveals the issue is at the wrong altitude:
 Update the issue body for its new type, rebuild native containment, and add an audit comment explaining what changed and why. Promotion or demotion preserves the original issue whenever practical so its discussion and decisions remain traceable.
 
 See the [Goal-Setting Framework](../../Goal-Setting.md) for the Initiative boundary and the [Issue Format](../Process/Format.md) for the universal body structure.
+
+For pull requests, this hierarchy also guides where to look first during the session-end [issue convergence sweep](../../Workflow-Stages/Implement.md#6-issue-convergence-sweep) (parent and sibling delivery leaves before wider searches).

src/docs/Ways-of-Working/PR-Format.md

@@ -120,12 +120,21 @@ The **Technical details** block is for reviewers and maintainers. Include intern
 - Implementation approach and design decisions.
 - Backward compatibility notes for developers.
 - **Implementation plan progress** — cross-reference the closing Task or Bug's plan. Which plan steps does this PR complete? Which were moved to follow-up delivery issues?
+- **Standards and framework alignment** — the result of the [alignment pass](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass), as one row per changed surface. The stage procedure owns when and how the pass is run; this block only carries its evidence.
+- **Issue convergence sweep** — the scope used for the [session-end sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) and which additional open issues (if any) the finished diff fully satisfied.
+
+| Changed surface | Standards checked | Framework docs checked | Result |
+| --- | --- | --- | --- |
+| `src/**` (PowerShell) | Naming, Functions | 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 to the follow-up issue that carries it. A surface with no framework or domain documentation of its own is recorded as `None (no framework-specific docs)`.
 
 The **Relevant issues (or links)** block is required and uses fully qualified references (`Owner/Repo#N`) so links work across repositories.
 
-Use one bullet per linked issue. Exactly one bullet uses a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) (`Fixes`, `Closes`, or `Resolves`), and it closes the one Task or Bug delivered by the pull request. A parent PBI or Epic may appear as context without a closing keyword; never close an aggregate through a delivery pull request. Other supporting links are also non-closing.
+Use one bullet per linked issue. One bullet uses a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) (`Fixes`, `Closes`, or `Resolves`) for the scoped Task or Bug delivered by the pull request. Additional bullets may also use closing keywords only for issues the [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) confirms are fully satisfied by the same finished diff. A parent PBI or Epic may appear as context without a closing keyword; never close an aggregate through a delivery pull request. Partially convergent or supporting issues are linked as non-closing context.
 
-If there is not exactly one closing Task or Bug: **stop**. Route back to [Define](Workflow-Stages/Define.md) to create or correctly route the delivery leaf. The [Issue Hierarchy](Issues/Types/Hierarchy.md) and [Issue Lifecycle](Issues/Process/Lifecycle.md) own type and closure semantics.
+If there is not one scoped closing Task or Bug: **stop**. Route back to [Define](Workflow-Stages/Define.md) to create or correctly route the delivery leaf. If additional closing keywords are used, include sweep evidence in Technical details that shows those issues are fully satisfied. The [Issue Hierarchy](Issues/Types/Hierarchy.md) and [Issue Lifecycle](Issues/Process/Lifecycle.md) own type and closure semantics.
 
 ## Formatting
 

src/docs/Ways-of-Working/Repository-Standard.md

@@ -110,7 +110,7 @@ Default title pattern:
 <Icon> [<Change type>]: <User-facing outcome>
 ```
 
-The description should lead with user-facing impact, continue with user-facing change sections, include optional technical details after those sections, and end with the related-issues block. It closes exactly one Task or Bug as required by [PR Format](PR-Format.md).
+The description should lead with user-facing impact, continue with user-facing change sections, include optional technical details after those sections, and end with the related-issues block. It closes one scoped Task or Bug as required by [PR Format](PR-Format.md), with any additional closing links limited to issues the session-end convergence sweep shows are fully delivered by the same diff.
 
 Repository templates may be simpler than the full PR Manager body, but they must gather enough information to reconstruct it.
 

src/docs/Ways-of-Working/Workflow-Stages/Implement.md

@@ -47,7 +47,39 @@ When the plan is wrong, stop and document the conflict in a comment, then update
 1. Run the [Copilot review loop](../Contribution-Workflow.md#the-copilot-review-loop) until it reports a clean round.
 2. Triage each thread and CI failure per [Review Etiquette](../Review-Etiquette.md): fix in scope and propagate the same fix elsewhere; file a follow-up for out-of-scope; reply, then resolve.
 
-### 5. Finalize and hand off
+### 5. Standards and framework alignment pass
+
+Run this once per implementation session, when the change is otherwise complete and before the pull request is marked ready — not on every commit. Re-read the applicable guidance in precedence order and reconcile the whole diff against it:
+
+1. **Process** — the [Ways of Working](../index.md) pages that govern this stage, including [Commit Conventions](../Commit-Conventions.md), [PR Format](../PR-Format.md), and [Branching and Merging](../Branching-and-Merging.md).
+2. **Standards** — the [Coding Standards](../../Coding-Standards/index.md) chapters that apply to the languages and file types actually changed.
+3. **Framework and domain documentation** — the documentation the repository's framework or product owns, published under [Capabilities](../../Capabilities/index.md) or in the repository itself; for example the module-pipeline documentation for a module repository, or the action contract for an action repository.
+
+Process defines the method; standards and framework documentation define correctness details. Where the layers overlap, the narrower layer supplies the detail and the broader layer supplies the method — a framework page never overrides a process rule it does not own. Read the canonical pages instead of recalling them; that is what keeps guidance written once and referenced everywhere.
+
+Record the outcome as one row per changed surface:
+
+| 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 that justifies it. Where a changed surface has no framework or domain documentation of its own, write `None (no framework-specific docs)` rather than inventing a pseudo-link. Carry the table into the pull request's Technical details block per [PR Format](../PR-Format.md), so [Review](Review.md) can verify the pass instead of guessing whether it happened.
+
+**Stop rule.** Fix what is in scope for the closing Task or Bug and small enough to keep the pull request reviewable. When a finding is out of scope, systemic across the repository, or would change the shape of the pull request, file a follow-up issue through [Define](Define.md), link it in the table as an exception, and leave the change as it is. The pass improves alignment; it does not turn into a second delivery.
+
+### 6. Issue convergence sweep
+
+Run this once per implementation session, at the same timing as the standards/framework pass: when the change is otherwise complete and before the pull request is marked ready.
+
+1. Search for already-open issues whose asks are already satisfied by the finished diff, not only the issue originally linked when the branch was opened.
+2. Scope the sweep deliberately so it scales: prioritize the delivery leaf's parent and siblings in the [Issue Hierarchy](../Issues/Types/Hierarchy.md), then narrow by affected component, labels, keywords, or code paths. Do not read every open issue serially in large repositories.
+3. Treat convergence as outcome-based:
+   - **Fully satisfied** — the diff already delivers the issue's ask. Add it to the pull request's Relevant issues block with a closing keyword (`Fixes`, `Closes`, or `Resolves`) so merge closes it.
+   - **Partially satisfied** — the diff helps but does not fully deliver the ask. Link it as non-closing context and keep or create a follow-up delivery leaf for the remaining gap.
+4. Keep this pass focused on convergence and linkage. It does **not** rewrite, reformat, or otherwise "fix up" issue bodies to match issue templates; issue quality edits are separate work routed through [Define](Define.md).
+
+### 7. Finalize and hand off
 
 When the change meets the [Definition of Ready for Review](../Definition-of-Ready-and-Done.md):
 
@@ -60,11 +92,14 @@ When the change meets the [Definition of Ready for Review](../Definition-of-Read
 2. Progress is visible — the delivery issue is updated as plan steps complete, not in bulk.
 3. Draft pull request from the start; stay in the issue's scope.
 4. Mark ready only when the change meets the Definition of Ready for Review — never with open plan steps.
-5. Return unplanned work to [Define](Define.md) and hand review-ready work to [Review](Review.md).
+5. Run the standards and framework alignment pass once at session end, before marking the pull request ready, and record its result in the pull request.
+6. Run the issue convergence sweep once at session end, before marking the pull request ready, and link every fully convergent issue in the pull request with closing keywords.
+7. Return unplanned work to [Define](Define.md) and hand review-ready work to [Review](Review.md).
 
 ## Where this connects
 
 - [Contribution Workflow](../Contribution-Workflow.md) — the draft-first loop this runs.
-- [Issue Lifecycle](../Issues/Process/Lifecycle.md) and [Issue Relationships](../Issues/Process/Relationships.md) — delivery-leaf eligibility and blockers.
+- [Coding Standards](../../Coding-Standards/index.md) — the standards layer the alignment pass reconciles against.
+- [Issue Hierarchy](../Issues/Types/Hierarchy.md), [Issue Lifecycle](../Issues/Process/Lifecycle.md), and [Issue Relationships](../Issues/Process/Relationships.md) — delivery-leaf eligibility, convergence sweep targeting, and blockers.
 - [Definition of Ready and Done](../Definition-of-Ready-and-Done.md) — the gate this hands off at.
 - [PR Format](../PR-Format.md) and [Branching and Merging](../Branching-and-Merging.md) — packaging and landing.

src/docs/Ways-of-Working/Workflow-Stages/Review.md

@@ -19,7 +19,7 @@ A pull request number or URL. If the pull request was authored by the reviewing
 
 ### 1. Read the delivery issue
 
-Confirm the pull request closes exactly one Task or Bug, then review against that delivery leaf's acceptance criteria, decisions, and plan. Parent PBI or Epic links provide context but do not expand the pull request's scope or close the aggregate.
+Confirm the pull request closes one scoped Task or Bug delivery leaf, then review against that leaf's acceptance criteria, decisions, and plan. Parent PBI or Epic links provide context but do not expand the pull request's scope or close the aggregate. Additional closing links are valid only when the [issue convergence sweep](Implement.md#6-issue-convergence-sweep) shows the diff fully satisfies those issues.
 
 ### 2. Read the README
 
@@ -33,6 +33,8 @@ Check each dimension per [Review Etiquette](../Review-Etiquette.md):
 - **Taste** — readability, naming, structure, tests that exercise behaviour.
 - **Security** — input validation, no secrets in logs, SHA-pinned actions, least privilege. Escalate a deep pass to [Security Review](Security-Review.md).
 - **Documentation** — updated where user-facing behaviour changed.
+- **Standards and framework alignment** — the pull request records the author's [alignment pass](Implement.md#5-standards-and-framework-alignment-pass), the result covers every changed surface, and each exception links a real follow-up issue. Spot-check at least one row against the canonical standard or framework page rather than trusting the summary; a missing or hollow pass is a blocking finding.
+- **Issue convergence sweep** — the pull request records the author's [sweep](Implement.md#6-issue-convergence-sweep), including scoped search coverage and any convergent issues linked with closing keywords. Spot-check at least one linked closing issue against the delivered diff; a claimed convergence with no visible delivery evidence is a blocking finding.
 - **Tests** — new behaviour has tests; bugs get regression tests.
 
 ### 4. Post the review
@@ -55,6 +57,7 @@ An approval co-signs the change, so approve once the blocking concerns are resol
 ## Where this connects
 
 - [Review Etiquette](../Review-Etiquette.md) — tone, severity, and how to disagree well.
+- [Implement](Implement.md#5-standards-and-framework-alignment-pass) and [Implement](Implement.md#6-issue-convergence-sweep) — the author-side session-end passes this stage verifies.
 - [PR Format](../PR-Format.md) — delivery-leaf closure and contextual aggregate links.
 - [Branching and Merging](../Branching-and-Merging.md) — who approves and how a change lands.
 - [Security Review](Security-Review.md) — the specialized security path.

src/docs/Ways-of-Working/Workflow.md

@@ -107,11 +107,13 @@ See [Documentation Model](Documentation-Model.md), [Issue Planning](Issues/Proce
 Execute one ready, unblocked Task or Bug. For repository delivery:
 
 1. **Branch** — create a branch (and [worktree](Git-Worktrees.md)) for the delivery leaf.
-2. **Draft PR** — push early and open a draft pull request that closes exactly that Task or Bug. This makes progress visible and attaches CI from the start.
+2. **Draft PR** — push early and open a draft pull request scoped to one Task or Bug delivery leaf. The pull request closes that scoped leaf; any additional convergent issues are linked separately through the session-end issue convergence sweep. This makes progress visible and attaches CI from the start.
 3. **Implement** — work through the implementation plan. One logical change per commit. Update the issue as each plan step completes.
 4. **Test locally** — don't push known failures to CI. Push work as far inward as it can go.
 5. **Self-review with automation** — run the [Copilot review loop](Contribution-Workflow.md#the-copilot-review-loop) until it reports a clean round, fixing in-scope feedback and filing follow-up issues for the rest.
-6. **Ready and auto-merge** — when the change meets the [Definition of Ready for Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review), finalize the pull request per [PR Format](PR-Format.md), mark it ready, and enable auto-merge.
+6. **Standards and framework alignment pass** — once the change is complete, reconcile it against process, the applicable [Coding Standards](../Coding-Standards/index.md) chapters, and the repository's framework documentation, and record the result in the pull request. See [Implement](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass).
+7. **Issue convergence sweep** — in the same session-end window, sweep scoped open issues for asks already satisfied by the finished diff, and link fully convergent issues in the pull request with closing keywords. See [Implement](Workflow-Stages/Implement.md#6-issue-convergence-sweep).
+8. **Ready and auto-merge** — when the change meets the [Definition of Ready for Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review), finalize the pull request per [PR Format](PR-Format.md), mark it ready, and enable auto-merge.
 
 An audited operational Task follows its [operational completion path](Issues/Types/Task.md#operational-delivery) instead of creating a branch or pull request.