feat(achievements): add Product Achievements grading axis

[foadshafighi]

Summary

Adds Product Achievements, a second computed grading axis alongside the existing
data-completeness ladder. Both are pure computed views over one Master Ledger of the
attestations a record already carries. This is the v1.0.0 milestone: ULC's first formal
backward-compatibility commitment, delivered as an additive-only change (no field, token,
or code is removed or narrowed).

The achievements axis reports, per theme (embodied carbon, circularity, material health,
energy, dark sky, emergency), whether a record is none, claimed, or documented, where
the claimed/documented split is driven purely by whether an evidence document (a
sha256-anchored source_document_ref) is attached. Expiry is record-relative
(valid_until vs record_status_as_of, never wall-clock), so the output is reproducible.

What is in it

• New internal/achievements/ package: a pure, total Compute(record) that merges the
  ledger, applies status disqualifiers and record-relative expiry, and returns per-theme
  state, documented_count, the restricted-substances flag, and a claimed-to-documented
  roadmap. Kept decoupled from completeness by a copy-not-import boundary enforced by an
  AST-level import-graph test.
• Schema (additive only): new EmbodiedCarbonScope, CircularityTier, and
  AchievementState enums; Attestation.sustainability_metric and issuing_authority;
  and the generated index.achievements and index.restricted_substances_declared members.
• Builder v0.6.0: stamps the two new index members with strict JSON normalization
  (int64 counts, non-nil arrays, map nesting) so the stored index round-trips through Diff
  without false drift.
• CLI: emits a default-visible achievements summary plus verbose per-theme state and
  roadmap findings.
• Docs: methodology, how-it-works, compliance-attestation, README, and ROADMAP updated
  to describe both axes and the additive-only commitment; CHANGELOG v1.0.0 entry.

Compatibility

• Every schema change is a new optional field, def, or enum. Nothing is removed or narrowed.
• Conformance grades and completeness findings are byte-identical; the eight example records
  re-stamp only their builder_version (0.5.0 -> 0.6.0) plus the two additive index members.
  Authored ulc_version is unchanged (five at 0.8.0, three at 0.10.0), which is the live
  proof of the compatibility commitment.
• Each stored record re-stamps with ulc build-index to gain the two new index members.

Review status

• Multi-agent review across correctness, architecture, testing, performance, security,
  simplicity, and pattern-consistency: all findings resolved or backlogged; zero P1.
• Greptile CLI review of this branch against main: 5/5 confidence, zero findings, no
  security concerns.

Test plan

• go build ./..., go vet ./... clean
• go test ./... -count=1 green across all packages (race-clean)
• gofmt clean
• All 8 example records validate one-at-a-time and pass ulc build-index --check
• Conformance level unchanged on all 8 examples (pinned by test)

Callouts for reviewers

1. internal/achievements/compute.go is the core: the state ladder, record-relative expiry,
   evidence gate, and best_metric_ref selection (which requires an attestation_id).
2. The declaration-type to program-token mapping is single-sourced in the achievements
   package and read by the index builder through DeclarationProgramToken, so
   index.attestation_programs and the material-health theme cannot drift.
3. internal/index/builder.go achievements emission uses the type-strict normalization that
   keeps index.Diff stable; the round-trip is guarded by TestAchievementsIndexRoundTrip.

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds Product Achievements as a second generated grading axis, updates schema/index builder/examples/docs, and adds achievement tooling/tests.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• tools/validator/internal/achievements/compute.go:65: best_metric_ref is selected for embodied-carbon/circularity themes whenever any sustainability_metric object exists, without checking that the metric actually represents that theme. An epd_iso_14025 attestation with only ceam_score, or a tm66_assured attestation with only embodied_carbon_kgco2e, can become the theme’s “best” metric reference, contradicting schema/ulc.schema.json:296 and the theme definitions in docs/compliance-attestation.md:179. Fix by adding theme-specific metric predicates before setting bestRef and add regression tests for mismatched metric payloads.

P2 - Medium Priority Issues (Consider Fixing)

• tools/validator/internal/achievements/compute.go:202: hasEvidence treats any non-empty sha256 string as evidence. FileReference requires filename and a 64-char lowercase hex SHA-256 at schema/ulc.schema.json:441 and schema/ulc.schema.json:443, but ulc build-index can run before schema validation and would stamp malformed refs like {"sha256":"x"} as documented. Fix by checking non-empty filename and matching the SHA-256 pattern, then add hostile-input tests for wrong length, uppercase/non-hex, and missing filename.
• CHANGELOG.md:25 / CHANGELOG.md:38: the release notes call the schema change “additive in the strict sense” and “optional,” but schema/ulc.schema.json:283 now requires index.achievements and index.restricted_substances_declared. The later migration note at CHANGELOG.md:31 is accurate. Reword the summary/header so consumers do not read this as an optional schema addition.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• JSON syntax checks passed for both schemas and all examples.
• Cross-file $ref resolution passed in static inspection.
• The new achievement/index parity tests are focused on deterministic output, non-nil arrays, and generated-index drift, which is the right failure surface for this PR.
• No .github workflow or research/ files were changed.

Note: I could not run go test ./... because this environment is read-only and Go could not create a build cache under /tmp.

---

Automated review by OpenAI Codex

[greptile-apps]

Greptile Summary

This PR introduces Product Achievements, a second computed grading axis alongside the existing data-completeness ladder. The change is fully additive: no field, token, or finding code is removed, and every conformance grade on the eight example records is byte-identical after re-stamping.

• New internal/achievements/ package: a pure, total Compute(record) walks the merged attestation ledger once and returns per-theme state (none/claimed/documented), documented_count, the restricted_substances_declared flag, and a claimed-to-documented roadmap. Isolated from completeness by a copy-not-import boundary enforced by an AST-level invariant test; expiry is record-relative, making index.achievements fully reproducible.
• Schema (schema/ulc.schema.json, schema/taxonomy.schema.json): three new enums and two new optional Attestation fields; index gains achievements and restricted_substances_declared as required, always-stamped generated members. All changes are additive.
• Builder v0.6.0: achievementsIndex emits strictly typed values so the nested subtree round-trips through Diff's reflect.DeepEqual path without false drift; guarded by TestAchievementsIndexRoundTrip.

Confidence Score: 5/5

Safe to merge — purely additive schema and purely computed index fields; no authored data removed or narrowed.

Every schema change is an optional addition or a new required-but-always-generated index field. The core Compute function is pure, total on hostile input, and produces deterministic output because expiry is record-relative. The copy-not-import boundary is enforced by an AST-level test. The type-normalization path that keeps Diff stable for the nested achievements map is guarded by TestAchievementsIndexRoundTrip. The enum exhaustiveness test forces conscious triage of any future AttestationProgram token. RequiredKeys in Go exactly mirrors the updated Index.required in the schema. No error paths are swallowed, no panics in library code, and all eight example records re-stamp cleanly.

No files require special attention.

Important Files Changed

Filename	Overview
tools/validator/internal/achievements/compute.go	Core computation engine — pure, total on hostile input, correctly separated from completeness. State ladder, evidence gate, expiry, status disqualifiers, and best_metric_ref selection are all logically sound and well-tested.
tools/validator/internal/achievements/themes.go	Program-to-theme classification; exhaustiveness guard enforced by TestEnumPartitionExhaustive. DeclarationProgramToken export is the single source of truth for declaration-to-program mapping consumed by both Compute and the index builder.
tools/validator/internal/index/builder.go	achievementsIndex uses strict JSON-normalized types (int64 via numberToJSON, non-nil []any, map[string]any) so Diff's reflect.DeepEqual comparison against a re-normalized stored record stays stable. RequiredKeys matches schema.
schema/ulc.schema.json	achievements and restricted_substances_declared added to Index.required; AchievementTheme $def added; sustainability_metric and issuing_authority added to Attestation; all changes are additive. The if/then conditional for embodied_carbon_kgco2e is correct Draft 2020-12 syntax.
schema/taxonomy.schema.json	Three new enums (EmbodiedCarbonScope, CircularityTier, AchievementState) added; AttestationProgram description updated to clarify ICEL as an emergency qualification. All additive.
tools/validator/internal/achievements/invariant_test.go	Covers REPRODUCIBLE-INPUTS-ONLY, kitchen-sink negative, mutation-safety, completeness isolation, and the AST-level copy-not-import boundary — a strong invariant suite.
tools/validator/internal/achievements/themes_test.go	Exhaustiveness guard (TestEnumPartitionExhaustive) verifies every AttestationProgram token is consciously placed; disjointness and real-enum-member checks close the classification against the taxonomy schema.
tools/validator/cmd/ulc/main_test.go	TestAchievementsIndexRoundTrip guards the nested-map type normalization path; TestManufacturerRecycleProgramIndexValidates pins schema-validity for the zero-program circularity claimed edge case.
tools/validator/internal/findings/findings.go	Three new achievement Code constants added; WriteText updated to suppress CodeAchievementsState and CodeAchievementsRoadmap in non-verbose mode alongside existing enrichment/observation suppression. Logic is consistent.
tools/validator/cmd/ulc/main.go	achievements.Report added to both the validate and from-sheet paths. Flag help text and usage description updated. No exit-code or error-handling changes.

_{Reviews (5): Last reviewed commit: "docs(achievements): correct the roadmap ..." | Re-trigger Greptile}

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds v1.0.0 Product Achievements axis, generated index fields, sustainability attestation metrics, docs, examples, and validator support.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• schema/ulc.schema.json:1424 adds embodied_carbon_kgco2e as a bare scalar. This violates ULC’s dual-unit policy for mass-like quantities: SI can be authoritative, but the Imperial companion is still required. Fix by modeling embodied carbon as a dual-unit object, e.g. kgco2e plus lbco2e with SI authoritative, or introduce a dedicated DualUnitCarbonEquivalent shape and update docs/tooling references accordingly.

• tools/validator/internal/achievements/themes.go:45 routes just_label into the material_health achievement theme, and docs/compliance-attestation.md:181 publishes the same mapping. But docs/compliance-attestation.md:88 defines JUST as a social-justice/equity transparency label for the manufacturing organization, not a product material-health disclosure. That fails the fixture-relevance/product-achievement boundary and can falsely badge a fixture for material health. Remove just_label from materialHealthPrograms and the theme table; place it in the deliberately unthemed organization-level bucket or defer it to a future social-responsibility theme.

P2 - Medium Priority Issues (Consider Fixing)

• docs/compliance-attestation.md:194 says living_product_challenge qualifies “a building or an organization,” while docs/compliance-attestation.md:86 correctly describes it as an ILFI product-level certification. The code comment in tools/validator/internal/achievements/themes.go:142 repeats the same grouping. If it remains unthemed, document it as a deliberately unthemed multi-attribute product certification, not as project/company-level.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• JSON syntax is valid for both schema files, and all $ref targets resolve.
• No changed files under research/.
• Generated example indexes are consistently restamped to builder 0.6.0.
• The achievements compute is deterministic and record-relative rather than wall-clock dependent.

I could not run go test ./... because the environment is read-only and Go could not create its build cache. Static checks run: jq empty, $ref target resolution, and git diff --check.

---

Automated review by OpenAI Codex

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds Product Achievements as a second computed grading axis, updates schema/index projections, validator reporting, examples, and docs for v1.0.0.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• schema/taxonomy.schema.json:1252, docs/compliance-attestation.md:173, docs/methodology.md:307 contradict the implemented expiry behavior. These lines define claimed as “no evidence document attached” and documented as “attached evidence document,” but tools/validator/internal/achievements/compute.go:81 intentionally downgrades an evidence-backed attestation with valid_until < record_status_as_of to claimed, not none. That creates a state with evidence attached and state: claimed, contradicting the state definitions. Fix by redefining claimed as “a qualifying contribution exists but no current/non-expired evidence supports documented” and defining documented as requiring attached, non-disqualified, non-expired evidence.

P2 - Medium Priority Issues (Consider Fixing)

• schema/ulc.schema.json:441 allows FileReference.filename to be an empty string, but tools/validator/internal/achievements/compute.go:220-238 treats an empty filename as no evidence and the comment says a non-empty filename is “the schema’s own FileReference contract.” This means a schema-valid source_document_ref with filename: "" and a valid SHA-256 will validate but will not document an achievement. Fix by adding "minLength": 1 to FileReference.filename, or loosen hasEvidence and update the docs/comments.

P3 - Low Priority Issues (Optional)

• tools/validator/cmd/ulc/main.go:88 and tools/validator/cmd/ulc/main.go:93-99 still describe --verbose and validate as conformance-only / four-check behavior. The command now also emits achievements findings as step 5. Update the flag help and usage text so users know --verbose also reveals achievements/state and achievements/roadmap.

Positive Observations

• The schema parses cleanly, changed $refs resolve, enum values are unique strings, and required arrays point to existing properties.
• The taxonomy/record-schema split is preserved: new enums live in taxonomy.schema.json, while structural achievement and metric shapes live in ulc.schema.json.
• The achievements builder path is deterministic and has focused parity/exhaustiveness tests.
• No files under research/ are added.

Note: I could not run go test because the sandbox is read-only and Go could not create a build cache.

---

Automated review by OpenAI Codex

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds Product Achievements as a second computed grading axis, extends the generated index, schema, docs, examples, and Go validator.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• tools/validator/internal/achievements/compute.go:228 promotes malformed source_document_ref evidence to documented when the object has a valid sha256 but no filename. That does not match schema/ulc.schema.json:447, where FileReference requires both filename and sha256, nor the docs at docs/methodology.md:314, which say the evidence reference has both. This can make ulc build-index stamp index.achievements.*.state = documented from a reference that schema validation rejects. Fix hasEvidence to require a schema-shaped FileReference at minimum: filename present as a string and sha256 matching the hash pattern. Update the tests at tools/validator/internal/achievements/compute_test.go:167 so “filename absent” is not accepted as documented.

• docs/methodology.md:307 and docs/compliance-attestation.md:173 describe status-disqualified evidence as capping a theme at claimed, but docs/methodology.md:320 and the implementation at tools/validator/internal/achievements/compute.go:78 say expired, withdrawn, and not_applicable contribute nothing. This is a spec logic contradiction for implementers. If the code is intended, remove “disqualified by status” from the claimed definition and state that status-disqualified attestations produce none; only record-relative expiry caps otherwise qualifying evidence at claimed.

P2 - Medium Priority Issues (Consider Fixing)

None found.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• Schema JSON parses cleanly, all 259 $ref pointers resolve, required arrays point to existing properties, and changed enums are unique strings.
• The schema/taxonomy split is maintained: new vocabularies are in taxonomy.schema.json, while structural achievement and sustainability payloads are in ulc.schema.json.
• No workflow or research/ files are changed.
• The new achievements package has useful guards for deterministic output, theme partitioning, builder parity, and completeness isolation.

Note: I could not run go test ./... because the review environment is read-only and Go cannot create a build cache, even under /tmp. I did run read-only schema and JSON checks.

---

Automated review by OpenAI Codex

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds Product Achievements as a generated second grading axis, with schema/index additions, validator reporting, examples, and docs.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• README.md:51, docs/how-it-works.md:72, docs/methodology.md:242 describe documented as simply “an evidence document is attached.” That contradicts the actual rule in tools/validator/internal/achievements/compute.go:81 and the more precise docs in docs/methodology.md:307-320: an attached document only supports documented when the attestation is non-disqualified and the evidence is not expired relative to record_status_as_of. Fix these summaries to say “attached, unexpired evidence on a non-disqualified attestation”; otherwise consumers can implement the axis incorrectly.

P2 - Medium Priority Issues (Consider Fixing)

None found.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• The schema split is preserved: new enum vocabularies are in schema/taxonomy.schema.json, and structural generated-index shapes are in schema/ulc.schema.json.
• The achievements implementation has good drift guards around enum partitioning, builder parity, generated-index round-tripping, and completeness isolation.
• Evidence references reuse FileReference, keeping the mandatory SHA-256 rule intact.

Note: I could not run go test ./tools/validator/... because this environment is read-only, including /tmp, so the Go build cache could not be initialized. I did run JSON parsing and a read-only $ref / required sanity check successfully.

---

Automated review by OpenAI Codex

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds Product Achievements as a second generated grading axis, extends attestation sustainability metadata, restamps examples, and wires validator/index tooling.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

None found.

P2 - Medium Priority Issues (Consider Fixing)

• ROADMAP.md:38 says “every schema change is a new optional field, def, or enum,” but this PR changes schema/ulc.schema.json:283 by adding index.achievements and index.restricted_substances_declared to Index.required. That is not an optional schema-only addition, even if it is confined to generated index restamping. Fix the roadmap wording to match CHANGELOG.md: authored surface is additive, but generated index required members changed and stored records need ulc build-index.

• docs/methodology.md:314 says “the named program on the attestation is the issuing authority,” but this PR adds schema/ulc.schema.json:1414 issuing_authority specifically for the named program operator. For EPDs, for example, program: epd_iso_14025 is not the operator. Fix the doc to distinguish the program token from issuing_authority, and say the latter should carry the operator when relevant.

P3 - Low Priority Issues (Optional)

• CHANGELOG.md:55 says achievements findings are emitted “immediately after the conformance findings,” but rendered output is sorted by code in tools/validator/internal/findings/findings.go:199, so achievements/* appears before conformance/* in the committed golden output (tools/validator/internal/completeness/testdata/golden/erco-quintessence-30416-023.txt:1). Reword this as “the validator adds achievements findings” or explicitly note rendered order is code-sorted.

Positive Observations

• JSON syntax and cross-file $ref resolution are clean in both schema files.
• New achievement taxonomy values live in taxonomy.schema.json, while generated index structure stays in ulc.schema.json.
• The builder, schema Index.required, examples, and golden outputs are aligned for the new 0.6.0 index shape.
• No workflow files or research/ files are changed.

Verification note: I could not run go test ./... because this environment is read-only, including /tmp, so Go could not create a build cache.

---

Automated review by OpenAI Codex

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds Product Achievements as a second generated grading axis, updates schema/docs/examples, and wires validator/index tooling for v1.0.0.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

None found.

P2 - Medium Priority Issues (Consider Fixing)

None found.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• Schema split is preserved: new enums stay in schema/taxonomy.schema.json, while generated index and attestation payload shapes stay in schema/ulc.schema.json.
• The achievements builder output is always stamped and covered by parity/round-trip tests, including empty-array handling for nested generated fields.
• The docs consistently explain the trust boundary: documented means attached evidence is present, not ULC verification.
• No workflow changes, no research/ files, and no enum leakage into ulc.schema.json.

I ran a read-only schema sanity check for JSON parse, $ref resolution, required-property consistency, enum uniqueness, and example index presence. I did not run go test because this session’s filesystem is read-only and Go tests require writable cache/temp space.

---

Automated review by OpenAI Codex