Revised the Normative Reference to comply with ISO

[seanmcilroy29]

Revised the Normative Reference to comply with ISO

[claude]

Review — PR #136: Revised the Normative References to comply with ISO

Reviewed against the repo conventions in CLAUDE.md (docs-first repo: SPEC.md is the deliverable, FAQ.md holds the rationale). Small, well-targeted change and the ISO alignment is solid. A few things to tidy before merge.

What's good

• The ISO/IEC Directives Part 2 boilerplate ("For dated references, only the edition cited applies…") is worded correctly and is exactly what an ISO-style Normative references clause needs.
• Reformatting the entry to ISO/IEC 21031:2024, Information technology — Software Carbon Intensity (SCI) specification (comma separator, no en-dash) matches ISO citation style. Good catch.
• Lowercasing the heading to Normative references is the correct ISO convention.

Issues to address

1. The "Open item for working group" blockquote should not be committed into the spec body. SPEC.md is the normative deliverable; a first-person editorial note ("I haven't added any since I don't know which…") that reads like a PR comment does not belong in the published text. Per the CLAUDE.md workflow, open questions belong in a GitHub issue or the PR discussion, not in SPEC.md. The substance is genuinely useful (ISO/IEC 30134 and ISO 14064 may need to be invoked normatively) — I would move it to an issue and drop it from the file. If the group wants in-doc TODOs, that convention should be agreed and applied consistently across the spec.

2. Missing blank line before the blockquote (Markdown rendering bug). The list item on line 51 is immediately followed by > on line 52 with no blank line between them. Markdown lazy-continuation rules can render the blockquote as a continuation of the list item rather than a separate block. If the note stays, add a blank line before >.

3. Trailing whitespace on the blank lines (lines 48 and 50 each contain a single trailing space). Minor, but it trips markdown linters — make them truly empty.

Consistency note (optional, out of scope)
Now that §3 is Normative references (lowercase), §4 Terms and Definitions is inconsistent with ISO style, which would render it Terms and definitions. Worth a follow-up pass to align all headings if full ISO compliance is the goal.

FAQ.md
No FAQ update required — this is a formatting/compliance change and does not contradict any existing FAQ rationale, so the CLAUDE.md dual-update rule does not apply.

Nice incremental cleanup overall — addressing item 1 (move the note out) is the main blocker.

[Henry-WattTime]

Approved once in line comment removed.

[claude]

Review: Revised the Normative Reference to comply with ISO

Reviewed the single-file change to SPEC.md §3 against FAQ.md and the repo conventions in CLAUDE.md. This is an editorial/normative-formatting change with no functional surface, so the "performance" and "security" axes of the review template do not really apply — I have focused on correctness of the ISO alignment, document consistency, and process/merge risk.

Overall: looks good, recommend merging after the whitespace nit. The substance is right.

What is correct

• Citation format. Changing ISO/IEC 21031:2024 – Information technology — Software Carbon Intensity (SCI) specification to ISO/IEC 21031:2024, Information technology — Software Carbon Intensity (SCI) specification is the right call. Comma-after-designation is the ISO citation convention, and the previous en dash was inconsistent with the em dash already used inside the title.
• Boilerplate. Adding the dated/undated applicability sentences brings §3 in line with the standard ISO/IEC Directives Part 2 introductory wording for a Normative references clause.
• FAQ impact: none required. Per the dual-update rule in CLAUDE.md I checked — FAQ.md does not discuss normative references, reference dating, or clause numbering, and nothing in FAQ.md/README.md cross-references spec sections by number. So no companion FAQ change is needed here, and no FAQ statement is invalidated. Correct to leave it out.
• No broken anchors. GitHub slugifies to lowercase, so Normative References becomes Normative references with the same #3-normative-references anchor. Any external deep links keep working.

Nit worth fixing before merge

Trailing whitespace on the two new blank lines (SPEC.md lines 49 and 51). Both contain a single space rather than being truly empty — visible via cat -A:

## 3. Normative references$
 $        <- line 49: single space
The following documents are referred to...$
 $        <- line 51: single space
- ISO/IEC 21031:2024, Information technology — ...$

This is a web-editor artifact. It is harmless in rendered output (a one-space line is still a blank line; it would take two trailing spaces to become a hard break), but it adds diff noise and would be flagged by markdownlint MD009. Worth stripping to keep the diff clean.

Points for the working group to confirm

1. Is the undated-reference sentence needed? The list contains exactly one entry and it is dated (21031:2024). The full two-sentence boilerplate is what you want when the list mixes dated and undated references; where every reference is dated, the undated sentence is arguably surplus. I would flag this as worth a check against the current Directives Part 2 wording rather than asserting it is wrong — and if the WG expects to add undated references as the spec grows, keeping both sentences now is a reasonable, self-consistent choice. Either way, not a blocker.

2. Section 2 is left behind by the sentence-case series. This PR is one of seven (Revised the Normative Reference to comply with ISO #136–Revised the Implementation examples to comply with iso #142) converting headings to ISO sentence case, and it is consistent with its siblings. But together they cover only §3–§9. Nothing in the open set touches 1. Introduction, 2. Scope, 2.1 AI Paradigms (Foundational Approaches), 2.2 Application-Specific AI Solutions, or 2.3 Emerging AI Technologies. After all seven merge, the §2 headings will be the only title-case headings left in the document. Suggest either folding them into this PR or opening an eighth to close the gap, so dev never lands in a half-converted state.

3. Clause numbering is still non-ISO. ISO/IEC drafting omits the period after a clause number (3 Normative references, not 3. Normative references), leaves Introduction unnumbered, and makes Scope clause 1. Fully aligning would renumber the whole document, so it is clearly out of scope for this PR — but if ISO compliance is the goal of this series, it is worth a tracking issue rather than letting it go unrecorded.

Process / merge risk

Seven open PRs all editing SPEC.md against dev is the main practical risk. GitHub currently reports this one MERGEABLE, but the first merge will likely require the rest to rebase, and #131 (from a fork) touches §2.3 Emerging AI Technologies, so it may conflict with any §2 follow-up. Worth agreeing a merge order on the weekly call — merging #136 through #142 back-to-back in one sitting, then #131, would minimise churn.

"Test coverage" equivalent

There is no automated markdown validation in CI — .github/workflows/ contains only the two Claude workflows. Adding a markdownlint check (or even a plain trailing-whitespace check) would have caught the nit above automatically and would pay off across a seven-PR editorial series like this one. Optional, but a cheap win for a spec-only repo.

---

🤖 Generated with Claude Code