Editorial and Normative reference updates

[seanmcilroy29]

Dev branch updated with Editorial and Normative reference updates in line with ISO requirements

[claude]

Review: Editorial and Normative reference updates

Reviewed against CLAUDE.md (spec-repo conventions, SPEC↔FAQ coupling) and the PR's stated goal of ISO alignment. Overall this is a solid editorial pass — the ISO boilerplate for normative references is correct, "End of Life" → "Retirement" resolves a long-standing term clash with Clauses 6/7, and the "Runtime Operations stage" body text now matches its own heading. Notes below, most-actionable first.

Verified: the arithmetic fixes are correct

I recomputed every changed figure and all four now check out — this PR fixes three real errors in the previous text:

Figure	Check
Consumer LLM: 6 500 kg ÷ 50e9 tokens	= 130 kg/billion = 130 g/million tokens ✅ (was 0.13 g/million — wrong by 1000×)
Provider LLM: 200 000 kg ÷ 5×10²²	= 4×10⁻¹⁸ kg/FLOP = 4 g/10¹⁵ FLOPs ✅
CV Provider: 75 000 kg ÷ 2,5 billion	= 30 000 kg/billion params ✅ (was 3000 in the calc and 30 in the reporting — two different wrong values)
CV Consumer: 3 200 kg ÷ 40e6	= 0,08 g/inference ✅

Showing the division inline in each EXAMPLE is a good call; it makes future drift detectable.

1. Markdown rendering regression in Terms and definitions (SPEC.md:65-107)

The two-space hard-break markers were stripped from the term entries. In .md files GitHub treats a single newline as a soft break (unlike in comments), so T.1 now renders as one run-together line:

T.1 functional unit quantified performance characteristic of an AI system that serves as...

Previously T.1·· / **Functional Unit**·· (trailing double-space) forced the ISO three-line layout. Please restore the trailing double-spaces (or use explicit <br>) on all of T.1–T.10. SPEC.md:96-97 (**floating point operation** / **(FLOP)**) collapses the same way.

2. ISO/IEC 5338:2023 is listed as normative but never cited (SPEC.md:52)

Per ISO/IEC Directives Part 2, only documents actually cited in the text such that their content constitutes requirements belong in Normative references — uncited documents go in a Bibliography. 21031 and 22989 are both cited (SPEC.md:5, SPEC.md:58); 5338 appears nowhere else in the file. Either cite it where it does normative work — the AI lifecycle stages clause is the obvious place, since those stages look 5338-derived — or move it to a Bibliography. Given the PR is specifically about normative references, worth resolving here.

3. Adding ISO/IEC 22989 as a terms source may clash with T.2/T.3 (SPEC.md:58, SPEC.md:71-77)

22989 already defines the role vocabulary (AI provider, AI producer, AI customer, AI user, AI subject) and also defines terms in the training/inference space. Now that it is invoked normatively for terminology, this document's bare provider / consumer (and possibly T.4 model training, T.5 inference) risk either duplicating or contradicting it. Worth a pass to confirm each of T.1–T.10 is genuinely new; where a 22989 term is being narrowed, ISO convention is to say so explicitly rather than silently redefine.

4. Normative contradiction: "one of" vs "may report multiple" (SPEC.md:229 vs SPEC.md:259)

• 229: "Provider functional units shall align with one of the following metrics..."
• 259: "Providers may report multiple functional units where feasible..."

As written the permission contradicts the requirement. This was latent before (SHALL align with one of + multiple functional units MAY be encouraged), but converting the second to a clean normative may sharpens it into a genuine conflict. Suggest shall align with at least one of the metrics in Table 2.

Also on 229: "one of the following metrics shown in Table 2, to normalize" — drop the stray comma and pick one pointer (following or shown in Table 2, not both).

5. The Table 1 NOTE carries a recommendation (SPEC.md:225)

"emissions should account for all triggered operations" is a recommendation inside a NOTE. Notes are informative only and cannot contain requirements, recommendations, or permissions — a validation reviewer will flag this. Promote it to body text immediately before or after the table, and keep the NOTE for the non-normative explanation. (SPEC.md:255 is fine — purely explanatory.)

6. Retirement still has no Consumer boundary basis (SPEC.md:138 vs SPEC.md:199)

The Consumer boundary is defined as Operation and Monitoring only, and Retirement appears solely in the Provider boundary list — yet "Retirement (Consumer and Provider)" imposes a conditional shall on both personas. There is nothing in Clause 6 a Consumer could scope that requirement against, and "included in the SCI calculation" doesn't say which of the two scores. Pre-existing, but this PR already fixed the sibling case (the LLM Provider boundary now correctly lists Inception, matching the Provider boundary), so it's a natural one to close out in the same pass.

Relatedly, the Provider calculation steps still itemise only data collection, training, optimization/testing and integration — no Inception or Retirement line items, even though the boundary now names both.

7. Clause numbering removed entirely

Unnumbering the Introduction is correct ISO practice, but removing numbers from every other clause goes further than ISO style, which requires numbered clauses (Scope = 1, Normative references = 2, Terms and definitions = 3) precisely so requirements can be cross-referenced. Consequences visible in this diff:

• SPEC.md:69 has to say "the Functional Unit clause of ISO/IEC 21031:2024" instead of a clause number.
• The T.1–T.10 scheme is non-ISO; ISO would use 3.1–3.10 (and T.n now can't be referenced from a numbered clause anyway).

If the intent is that numbering gets applied at publication, that's reasonable — but worth stating in the PR description so reviewers don't read it as a regression. Otherwise I'd keep numbers and switch the terms to 3.n.

8. Style consistency nits

• Unit spacing: gCO₂e / kgCO₂e at SPEC.md:262-264 vs g CO₂e / kg CO₂e everywhere else. SI wants the space; pick one.
• Decimal comma: 0,45 / 2,5 / 0,08 is ISO house style, so this is defensible — just confirm it's a deliberate decision for the GSF-published version too, since a comma decimal reads as a thousands separator to a lot of the target audience.
• Example scale spread: the Clause 8 illustration says 20 kgCO₂e per billion parameters while the Clause 9 CV example computes 30 000 kg/billion — a ~1500× spread between the document's own two examples. Both are internally correct, but a reader may take one as a plausibility anchor. Consider aligning the illustrative figure or noting that the models differ in scale.
• Case: headings moved to sentence case while list items and table cells stay Title Case (API and Inference, Data Collection Systems, Per Token). Fine if intentional, but the mixture is now more visible.
• Modal verbs: dropping RFC 2119 capitals for ISO lowercase is right for an ISO submission, but the document no longer tells a standalone reader how to interpret shall/should/may (ISO gets that from the Directives). ISO/IEC 21031 handles this with an explicit statement — consider adding one.

CLAUDE.md compliance

The FAQ-coupling rule checks out: FAQ.md already uses "Retirement" (FAQ.md:277, 306) and "Per Billion Parameters" (FAQ.md:161), and contains no clause-number references, so the renames and de-numbering don't invalidate it — no FAQ change is strictly required. Two optional tidies while nearby: FAQ.md:323 says "(per parameter, per FLOP)" where the unit is now named Per Billion Parameters, and FAQ.md:92 reads "Consumer & Providers (companies that build AI systems)" which looks like it should be "Providers".

On the other review dimensions

No code here, so bugs/performance/security/test coverage don't apply directly. The nearest equivalents: the arithmetic (verified above), the Markdown rendering regression in item 1 (the closest thing to a build break), and validation tooling — .github/workflows/ currently only has the Claude review workflows, so there's no markdown-lint or link-check gate. Given that this PR's main risk surface is exactly rendering and dead links, a lightweight lint/link-check job would be cheap insurance for future editorial passes. ANCILLARY.md:175,186 still uses "End of Life", which is consistent with CLAUDE.md's note that the file is slated for removal.

Recommendation: item 1 should be fixed before merge (visible rendering regression). Items 2, 4 and 5 are ISO-compliance points that will surface in validation and are cheap to fix now. The rest can be follow-ups.

[claude]

Review: Editorial and Normative reference updates (#146)

Reviewed the full SPEC.md diff (193 +/168 −) against FAQ.md and CLAUDE.md. This is a solid ISO-alignment pass — the modal-verb lowercasing (SHALL → shall), the ISO boilerplate in Normative references, the numbered/captioned tables, and the NOTE/EXAMPLE markers all move the document toward ISO/IEC Directives Part 2 style. A few things need attention before merge.

Verified correct ✅

I re-checked every arithmetic change; the corrections in this PR are right and fix real pre-existing errors:

Example	Before	After	Check
LLM Consumer reporting	0.13 g CO₂e/million tokens	130 kg CO₂e/billion tokens	6 500 kg ÷ 50e9 = 130 kg/billion ✅ (old value was off by 10⁶)
CV Provider calc	3000 kg/billion params	30 000 kg/billion params	75 000 ÷ 2,5 = 30 000 ✅
CV Provider reporting	30 kg/billion params	30 000 kg/billion params	now internally consistent ✅
LLM Provider FLOP conversion	(unchanged)	4 × 10⁻¹⁸ kg/FLOP = 4 g/10¹⁵ FLOPs	✅

Also good: adding Inception to the LLM Provider boundary (aligns with the Provider boundary clause and §Inception (Provider)), the End of Life → Retirement rename (removes a naming split with the coverage clause), the new T.9/T.10 gross value / effective value entries that back the prose in the reporting clause, and renaming Per Parameter → Per Billion Parameters, which now matches FAQ.md:161.

Issues

1. Terms and definitions will render as run-on paragraphs (SPEC.md:65-107)

The diff removed the trailing two-space hard line breaks after T.1, the bold term, etc. In GitHub-flavoured Markdown, consecutive lines in one block collapse, so all ten entries now render as:

T.1 functional unit quantified performance characteristic of an AI system that serves as…

instead of the three-line ISO term layout. Please restore the two trailing spaces (or use explicit blank lines / <br>). This affects every entry T.1–T.10, and it's a visible regression from the current main.

2. ISO/IEC 5338:2023 is listed as normative but never cited (SPEC.md:52)

ISO/IEC Directives Part 2 requires every entry in Normative references to be cited normatively in the body. grep finds no reference to 5338 outside the list itself. Either cite it where the lifecycle stages are introduced (the Inception → Retirement stages look derived from it — a citation there would strengthen the clause) or move it to a Bibliography. 21031:2024 and 22989:2022 are both properly cited, so only 5338 is affected.

3. Clause numbering was removed — cross-references now have nothing to point at

Dropping ## 1. Introduction … ## 9. matches ISO in the sense that Introduction is unnumbered, but ISO also requires numbered clauses (1 Scope, 2 Normative references, 3 Terms and definitions, …) precisely so text can cite them. Two places in the document now can't:

• SPEC.md:250 — "whether emissions are normalized using gross or effective values (see below)"; ISO wants "see 8.2.2".
• SPEC.md:69 — "described in the Functional Unit clause of ISO/IEC 21031:2024" should cite the clause number of the dated reference.

Related: terms are numbered T.1–T.10 rather than 3.1–3.10 under Clause 3. If the intent is ISO submission, restoring numbering and renumbering terms would be more consistent than the current half-way state. If the numbering removal was deliberate (e.g. to avoid renumber churn in PRs), it's worth a line in FAQ.md recording that decision.

4. Retirement boundary contradiction (pre-existing, but this PR is the natural place to fix it)

• SPEC.md:151-156 — Provider boundary includes Retirement.
• SPEC.md §"Retirement (Consumer and Provider)" — says it's in both SCI calculations.
• FAQ.md:306 — table marks Lifecycle: Retirement as Provider ✅ / Consumer ❌.

Two of three say Provider-only, so the coverage heading looks like the outlier. Per CLAUDE.md, whichever way this resolves, SPEC.md and FAQ.md should land together.

5. Example magnitudes are now mutually implausible

The arithmetic is right, but fixing it surfaced that the input numbers were never calibrated against each other:

• Provider EXAMPLE (SPEC.md:264): 20 kgCO₂e per billion parameters
• CV example (SPEC.md:353): 30 000 kg CO₂e per billion parameters — 1 500× higher, for a smaller model
• FAQ.md:172: GPT-3 at "~6.86 metric tons CO₂e per billion parameters"

A reader comparing the two SPEC examples will assume one is a typo. Suggest reworking the CV example's inputs (e.g. total emissions in the low thousands of kg) so the illustrative figures sit in the same order of magnitude as each other and as the FAQ's GPT-3 anchor.

6. Unit formatting inconsistency

SPEC.md:262-264 uses gCO₂e / kgCO₂e (no space) and "per", while SPEC.md:293-360 uses g CO₂e / kg CO₂e with /. ISO 80000-1 requires a space between the value and the unit. Suggest g CO₂e throughout and picking one of / or "per".

Two smaller ones in the same family:

• The three-space NOTE / EXAMPLE separators collapse to one space in rendered Markdown — fine to keep for the eventual ISO conversion, just don't expect the typography to survive on GitHub.
• The decimal comma (0,45, 2,5, 0,08) is correct ISO style and applied consistently within SPEC.md, but FAQ.md still uses decimal points (6.86, 5x). Worth a follow-up issue so the two documents don't diverge.

7. Minor wording (SPEC.md:229)

"shall align with one of the following metrics shown in Table 2, to normalize carbon emissions…"

"following" and "shown in Table 2" are redundant, and the comma splits the verb from its purpose clause. Suggest: "shall be one of the metrics in Table 2, used to normalize carbon emissions during AI model training."

Also note the normative asymmetry that this PR preserves: the Consumer table is explicitly "indicative and not exhaustive" while the Provider list is a closed shall align with one of. Presumably intentional, but if so it deserves an FAQ entry.

On the review dimensions requested

This repo is a specification, not code, so performance and security don't apply, and nothing here touches secrets or dependencies. The analogue of test coverage is document consistency, and there is currently no automation for it — .github/workflows/ contains only the two Claude workflows. Given that this PR fixed three arithmetic errors that had been sitting in main, a lightweight CI check (markdownlint + a link checker, and possibly a grep guard for stale terms like SHALL / End of Life) would have caught the formatting class of issues and would pay for itself.

Unrelated to this PR: ANCILLARY.md:173-175 still uses the old Runtime Operations / End of Life names, but CLAUDE.md notes that file is slated for removal, so I'd leave it.

Summary

Items 1 (rendering regression) and 2 (uncited normative reference) should be fixed before merge. 4 and 5 are content questions best settled on the weekly call. Everything else is polish. Nice catch on the arithmetic errors — those were real.

[claude]

Review: Editorial and Normative reference updates (#146)

Reviewed as an editorial/normative pass on SPEC.md, checked against FAQ.md and the change rules in CLAUDE.md. This is a solid step toward ISO drafting conventions, and it quietly fixes several real arithmetic errors. Below: verified fixes, then issues worth addressing before merge, then consistency nits and process notes.

Verified fixes (nice catches)

I re-checked every worked example; all four now compute correctly and agree with their "Reporting" subclause:

Example	Check	Result
LLM Consumer	6 500 kg / 50 x 10^9 tokens	130 kg CO2e per 10^9 tokens OK
LLM Provider	200 000 kg / 5 x 10^22 FLOPs	4 x 10^-18 kg/FLOP = 4 g/10^15 FLOPs OK
CV Consumer	3 200 kg / 40 x 10^6 inferences	0,08 g CO2e/inference OK
CV Provider	75 000 kg / 2,5 x 10^9 params	30 000 kg CO2e per 10^9 params OK

Two of these repair pre-existing errors that are worth flagging in the weekly call, because they change published numbers:

• LLM Consumer reporting previously read 0.13 g CO2e/million tokens; the calculation yields 130 kg/billion tokens = 130 g/million tokens — the old figure was off by 1 000x.
• CV Provider previously said 3000 kg/billion parameters in the calculation and 30 kg/billion parameters in the reporting; neither matched 75 000 / 2,5 = 30 000.

Also good: End of Life -> Retirement (aligns the lifecycle-stages clause with the coverage clause, which already said Retirement); Per Parameter -> Per Billion Parameters (the description always said "per billion"); and adding Inception to the LLM Provider example boundary so it matches the Provider boundary clause.

Issues to address before merge

1. Markdown hard line breaks were dropped in Terms and definitions (SPEC.md:65-106) — rendering regression. The old entries ended with two trailing spaces (T.1··, **Functional Unit**··); those are gone, so T.1, T.2, T.3, T.5, T.7 and T.8 now render as single run-on paragraphs on GitHub:

T.1 functional unit quantified performance characteristic of an AI system that serves as the reference unit for carbon intensity calculation

Restore the two-space breaks (or use a trailing \, or put the term on its own paragraph). T.4/T.6 already had this defect before the PR, so applying the fix uniformly across all ten entries is the win here.

2. ISO/IEC 5338:2023 is listed as normative but never cited in the text (SPEC.md:52). The clause's own boilerplate says these documents are "referred to in the text in such a way that some or all of their content constitutes requirements" — 5338 is not referred to anywhere in the body. Per ISO/IEC Directives Part 2, an uncited reference belongs in a Bibliography. Either move it there, or genuinely cite it: e.g. in AI lifecycle stages, state how the five stages used here (Inception / Design and development / Deployment / Operation and monitoring / Retirement) relate to 5338's life cycle processes. That mapping is the substantive question adding the reference raises, and readers will ask it.

3. T.1 redefines a term imported from a normative reference (SPEC.md:58, 65-69). The clause imports the terms of ISO/IEC 21031:2024, then T.1 defines functional unit again — and the new paragraph at line 69 says outright that it "adapts" 21031's concept. An adapted redefinition of an imported term is a conflict, not a clarification. Options:

• drop T.1 and rely on 21031's definition; or
• rename the entry to AI functional unit so it is clearly a distinct term; and
• either way, recast line 69 as Note 1 to entry: and cite a clause number (ISO/IEC 21031:2024, x.y) rather than "the Functional Unit clause" — citing a normative reference by clause name is imprecise.

While you are in this clause, it is worth checking T.4 (model training), T.5 (inference), T.6 (token) and T.7 (parameter) against ISO/IEC 22989:2022 now that it is imported at line 58. Where 22989 already defines a concept, ISO drafting practice is to cite it rather than define a local variant.

4. The NOTE at SPEC.md:225 contains a recommendation. "...emissions should account for all triggered operations..." was normative body text before this PR (SHOULD). Notes shall not contain requirements or recommendations, so converting it to a NOTE demotes guidance that matters a great deal for agentic and multi-call systems. Move it back into the body as a should sentence. (The NOTE at line 255 is fine — genuinely explanatory.)

5. Nothing states the verbal-form convention. Replacing SHALL/SHOULD/MAY with lowercase ISO forms is the right direction, but readers of a GSF pre-draft arrive with RFC 2119 expectations. Add one sentence in the Introduction or a short Conformance clause: "In this document, 'shall' indicates a requirement, 'should' a recommendation, 'may' a permission, and 'can' a possibility or capability."

6. Removing clause numbering removes the ability to cross-reference. ISO documents are numbered (Scope = 1, Normative references = 2, Terms and definitions = 3), and the consequences already show in this diff: SPEC.md:250 says "(see below)" where it should point at T.9/T.10, and SPEC.md:253 re-states those two definitions in prose instead of referencing them. It also changes every heading anchor — nothing in-repo links to SPEC.md#... today, but external links and past meeting minutes may. I would restore numbered clauses and replace "(see below)" with "see T.9 and T.10", unless the publishing toolchain is expected to auto-number; worth confirming in the call.

Consistency items (mostly pre-existing, but this is the editorial pass)

• Retirement boundary contradiction: the Provider boundary includes Retirement (SPEC.md:156), coverage is titled "Retirement (Consumer and Provider)" (SPEC.md:199), yet the Consumer boundary is defined as Operation and Monitoring only (SPEC.md:138). Since this PR renames the stage, it is a good moment to resolve it — either add Retirement to the Consumer boundary clause or scope line 199 to Provider.
• shall vs may conflict on functional units: "shall align with one of the following metrics" (SPEC.md:229) vs "Providers may report multiple functional units" (SPEC.md:259). Suggest "shall be one or more of the metrics in Table 2". Line 229 also reads awkwardly: "one of the following metrics shown in Table 2, to normalize" has a redundant "following/shown" plus a stray comma.
• Notation is now mixed: 0,45 g CO2e per 10^12 FLOPs (262) vs 4 g CO2e/10^15 FLOPs (327) — pick "per" or the solidus. The division sign in running prose (296, 320, 342, 353) is unusual for ISO text. Magnitudes mix digits and words ("50 billion", "2,5 billion"). Please also confirm g CO2e (with space) against the notation used in ISO/IEC 21031:2024, since readers will hold the two documents side by side.
• Decimal comma is now repo-inconsistent: SPEC.md uses 0,08 / 2,5, while FAQ.md and ANCILLARY.md use decimal points. Either follow through repo-wide or state the convention, otherwise the mixed style reads as a typo.
• Heading case vs defined stage names: headings are sentence case ("Design and development") while body text keeps title case ("the Design and Development stage"). The stage names function as defined labels, so one form should win. Same mismatch in the coverage headings, which pair sentence case with a capitalised parenthetical: "Operation and monitoring (Consumer)".
• Leftover pre-edit voice: SPEC.md:268 still reads "This section provides examples of how to apply the SCI for AI specification..." — converted to "this document" elsewhere; ISO would say "This clause".
• http://www.electropedia.org/ (SPEC.md:63) — pre-existing, but ISO's current boilerplate uses https://. Cheap fix while the clause is open.

Process and validation

• CLAUDE.md change rule: this PR touches SPEC.md only. Nothing in FAQ.md is outright contradicted, but the Per Parameter -> Per Billion Parameters rename leaves FAQ.md:323 and FAQ.md:326 describing the unit as "per parameter". A matching touch-up keeps the two documents aligned, and a short FAQ entry explaining why the document moved to ISO verbal forms and ISO reference style would help reviewers who only read the FAQ.
• No automated checks exist: .github/workflows/ contains only the Claude review jobs. Given that issue 1 above is a whitespace-sensitive rendering regression, a markdownlint job (with the hard-break/MD009 rules configured deliberately rather than left at defaults) plus a link checker such as lychee would catch exactly this class of problem before human review. That is the closest analogue to test coverage for a spec repo.
• Nothing security- or performance-relevant here: no code, no dependencies, no secrets; the only external URLs are iso.org and electropedia.

Summary

The arithmetic and terminology fixes are real improvements and should land. I would treat items 1-4 as merge blockers (a rendering regression, an uncited normative reference, a redefined imported term, and a recommendation demoted into a NOTE), and items 5-6 plus the Retirement contradiction as decisions for the weekly call rather than for the author alone.