TSG/Storage: add testable metadata markers + live-validated enhancements (4 articles)

[John Neemes (1008covingtonlane)]

Summary

Adds machine-readable test metadata (the tsg-metadata/v1 marker) to all four content articles under TSG/Storage, alongside targeted enhancements validated against live Storage Spaces Direct clusters in an internal HaaS lab. This lets the directory be discovered and automatically tested by the metadata-driven pipeline.

Each article now carries a hidden <!-- tsg-metadata ... --> marker declaring document type, detector, reproduction substrate, live-validation fidelity, and a backing spec reference. Content was hardened for reader usability across a 13-persona review (leadership skim, first-day technician, CSS engineer, partner SI, OEM, and others), and every article reached a perfect panel with no remaining required change.

Articles

Article	Type	Live fidelity	Key enhancement
HowTo-Storage-AddPhysicalDisksToS2DPool	how-to	L3	Full reversible add / auto-pool / remove cycle validated live; new At a Glance and Evidence and Escalation sections; corrected disk-state terminology (CanPool boolean vs In a Pool reason)
Troubleshoot-Storage-PhysicalDiskCanPoolFalse	troubleshoot	L1	CannotPoolReason values corrected to the exact title-case strings the product emits (In a Pool, Insufficient Capacity, and others); scope banner; beginner off-ramp before the destructive reset
Troubleshoot-Storage-StoragePoolCapacityThreshold	troubleshoot	L3	Fixed-vs-thin footprint thesis confirmed live; substrate-artifact note for nested reclaim; multi-site sweep guidance
Troubleshooting-Storage-With-Support-Diagnostics-Tool	reference	L1	Full -Include token matrix run read-only; glossary; corrected all-PASS escalation target; PhysicalExtentCheck edge output documented

Validation

Every article was live-exercised read-only where safe, and for AddPhysicalDisks with a fully reversible scratch-disk add-and-remove that restored the pool byte-identical to its pre-test baseline. No production or customer system was used. The exact commands, observed output shapes, and per-run evidence live in the backing test specs.

Notes for reviewers

• The canonical tsg-metadata.schema.json these markers validate against is added in the companion Templates PR (Forge and standardize public TSG templates #342); that one should merge first.
• Markers are hidden HTML comments and do not change rendered article content.

/cc Alex Burns (@AlBurns-MSFT) Adam Rudell (@arudell) Meghay (@mejayara) for review.

[Copilot]

Pull request overview

Adds testable metadata and validated storage guidance improvements across four Azure Local articles.

Changes:

• Adds tsg-metadata/v1 markers for pipeline discovery.
• Expands safety, validation, evidence, and escalation guidance.
• Corrects disk-state terminology and diagnostic output details.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
HowTo-Storage-AddPhysicalDisksToS2DPool.md	Strengthens safe disk-add and verification procedures.
Troubleshoot-Storage-PhysicalDiskCanPoolFalse.md	Expands reason-based diagnosis and evidence collection.
Troubleshoot-Storage-StoragePoolCapacityThreshold.md	Clarifies fixed/thin remediation and validation.
Troubleshooting-Storage-With-Support-Diagnostics-Tool.md	Adds a comprehensive diagnostic command reference.

Suppressed comments (1)

TSG/Storage/Troubleshoot-Storage-PhysicalDiskCanPoolFalse.md:482

• What: the second transcript-copy block again filters only .txt, .log, .etl, and .zip, while this cmdlet writes its transcript as CSV. Why: the physical-extent run's native evidence is never copied, and a later same-day run can overwrite it. How: select the newly modified TraceOutput_*.csv and save it with a distinct name.

# Copy the native tool transcript for this run into the evidence package as well.
Get-ChildItem -Path $diagWorkingDir -Recurse -File |
    Where-Object { $_.LastWriteTime -ge $extentStart -and $_.Extension -in '.txt','.log','.etl','.zip' } |
    ForEach-Object { Copy-Item -Path $_.FullName -Destination $evidenceRoot -Force }

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[T.J. Hambley (tihamble)]

I went through all four articles against the product source of truth and ran the deterministic lint over every code block.

What checked out:

• Every cmdlet, parameter, and property is real and read off the right object: CanPool and CannotPoolReason on the physical disk, ProvisioningType and FootprintOnPool on the virtual disk, Size and AllocatedSize on the pool. The CannotPoolReason value strings ("In a Pool", "Not Healthy", "Removable Media", "In Use by Cluster", "Offline", "Insufficient Capacity") match the MSFT_PhysicalDisk value map exactly, casing included.
• Both pool health faults are in the exact form Get-HealthFault emits, StoragePool.InsufficientReserveCapacity and StoragePool.PoolCapacityThresholdExceeded, with no Fault/Error/Alert suffix, and the note about the Microsoft.Health.FaultType. prefix on the full internal id is accurate.
• The Support Diagnostics article lines up with the CSSTools module: Start-AzsSupportStorageDiagnostic and its parameter set, plus Get-AzsSupportWorkingDirectory and Get-AzsSupportStoragePhysicalExtent. Each metadata detector signal matches the cmdlet its article actually leads with.
• The capacity numbers match (70 percent thin-provisioning alert, volume warning 80 and critical 90), and the metadata markers are well-formed JSON.
• The fixed-versus-thin remediation is correctly gated on ProvisioningType, so a fixed-pool operator is routed away from the thin-only reclaim, and the pool-full-but-volumes-empty case is treated as expected behavior rather than a fault.
• Safety labeling holds. Reset-PhysicalDisk is HIGH RISK with a hard-stop checklist, a not-in-a-pool and no-active-repair precondition, a clear warning that it destroys the disk's Storage Spaces metadata, and a no-in-place-rollback note.

One note on the lint if you run it yourself: the PowerShell parse errors it reports are artifacts of the linter substituting angle-bracket placeholders that sit inside quoted strings (for example $serial = ''). The code itself parses fine.

What I could not do: I was not able to re-run the live read-only steps on hardware in my environment, so I did not independently reproduce the live-validation results described here. The static and source-of-truth checks all held, but the live run is unconfirmed on my end rather than something I verified.

No blocking issues in the content.

[T.J. Hambley (tihamble)]

Checked all four articles against the product source of truth and the emitted health-fault catalog, and ran the lint over every code block. No defects. The live-validation results described in the PR were not independently reproduced on my end, so that part is taken on the author's word rather than verified.