[Marius Storhaug (MariusStorhaug)]

Contribution guidance uses direct en-US explanations for branches, commits, worktrees, review duties, and session procedures. Commit guidance points change classification to canonical PR Format instead of asserting an unsupported metadata field.

Commands, recognized phrases, and review/release gates are unchanged. Contributors and reviewers need no workflow change. This clarification changes guidance only, not automation or enforcement. The campaign keeps this pull request in draft.

Changed: Contribution records state duties and session effects directly

The contribution pages replace metaphorical explanations with explicit actors, actions, conditions, and results. Authors still complete automated review before requesting human review. Reviewers retain blocking-concern and independent-approval duties. Session procedures retain their existing recording, continuation, read-only status, and confirmation requirements.

Commit Conventions states that classification belongs in the PR and links its canonical format. It adds no metadata field or unconditional label requirement. The no-conventional-prefix rule and every actual conditional release-label rule remain unchanged. No adoption action is required beyond reading the clarified explanations. PR Format remains unchanged, including its complete release-bound coverage and consumer-record requirements.

Technical details

Immutable scope and complete reading

The fixed criteria and scoped PR base are 1b0d4893c8fefabe604d04393068a8ff6f848082. The final candidate is 5aa044a68db7f5bcf7927d1d1b48b2bbb1e701fd. The remote PR head and all observed final-head CI checks name that exact candidate. Seven small commits change six prose-only files, with 272 additions and 223 deletions. The working tree is clean.

The source-resolved follow-up compares prior verified head 4de8a3b1a933b76d50197af8303cb12f83bb1d5c with the final candidate. It changes exactly one sentence in Commit-Conventions.md, with one insertion and one deletion. The other six assigned pages and every other sentence in Commit Conventions are exact to that prior head. The unsupported field reference is corrected, not deferred as policy.

Every assigned page was read in full, including every example and all 745 lines of PR Format.

Fully read path	Final disposition
src\docs\Ways-of-Working\Branching-and-Merging.md	Changed: direct branch, check, promotion, and approval explanations. Stack ordering and release conditions are retained.
src\docs\Ways-of-Working\Commit-Conventions.md	Changed: direct rationale and author responsibilities, with a canonical PR-format pointer instead of an unsupported field assertion. All prefix rules, good/bad messages, the body example, and the git log reference are retained.
src\docs\Ways-of-Working\Contribution-Workflow.md	Changed: explicit author review steps, readiness, and required ruleset conditions. The script contract, example, and Mermaid are retained.
src\docs\Ways-of-Working\Git-Worktrees.md	Changed: concrete working-directory isolation instead of a guarantee about all parallel work. Topology, remotes, and every command are retained.
src\docs\Ways-of-Working\PR-Format.md	No change: all 745 lines are unchanged. Immutable publication/candidate identity, lineage, full-range coverage, partial/initial publication, conditional release decisions, and complete adoption/no-action records remain intact.
src\docs\Ways-of-Working\Review-Etiquette.md	Changed: direct approval, evidence, response, and regression-coverage explanations. Blocking duties and the unresolved policy clauses are retained.
src\docs\Ways-of-Working\Session-Interactions.md	Changed: direct procedure descriptions and en-US. All eight phrases, aliases, effects, normative force, and the unresolved confirmation clauses are retained.

No workflow, issue-guidance page, shared index, governance page, dependency, code, test, or configuration file changes are included. Active #240 code/tests remain outside scope. Front-matter descriptions are the owning inputs for CI-generated indexes; no generated index was edited or committed.

Concrete before and after

Page	Before	After
Contribution Workflow	"the cheap feedback is spent before a person's time is"	"The author addresses automated review feedback before requesting human review"
Contribution Workflow	"survived an automated pass"	"the author completes the automated review loop and responds to its findings"
Contribution Workflow	"so nothing lands early"	"Auto-merge waits for human approval and every required branch-protection condition before it merges the change."
Branching and Merging	"A pull request is green before review begins."	"Automated checks pass before human review begins."
Commit Conventions	"without the ceremony"	"Direct, descriptive messages explain the change without duplicate type prefixes."
Commit Conventions, at the prior verified head	MSX classifies changes at the PR level via labels and the change-type field.	MSX classifies changes in the PR according to [PR Format](PR-Format.md).
Git Worktrees	"so parallel work never collides"	"This keeps participants' uncommitted changes in separate directories."
Review Etiquette	"the reviewer vouches for it"	"An approving review records the reviewer's acceptance of the change."
Session Interactions	"The phrase matters because the alternative is ceremony."	"A defined procedure makes the expected result clear."

The independent source for the classification correction is the fixed per-result classification contract. Its release decisions remain conditional on the target route. This correction points to that owner rather than inventing a field or repeating its classification rules.

Verification and its limits

The editorial expectations and failing before-text examples were recorded in the native Task before editing. The classification correction also has a source-bound before/expected result recorded before its edit. An exact whole-file comparison proves that only the specified sentence changed against the prior verified head. The other six pages are unchanged from that head, including all actual conditional release-label rules and both unresolved policy choices.

Final comparison against the fixed baseline retains all titles, 95 headings, 14 fenced blocks, 145 inline-code spans, 15 uppercase normative tokens, eight exact interaction phrases, and seven exact aliases/examples. All 72 existing link targets remain intact; the canonical PR-format pointer adds one relative target, for 73 total. PR Format remains wholly unchanged. Four selected policy clauses remain exact. The former field assertion is an explicitly verified descriptive correction, not a preserved policy choice.

The complete before/after prose was reviewed for retained technical meaning, active voice, conditions, direct work steps, and the relevant Issue 9 rules and dictionary. Counts, syntax comparison, linter success, and automated approval do not prove full STE conformance. The ruleset requirements remain normative guidance, not evidence that repository enforcement was audited. The preserved setup/cleanup examples were not executed as real repository operations.

Existing check, repeated for the final candidate	Outcome
git diff --check against the fixed base	Passed.
Cached markdownlint-cli2 0.24.0 with the shared configuration	Seven assigned pages examined; zero issues. No installation.
Test-DocumentationLink.ps1	All relative links resolved; 130 files examined, including the added canonical pointer.
Test-CrossRepositoryLink.ps1	Seven links in 134 files resolved. Existing GitHub authentication supplied rate-limit headroom; no credential was logged or persisted. An earlier head's anonymous-quota failure and successful retry remain in the Task audit record, not as evidence for this head.
Invoke-PesterSuite.ps1 with installed Pester 6.0.1	66 passed in six suites; zero failed, skipped, inconclusive, or not run. The log confirms the existing 6.0.1 import and GUID.
python -m zensical build --clean from src	Passed; no issues.
Final-head GitHub checks	Lint, Build, Test, Links, Cross-repository links, and automated review succeeded. Publish was skipped under the workflow's PR condition. All 15 reported linter statuses succeeded.
Automated review	Four requested rounds completed cleanly. The repeated final review names 5aa044a68db7f5bcf7927d1d1b48b2bbb1e701fd, reports approval, and adds zero inline comments. There are zero inline comments on the PR. Earlier clean rounds do not validate this new source.

Final external evidence: Docs CI, cross-repository CI, and the final source-bound review.

Standards and scope alignment

Criteria were derived before page review from the fixed Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and applicable Standard/Guide/Reference templates. The official STEMG overview and FAQ and relevant local Issue 9 rules/dictionary were consulted. The source links and verified PDF MD5 are in #261. The PDF and extract remain local and are not republished.

Changed surface	Standards checked	Framework docs checked	Result
src\docs\Ways-of-Working\Branching-and-Merging.md	Fixed writing criteria, Markdown, Standard/Guide roles; branch, stack, promotion, and approval contracts	None (no framework-specific docs)	Fixed in this PR
src\docs\Ways-of-Working\Commit-Conventions.md	Fixed writing criteria, Markdown, Standard role; canonical PR classification ownership, no-prefix rules, and exact examples	None (no framework-specific docs)	Fixed in this PR
src\docs\Ways-of-Working\Contribution-Workflow.md	Fixed writing criteria, Markdown, Guide/Standard roles; review, readiness, triage, and merge conditions	None (no framework-specific docs)	Fixed in this PR
src\docs\Ways-of-Working\Git-Worktrees.md	Fixed writing criteria, Markdown, Guide/Reference roles; workspace, remotes, and exact commands	None (no framework-specific docs)	Fixed in this PR
src\docs\Ways-of-Working\Review-Etiquette.md	Fixed writing criteria, Markdown, Standard role; blocking, reply, and independent-approval duties	None (no framework-specific docs)	Fixed in this PR
src\docs\Ways-of-Working\Session-Interactions.md	Fixed writing criteria, Markdown, Standard/Reference roles; phrase bindings, effects, authority, and normative force	None (no framework-specific docs)	Fixed in this PR

These results cover the scoped prose, not a claim that every policy ambiguity is resolved. Accepted differences include direct imperatives, exact commands/examples, native issue types and technical terms, stable headings/anchors, recognized phrases, and release/history record semantics. The app-managed branch name and the draft-only handoff are explicit campaign exceptions to the general delivery procedure.

The scoped convergence search covered this Task and open MSXOrg/docs issues with contribution in the title. It returned only #261. The narrow correction delivers the same Task, adds no other closing reference, and does not expand scope. All scoped implementation and repeated verification steps are complete; the Task remains open for review and merge.

The inspected target workflows build and publish the Zensical site. They do not invoke Release Management or publish a versioned product artifact. No publication baseline, release decision block, or applied release label is appropriate for this PR. Its scoped source comparison is not release-note coverage evidence.

Preserved policy questions and handoff

Only two genuine policy tensions remain unresolved: Session Interactions calls Stop the only interaction that MUST confirm first, while Spin-off also requires confirmation; Review Etiquette sends self-review to the terminal but also describes a public Comment review. Their original source clauses remain unchanged. The unsupported change-type-field reference is resolved from canonical PR Format as a narrow descriptive correction, not left as a third policy question.

There is no remaining implementation or validation blocker. This campaign stops at draft. The PR is open, draft, and unmerged; GitHub auto-merge is unset and Agent merge is disabled. Do not mark ready, merge, or enable either merge feature.

Related references

• Resolves [documentation-writing-alignment] Clarify contribution records and session procedures #261

[Copilot]

🟢 Approved

There are no active review issues for this documentation-only clarification of contribution responsibilities and workflow guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR clarifies the contribution workflow by stating author and reviewer responsibilities directly. It supports the broader writing-alignment task without changing commands, review gates, or repository enforcement.

Changes:

• Replaces metaphorical explanations with explicit author review and feedback-triage duties.
• Clarifies readiness requirements and the conditions auto-merge waits for.
• Preserves headings, links, examples, and the Copilot review-loop contract.

File	Description
src/​docs/​Ways-of-Working/​Contribution-Workflow.md	Clarifies draft review, author responsibilities, readiness, and auto-merge guidance.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are identified for this documentation-only clarification of contributor responsibilities and development practices.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues block these documentation-only guidance updates.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are reported for this documentation-only clarification of contribution guidance.

No open issues 🎉

_{Review effort: Balanced}