[Marius Storhaug (MariusStorhaug)]

Artifact and orchestration guidance uses direct en-US statements for documentation authors and agents. Fleet stage transitions remove the old label before adding its replacement, so the example and ordered instructions follow the existing one-stage-at-a-time rule.

The five-page revision preserves artifact roles, native issue types, hierarchy, stage gates, requirement identifiers, and command strings. The Fleet example intentionally changes sequence only. No integration or runtime-tool change is required.

Changed: Artifact guidance states its contracts and procedures directly

Documentation Model distinguishes requirements, design mechanisms, implementation values, and delivery records. Spec-Driven Development and its templates use consistent en-US wording. Comparative and fleet playbooks use literal explanations for evidence, ownership, stages, and campaign state.

The guidance keeps research findings historical, decision rationale immutable, template clarification markers unresolved until acceptance, and normative contracts separate from implementation or CI-enforcement evidence. It does not change policy, navigation, tooling, or dependencies.

Technical details

The review baseline remains fixed at 1b0d4893c8fefabe604d04393068a8ff6f848082. Source expectations come from that commit's Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and artifact templates. Editing an owned source page does not change the baseline or weaken its rules.

The official STEMG overview, FAQ, and verified local Issue 9 PDF/extract support the language review. The PDF MD5 is 9c720341c350ed77943b2c73d01c716f. Copies and extracts remain local. Full STE conformance is not claimed.

Before	After
this site is organised	The documentation on this site serves **humans and agents**.
the behaviour, guarantees, and success criteria	behavior, guarantees, and success criteria
implementation detail rots fastest	Implementation details change more often than requirements.
A change moves down a ladder of artifacts.	Each artifact has a defined level of detail
A spec fixes the smallest set of requirements	A spec fixes only the requirements needed for correctness and verification.
this feature specialises	this feature specializes
<One paragraph on how the spec is realised.>	<One paragraph on how the design meets the spec.>
Some reviews are not	A comparative review compares a target with authoritative reference sources.
Defining the classification vocabulary *before* looking at anything	Define the classification vocabulary **before** investigation.
How a single change is applied across many repositories at once	A *campaign* applies one change across many repositories.
every repository hitting the same wall	One shared fix unblocks every affected repository.
the judgement of	The only human or agent judgment is

All five owned files are fully read and changed, including all 11 artifact templates:

• src\docs\Ways-of-Working\Documentation-Model.md
• src\docs\Ways-of-Working\Spec-Driven-Development.md
• src\docs\Ways-of-Working\Spec-Driven-Development-Templates.md
• src\docs\Ways-of-Working\Comparative-Review-Orchestration.md
• src\docs\Ways-of-Working\Fleet-Orchestration.md

All 12 fixed prose examples pass after failing before editing. All 163 heading lines, including template/example headings, and all 118 link targets remain unchanged. FR/NFR anchors, normative keyword counts, fence structure, and contract tables retain their baseline meaning. Three comparative-review input descriptions change wording only. The 11 template skeletons retain their headings, syntax, placeholder delimiters, scenario examples, and clarification/supersession placeholders.

All executable examples remain byte-for-byte unchanged except for the explicit Fleet sequence-only correction described below. The two existing command lines exchange positions without changes to either command string, its identifiers or API route, or the note command. This is the sole example-preservation exception.

Manual review confirms required/optional tiers, the spec/design distinction, native issue types and hierarchy, stage gates, normative force, cross-cutting acceptance criteria, historical research, and decision immutability and supersession. No owned page has a no-change outcome. Shared indexes, other pages, code, tests, configuration, dependencies, and the files reserved by #240 remain unchanged. No cross-owned repair is required.

Accepted differences retain stable heading text and anchors, technical nouns, native fields, exact commands and paths, imperative instructions, normative obligations, historical findings and decisions, and intentionally incomplete template examples. The normal ready/auto-merge handoff is not performed because this campaign explicitly requires draft PRs.

Changed surface	Standards checked	Framework docs checked	Result
Documentation-Model.md	Fixed-baseline Natural Language, Technical Writing Guide, Markdown, Documentation	Fixed-baseline Documentation Model and artifact templates	Fixed in this PR
Spec-Driven-Development.md and templates	Same fixed-baseline writing sources	Fixed-baseline artifact tiers, specification/design roles, and all templates	Fixed in this PR
Comparative and fleet playbooks	Same writing sources; PowerShell shared conventions for exact native-command strings	Orchestration template, issue ownership, state rules, and stage gates	Fixed in this PR

The first complete Model improvement was pushed before this draft opened. Five focused commits are pushed: b7c1648, 6cf862a, ba77513, 111cee3, and 6e188db. The scoped PR comparison is 1b0d4893c8fefabe604d04393068a8ff6f848082 to 6e188db9cb47563b9cd8ba6da37ecfab123b8a5e.

The issue-convergence sweep covers 16 open campaign issues and open Spec-Driven-Development and Fleet-Orchestration matches. #105 requests removal of the standalone acceptance-criteria section, while the fixed standard retains it for cross-cutting scenarios. That policy/migration question remains separate, open, and unresolved. #101 requests a defect-tracking capability, not a prose revision. No additional issue is fully convergent and no extra closing reference is added.

Docs.yml builds and publishes the documentation site without invoking Release Management. The other workflow validates cross-repository links. No release decision block or release:* label applies.

Fixed: Fleet stage changes remove the old label first

The Fleet example removes stage:in-progress before adding stage:blocked. The queued-to-in-progress, adopted-PR, and blocked transition instructions use the same remove-first order. The existing limit of one stage label holds during the transition, not only after it.

This corrects the example and ordered documentation, not the policy or runtime tooling. Both existing command strings, identifiers, API routes, and the following note command are unchanged. No real GitHub labels are changed for the experiment.

Technical details

Before editing, anonymous in-memory label sets reproduce the original transient failure. The original document-order assertion fails, as expected. The corrected test reads the actual example's command order and checks every intermediate state.

Sequence, including initial state	Stage-label counts	Result
Add replacement, remove old stage, add note	1, 2, 1, 1	Fails the invariant after the add
Remove old stage, add replacement, add note	1, 0, 1, 1	At most one stage after every operation
Queued to in-progress	1, 0, 1	Remove-first instruction and model pass
Delivery issue to adopted PR	1, 0, 1	Remove-first instruction and model pass

The initial example labels are anonymous: stage:in-progress and topic:example. Both command orders produce the same final labels, stage:blocked and topic:example. The unrelated label is preserved. The note command does not mutate labels. The experiment makes no network calls or real GitHub label changes.

The Task's acceptance criteria and technical decisions record the intentional sequence-only exception. The original source baseline remains fixed. Normalizing only the approved adjacent-line reorder makes every other executable example match its prior content. Exact command-line multisets and the note command also match. All headings, links, FR/NFR anchors, normative keywords, and contract tables are preserved. Only Fleet changes after 111cee39bf9af79f04489d2eb5933e1999091e72: seven insertions and five deletions.

All implementation and verification steps for 6e188db9cb47563b9cd8ba6da37ecfab123b8a5e are complete, with evidence in the closing Task.

Repeated final-head validation	Result
Test-first model and actual document order	Original 1, 2, 1, 1 failure reproduced before editing; corrected 1, 0, 1, 1 passes with the same final and unrelated labels
Matching instructions	Queued, adopted-PR, and blocked transitions remove the old stage before adding the replacement
Original prose and preservation	All 12 cases and full five-page checks pass with the explicit sequence-only exception
Markdown lint	All five pages pass the shared configuration
Relative links	All links resolve across 130 documentation files
Cross-repository links	All seven links resolve across 134 Markdown files after the reported anonymous rate-limit reset
Site	zensical build --clean completes with no issues; no generated index is edited in the worktree
Repository tests	66 tests in six suites pass at the final head with installed Pester 6.0.1
Scope and whitespace	Exactly five owned files differ from baseline, only Fleet changes in the correction commit, git diff --check passes, and the worktree is clean
Final-head CI	Lint, Build, Links, Test, and Cross-repository links pass; Publish is skipped as configured
Copilot review	APPROVED for the final commit, zero new inline comments; the review-wait script returns exit 0
Native delivery state	Remote and PR head match the final SHA; the PR is open/draft, targets main, and closes only the native Task; auto-merge is unset, Agent merge is disabled, and release labels are absent

The first repeated anonymous network-link run is rate-limited on five targets, which is not a broken-link result. The identical retry succeeds after the reported reset. No dependency, configuration, runtime-tool, or enforcement change is made to obtain the passing result.

#105 remains separate and unresolved. The Fleet ordering contradiction is corrected in this PR rather than deferred. No blocker remains for this deliverable. This PR stays draft; do not merge it or enable auto-merge or Agent merge.

Related references

• Resolves [documentation-writing-alignment] Clarify artifact authoring and orchestration guidance #244
• References Co-locate each requirement's Gherkin acceptance test with the FR/NFR it verifies #105
• References Require automated and agentic work to track its defects #101

[Copilot]

🟢 Approved

No active review issues are reported for this documentation-only update to artifact and orchestration guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR rewrites artifact and orchestration guidance in direct en-US prose for human and agent readers, preserving existing contracts, stage gates, and executable examples.

Changes:

• Clarifies artifact roles, authoring rules, and the spec-driven delivery lifecycle.
• Refines wording across all 11 artifact templates while retaining their structure.
• Simplifies comparative-review and fleet guidance for evidence, ownership, and campaign state.

File	Description
src/​docs/​Ways-of-Working/​Spec-Driven-Development.md	Clarifies artifact responsibilities, requirements, and delivery guidance.
src/​docs/​Ways-of-Working/​Spec-Driven-Development-Templates.md	Refines template prose and artifact-specific authoring guidance.
src/​docs/​Ways-of-Working/​Fleet-Orchestration.md	Simplifies campaign coordination and GitHub state guidance.
src/​docs/​Ways-of-Working/​Documentation-Model.md	Clarifies documentation organization, artifact boundaries, and evergreen contracts.
src/​docs/​Ways-of-Working/​Comparative-Review-Orchestration.md	States review inputs, evidence handling, and issue-filing procedures directly.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are recorded for the documentation and workflow-guidance updates.

No open issues 🎉

_{Review effort: Balanced}