[Marius Storhaug (MariusStorhaug)]

Deployment guidance states the approved-effect contract in direct, evergreen, en-US prose. Contributors, reviewers, operators, and their agents get a clear explanation of one approval for the code and every environment's resource effect, followed by deployment of exactly that approved effect. No consumer action or deployment change is required.

Changed: Deployment guidance explains approval and resource effects directly

The spec replaces vague and time-dependent explanations with concrete, present-tense statements. The indexes distinguish the technology-independent contract from each combination-specific design. The Azure-from-GitHub design explains saved plans, state validity, identity, emergency access, and audit records without idioms. Direct procedures retain direct commands.

The approved-effect, reapproval, fail-closed, concurrency, emergency, audit, environment, trust, and state contracts remain unchanged. This PR changes guidance, not deployment behavior or enforcement. The DORA statements describe intended outcomes, not measured implementation results.

Technical details

Immutable scope. MSXOrg/docs 1b0d4893c8fefabe604d04393068a8ff6f848082 to 41fe0058730ba9fc759c211aac124ea135813176. Four small commits change only the four assigned Markdown pages: 218 insertions and 215 deletions. The final head is pushed and the worktree is clean. This is a scoped documentation-change record, not an artifact-release record. The effective workflows validate and publish a Zensical site and do not invoke Release Management.

Full reads and changed paths. Every owned page was read in full before editing and the full baseline-to-head diff was reviewed after editing. No whole owned page remains unchanged.

Fully read and changed page	Change	Exact no-change content
src/docs/Capabilities/deployment/spec.md	Premise, enduring problem, outcomes, and requirement explanations	Front matter, Gherkin, inline code, links, 14 FR/NFR IDs/anchors, and normative keyword force per requirement
src/docs/Capabilities/deployment/index.md	Approval sequence and spec/design relationship	Front matter, table rows, navigation, and links
src/docs/Capabilities/deployment/designs/index.md	Design/spec relationship	Front matter, generated INDEX table, and links
src/docs/Capabilities/deployment/designs/azure-from-github.md	Mechanism explanations, en-US spelling, and direct operational steps	Front matter, Mermaid, YAML, ordered inline identifiers/commands, links, reference URLs, and headings

Concrete before/after evidence.

Before	After
first-class, reviewable thing	Before deployment, the process computes and shows the effect on every environment in the promotion path.
Problem and why now	Problem {#problem-and-why-now}
from a proposal to live	The team approves the code change and all these effects as one decision.
Entra rides the Azure identity context	The design states that the azuread provider uses the same federated token and Azure identity context, with no separate Entra ID secret.
native backstop	This state check is the native guard for FR5. The requirement remains linked.
serialised, authorised, cancelled, serialisation, defence in prose	serialized/serializes, authorized, canceled, serialization, defense

Technical-meaning review. Each original FR/NFR and design mechanism was compared with the edited text. NFR2 retains distinct read-only and environment-scoped write forms of access; it does not add a separate-principal policy to the spec. The design keeps its existing two-identity mechanism. The complete review retains exact approved plans and hashes, per-environment state serial/lineage, reapproval after invalidation, no concurrent or interrupted applies, required tests, restricted emergency access with reason/incident/follow-up, immutable attribution, drift, OIDC, and trust boundaries.

Preservation and anchor evidence. A one-time baseline comparison confirms three exact fenced blocks, one exact generated block, unchanged front matter, ordered inline code, Markdown link targets, autolinks, and all 14 requirement IDs/anchors. The MUST/MUST NOT/SHOULD sequence is unchanged within every requirement. Only the Problem heading and FR6 spelling change. The old published-site problem-and-why-now attr_list ID and all 14 FR/NFR IDs appear exactly once in the actual final CI-built HTML. GitHub implicit-heading-anchor compatibility is not claimed. No tracked links depended on the old implicit Problem or FR6 heading slug, so no cross-owned repair is needed.

Validation. Repeatable commands and full results are also retained in the delivery Task.

Check	Command or evidence	Result
Markdown	Existing markdownlint-cli2 with --no-install, .github/linters/.markdown-lint.yml, and the four explicit owned paths	Four files; zero issues
Relative links and anchors	pwsh -NoLogo -NoProfile -File .\.github\scripts\Test-DocumentationLink.ps1	All links resolve across 130 files
Cross-repository links	pwsh -NoLogo -NoProfile -File .\.github\scripts\Test-CrossRepositoryLink.ps1	Seven links resolve across 134 files
Local site	zensical build --clean --config-file .\src\zensical.toml	Existing local Zensical 0.0.50; no issues; not the repository's pinned version
Pinned site and anchors	Final CI installs Zensical 0.0.59 from requirements.txt; build succeeds; actual github-pages artifact inspected	Old published Problem ID and all 14 requirement IDs appear exactly once
Existing repository tests	pwsh -NoLogo -NoProfile -File .\.github\scripts\Invoke-PesterSuite.ps1	Existing Pester 6.0.1; 66 tests in six suites pass; none skipped
Whitespace and ownership	git diff 1b0d4893c8fefabe604d04393068a8ff6f848082 41fe0058730ba9fc759c211aac124ea135813176 --check and changed-path comparison	Clean; only the four owned pages change
Pre-edit prose review probe	Same scoped search outside fenced examples, before and after	12 observed phrase/spelling findings before; zero after; not a full STE-conformance test
Draft review	Existing Wait-CopilotReview.ps1 after each push	Final round APPROVED on 41fe0058730ba9fc759c211aac124ea135813176 at 2026-11-04T12:46:42Z; zero new inline comments
Final-head GitHub checks	Docs run and cross-repository links run	Lint, Build, Links, Test, and Cross-repository links pass; Publish is skipped for this PR

The pinned-build anchor evidence comes from artifact ID 13321579755, name github-pages, from the successful final-head Docs run. The inspected TAR member is ./Capabilities/deployment/spec/index.html; its SHA-256 is 067e56568d4c80dcdc3f94b6893e4391f3c12c79ca8ec1bad91146091b597eec. The artifact TAR SHA-256 is 5910dc357989b5fbeef7610a4bc07c594cf788fbcfe1f7292acd27334e26e69a. This verifies the actual pinned output instead of treating the older local installation as equivalent. No local dependency upgrade or new tooling is needed.

The final anonymous cross-link attempt hit the shared GitHub API quota and reported five unresolvable links, not broken targets. A retry with the existing GitHub CLI credential in process-local GITHUB_TOKEN passes. A transient second-commit push rejection also resolves with an ordinary fast-forward retry. No history rewrite, dependency installation, or credential persistence is used.

Standards and framework alignment. Criteria were derived before edits from the fixed-commit Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and spec/design templates linked in the Task. The official STEMG overview/FAQ and relevant Issue 9 rules and dictionary entries were consulted. The local PDF hash matches the verified reference; the PDF and extract remain local. These checks do not certify full ASD-STE100 conformance.

Changed surface	Standards checked	Framework docs checked	Result
Deployment spec	Fixed-baseline documentation/writing standards and specification template; relevant official STE guidance	Original Deployment spec and Azure design	Fixed in this PR; normative meaning retained
Both deployment indexes	Same writing standards and navigation/generated-content rules	Deployment spec/design relationship	Fixed in this PR; metadata and generated content retained
Azure-from-GitHub design	Same writing standards and design template; direct procedural writing	Original deployment requirements and mechanisms	Fixed in this PR; native contracts retained

Delivery plan and convergence. The delivery Task's source review, full reads, test-first prose-verification plan, spec/index/design steps, final full-diff review, and checks are complete. The issue retains the detailed source and before-text evidence. A narrow open-issue search for deployment in:title finds only the delivery Task; no additional issue is fully resolved by this diff.

Exclusions and limitations. No other capability, shared index, process page, code, configuration, or test file changes. #240 remains outside scope. Frozen Gherkin spelling, Mermaid labels, YAML comments, exact commands, technical terms, and generated content are accepted differences. No live Azure or Terraform deployment was attempted. Normative design intent is not proof of implementation or enforcement. No remaining substantive contradiction was identified in the owned pages, and there is no remaining blocker.

The PR remains draft. It is not marked ready or merged, and auto-merge and Agent merge are not enabled.

Related references

• Resolves [documentation-writing-alignment] Align deployment capability prose with writing standards #249
• References fixed-baseline criteria, initial observations, and delivery evidence

[Copilot]

🟢 Approved

No active review issues were identified for this documentation-only clarification of the deployment approval contract.

No open issues 🎉

What changed in this PR

This documentation-only change clarifies the deployment capability’s approval contract: one decision covers the code and its resource effects across all environments, and deployment applies exactly those approved effects.

Changes:

• Replaces vague explanations with direct, present-tense prose.
• Renames the Problem heading while preserving its published anchor.
• Describes intended delivery outcomes without claiming this edit implements or measures them.

File	Description
src/​docs/​Capabilities/​deployment/​spec.md	Clarifies the approval contract, user needs, and intended outcomes while preserving the existing Problem anchor.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are reported for the documentation-only clarification of the deployment approval contract.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are recorded for this documentation-only clarification of the deployment approval contract.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues block this documentation-only clarification of the deployment approval contract.

No open issues 🎉

_{Review effort: Balanced}