Prepare v1.0 release closeout records

[jaharris87]

Summary

Closes #354.

This PR prepares the v1.0.0 release closeout records without changing runtime behavior or broadening release claims:

• adds docs/release-notes-v1.0.0.md as the source-only v1.0.0 release-notes draft
• adds docs/release-validation-v1.0.0.md with local validation commands, exact toolchain/skips, artifact closeout, benchmark handling, and post-release triage expectations
• links the new closeout records from docs/release.md
• adds both new records to ftimer_release_docs_contract link/path validation

The release notes keep #353's MPICH MPI+OpenMP boundary caveated, keep #355/#294/#259/#256 as post-release or non-blocking follow-ups, and make no benchmark trend claim because no committed CSV+sidecar provenance evidence is being attached.

Local Validation

• cmake -B build-smoke
• cmake --build build-smoke
• cmake -E chdir build-smoke ctest --output-on-failure -> 25/25 passed
• FC=gfortran cmake -B build -DFTIMER_BUILD_TESTS=ON -DPFUNIT_DIR=/opt/homebrew/PFUNIT-4.16
• cmake --build build
• cmake -E chdir build ctest --output-on-failure -> 26/26 passed
• FC=mpifort cmake -B build-mpi -DFTIMER_USE_MPI=ON -DFTIMER_BUILD_TESTS=ON -DPFUNIT_DIR=/opt/homebrew/PFUNIT-4.16 -DMPIEXEC_EXECUTABLE=/opt/homebrew/bin/mpiexec
• cmake --build build-mpi
• cmake -E chdir build-mpi ctest --output-on-failure -L mpi -> local CTest launcher failed before pFUnit tests with Open MPI reporting All nodes which are allocated for this job are already filled; direct generated mpiexec -n 2 .../ftimer_mpi_tests --verbose passed 79 tests and mpiexec -n 4 .../ftimer_mpi_tests_4pe --verbose passed 22 tests
• FC=mpifort cmake -B build-mpi-openmp -DFTIMER_USE_MPI=ON -DFTIMER_USE_OPENMP=ON
• cmake --build build-mpi-openmp
• cmake -E chdir build-mpi-openmp ctest --output-on-failure -> 35/35 passed
• FC=gfortran cmake -B build-openmp -DFTIMER_USE_OPENMP=ON -DFTIMER_BUILD_TESTS=ON -DPFUNIT_DIR=/opt/homebrew/PFUNIT-4.16
• cmake --build build-openmp
• cmake -E chdir build-openmp ctest --output-on-failure -> 31/31 passed
• cmake -S . -B build-bench -DFTIMER_BUILD_BENCH=ON -DCMAKE_BUILD_TYPE=Release
• cmake --build build-bench --target ftimer_bench
• ./build-bench/bench/ftimer_bench /tmp/ftimer_bench_results.csv -> wrote a 52-line CSV used only as smoke/review evidence, not as release-note trend evidence
• cmake -E chdir build-smoke ctest --output-on-failure -R '^ftimer_release_docs_contract$' -> passed
• git diff --check

Local Skips / Caveats

• flang-19 was not on PATH locally; default smoke/bench configures used Homebrew /opt/homebrew/bin/flang 22.1.7 where CMake selected it.
• MPICH was not run locally because the local mpifort/mpiexec pair is Open MPI 5.0.9 and mpifort.mpich was not on PATH.
• Direct Spack/EasyBuild execution was not run because package-manager ownership remains post-v1.0 (Strategic question: decide package-manager ownership after v1.0 #355), and neither spack nor eb was on PATH locally.
• NVHPC was not run and is not claimed (Investigate NVHPC nvfortran serial smoke validation #256).

Required CI / Review Gates

Before merge, this PR still needs all CI jobs from .github/workflows/ci.yml, Codex Review Routing and Triggers, and Codex Review Coverage green on the PR head.

[jaharris87]

@codex review as a senior software engineer reviewing this fTimer PR for correctness; inspect changed code, changed tests, and changed user-facing docs, then find behavior regressions, wrapper or OOP parity drift, install or export breakage, unsafe defaults, silent lossy behavior, summary or output regressions, and missing end-to-end validation, not style issues; when timer runtime paths change, explicitly sanity-check start or stop ordering, context attribution, and docs/tests parity; classify findings as bug, test gap, design concern, or nit; begin with "## Software Review".

[chatgpt-codex-connector]

Codex review is not enabled for this repo. Please contact the admins of this repo to enable Codex.

[jaharris87]

@codex review as a docs and contract reviewer; compare touched README, docs, examples, maintainer guidance, and workflow text against the implemented code and tests, looking for contract drift, docs mismatch, workflow mismatch, example drift, or clarity concerns; cite the file and statement for each finding; begin with "## Docs / Contract Review".

[chatgpt-codex-connector]

Codex review is not enabled for this repo. Please contact the admins of this repo to enable Codex.

[jaharris87]

@codex review as a skeptical fTimer test reviewer; decide whether the changed tests would fail for broken start or stop ordering, repair timestamp consistency, callback suppression during repair, self-time sibling boundaries, error-contract mistakes, MPI mismatch handling, and worker-thread no-op behavior, and whether mocks or golden tests create false confidence; classify findings as test gap, weak assertion, false confidence, flaky risk, or design concern; begin with "## Test Quality Review".

[chatgpt-codex-connector]

Codex review is not enabled for this repo. Please contact the admins of this repo to enable Codex.

[jaharris87]

@codex review as a build and portability reviewer; check serial, MPI, smoke, installed-consumer, CI, and CMake or Make behavior for compiler assumptions, config drift, packaging issues, and environment leakage; cite the file and failing mode for each finding; begin with "## Build / Portability Review".

[chatgpt-codex-connector]

Codex review is not enabled for this repo. Please contact the admins of this repo to enable Codex.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: f52ee85a6248cf35e35675420af551ee4205eb77
Fallback wave: 1
Role: software
Outcome: no-findings
Source: fresh-context subagent

Software Review

No actionable correctness, test, or design findings found.

Required questions:

1. Does this diff change public behavior? No runtime behavior, API signatures, CLI output, defaults, or file formats change. This is release documentation plus adding the new release docs to the release-docs contract path/link validation.

2. Are docs, CLI help, and tests updated together with the behavior change? No behavior change is introduced. The docs are updated in docs/release-notes-v1.0.0.md, docs/release-validation-v1.0.0.md, and docs/release.md; CLI help is not applicable; tests/check_release_docs_contract.cmake now includes both new docs in its required path/link validation.

3. Are new defaults safe? Not applicable. No defaults are changed.

4. Is any behavior silently lossy or imputed? No new behavior is added. The new release docs explicitly avoid benchmark trend claims, call out unavailable local validation, and keep caveats for MPICH MPI+OpenMP, package-manager support, and NVHPC validation.

5. Is there an end-to-end test path for the new feature? For the documentation change, yes: ftimer_release_docs_contract covers required release-facing paths and Markdown links, including the two new files. I also ran the contract script directly with cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake, and it passed. Runtime features mentioned by the release docs are not newly implemented in this PR and remain covered by the existing test/CI paths cited in the release evidence.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: f52ee85a6248cf35e35675420af551ee4205eb77
Fallback wave: 1
Role: docs-contract
Outcome: no-findings
Source: fresh-context subagent

Docs / Contract Review

Findings: None.

Required questions:

1. What does main guarantee after this diff?
   After this diff, main documents a source-only v1.0.0 release-prep package: a release-notes draft, a validation/artifact record, release checklist links, and contract-test coverage for those docs. The stated guarantees remain bounded to the existing release evidence: serial/local timing, pure MPI, OpenMP compatibility, explicit ftimer_openmp_t, strict/sparse hybrid output, stable CSV/export claims, and installed CMake package behavior. The new docs state that clearly and correctly.

2. Do any docs describe deferred or future behavior as if it already exists?
   No. Package-manager support, fixed-team/no-explicit-region OpenMP ergonomics, Ubuntu 24.04 MPICH pFUnit runner migration, NVHPC validation, profiler backends, hardware counters, traces, dashboards, FPM, binary packages, and benchmark trend claims are kept as deferred, non-goal, or unclaimed items.

3. Are README, CLAUDE.md, maintainer docs, examples, and TODO.md mutually consistent after this change?
   Yes for the reviewed scope. The new release draft and validation record align with README/CLAUDE/AGENTS support boundaries, docs/release.md, docs/release-evidence.md, docs/installed-api.md, docs/csv-schema.md, and the named examples. TODO.md is not present in this checkout, so there is no TODO consistency point to evaluate.

4. Are current-state behavior and target design clearly separated?
   Yes. The current implemented/release-supported surfaces are separated from post-release or unclaimed work, and the validation record explicitly distinguishes local evidence, required CI proof, unavailable local toolchains, and source-only release artifacts.

5. Would a new contributor or coding agent be likely to misunderstand what is implemented today? If so, where?
   No actionable misunderstanding found. The added docs repeatedly route claim decisions through docs/release-evidence.md, keep MPICH MPI+OpenMP caveated, keep package-manager material guidance-only, and avoid benchmark or binary-artifact overclaims.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: f52ee85a6248cf35e35675420af551ee4205eb77
Fallback wave: 1
Role: test-quality
Outcome: findings
Source: fresh-context subagent

Test Quality Review

Findings

1. test gap — tests/check_release_docs_contract.cmake only adds the two new v1.0.0 release docs to required_paths, so they get existence and Markdown-link checks, but not semantic contract checks. See tests/check_release_docs_contract.cmake:18-19 and the generic link loop at tests/check_release_docs_contract.cmake:33-63. A broken release-note draft could drop required v1.0 caveats such as MPICH MPI+OpenMP being caveated, NVHPC being unvalidated, benchmark rows not being release claims, or source-only artifact policy, and this test would still pass as long as links remain valid. Concrete test to add: read docs/release-notes-v1.0.0.md and require the release-checklist guardrails from docs/release.md to appear in the draft: supported workflow names, SameMajorVersion, source-only/no-binary artifact language, MPICH hybrid caveat, package-manager/non-goal caveat, NVHPC unvalidated caveat, and benchmark no-threshold/no-trend-claim language. This would catch release-note drift that preserves valid links but widens the release claim.

2. test gap — docs/release-validation-v1.0.0.md records machine-checkable release closeout facts, but the contract test does not validate them against source files. For example, the validation record says CMakeLists.txt declares project(fTimer VERSION 1.0.0) and uses SameMajorVersion, and it lists required CI proof, but the test does not compare those claims to CMakeLists.txt or .github/workflows/ci.yml. Concrete test to add: parse or string-check docs/release-validation-v1.0.0.md against CMakeLists.txt for the project version and FTIMER_PACKAGE_VERSION_COMPATIBILITY, and require each listed CI job id that is expected to be a workflow job to exist in .github/workflows/ci.yml. This would catch stale validation records after a version, compatibility, or CI job rename.

Required Questions

1. Do the tests actually prove the behavior the PR claims to implement?
   Partially. They prove the new release docs exist and have valid local Markdown links. They do not prove the release-note and validation-record claims remain aligned with the release checklist, release evidence ledger, CMake version/compatibility settings, or CI workflow names.

2. Would these tests fail for the most likely incorrect implementations? Or could a broken implementation still pass?
   A broken docs implementation could still pass. The likely failure mode for release-prep docs is not a missing file; it is stale or over-broad prose. The current test would pass if the release notes removed key caveats or if the validation record’s CMake/CI facts became stale, provided links still resolve.

3. Are the important edge cases covered? What important cases are still untested?
   The important doc-link edge case is covered. The untested cases are semantic drift in the release-note claim boundary, stale artifact policy wording, stale benchmark claim wording, stale version/compatibility claims, and stale required CI proof.

4. Are the tests deterministic and appropriately isolated? Do they rely on timing noise, environment quirks, or shared mutable state?
   Yes. The CMake script checks are deterministic and isolated: they read repository files and do not depend on timing noise or external services. The issue is assertion depth, not flakiness.

5. What are the highest-value additional tests this PR or a follow-up should add?
   First, add release-note-specific assertions in tests/check_release_docs_contract.cmake for the required v1.0 claim boundaries and non-goals. Second, add validation-record assertions that compare the documented version and package compatibility against CMakeLists.txt. Third, add a check that required CI job names documented in docs/release-validation-v1.0.0.md remain present in .github/workflows/ci.yml, with any non-workflow status checks handled by an explicit allowlist.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: f52ee85a6248cf35e35675420af551ee4205eb77
Fallback wave: 1
Role: build-portability
Outcome: no-findings
Source: fresh-context subagent

Build / Portability Review

Findings

No actionable build, portability, configuration, or packaging findings.

Required Questions

1. Does this diff build correctly across the intended modes?
   Yes. The PR changes release documentation plus tests/check_release_docs_contract.cmake path coverage only; it does not alter source, CMake feature wiring, preprocessing, install rules, or exported targets. The new validation record names the expected serial, MPI, MPI+OpenMP, OpenMP, smoke, behavioral, benchmark, and installed-consumer proof paths, and the added docs are included in the release docs contract path/link validation.

2. Does this diff introduce compiler- or toolchain-specific assumptions?
   No actionable issue found. The new validation record includes Homebrew/Darwin paths and versions, but presents them as local evidence and explicitly records unavailable local toolchains (flang-19, MPICH, Spack/EasyBuild, NVHPC) rather than baking those paths into build instructions or package configuration.

3. Are CMake options, preprocessing, and dependencies wired correctly and consistently?
   Yes for this diff. No CMake option, compile definition, dependency export, or preprocessor guard is changed. Existing package wiring still exports MPI/OpenMP dependencies through fTimerConfig.cmake.in, and the PR only adds the two new release files to required_paths in tests/check_release_docs_contract.cmake.

4. Could this diff work on the author’s machine but fail in another reasonable environment? Why?
   I do not see an actionable environment-specific failure introduced by the diff. The only machine-specific values are documented as local validation provenance, not commands users or CI must reproduce. The release notes and validation record keep unsupported combinations caveated: MPICH MPI+OpenMP is not claimed as permanent PR CI coverage, package-manager execution is not claimed, and NVHPC remains unvalidated.

5. Does the installed/exported package remain usable by downstream consumers?
   Yes. The PR does not modify install/export code, installed module layout, package config generation, or installed-consumer tests. The new release notes correctly preserve the downstream boundary that Fortran .mod artifacts are compiler, wrapper, runtime, and feature-mode specific, and they align with the documented SameMajorVersion package-version contract.

[jaharris87]

@codex review as a completion-audit reviewer; determine what this PR demonstrably completes, what remains partial or overstated, what evidence is still missing, and what can safely be deferred; classify findings as completion gap, overstated claim, validation gap, safe deferral, or blocking gap; begin with "## Completion Audit Review".

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: f52ee85a6248cf35e35675420af551ee4205eb77
Fallback wave: 1
Role: completion-audit
Outcome: findings
Source: fresh-context subagent

Completion Audit Review

Verdict: partially complete. The release-closeout docs themselves look complete and honest, but #354 cannot be called fully complete at head f52ee85a6248cf35e35675420af551ee4205eb77 until the required CI/review coverage gates are green.

Findings:

1. [blocking gap] Required CI/review proof is not complete on the reviewed head. docs/release-validation-v1.0.0.md:82 requires the listed CI proof to be green before the release-prep PR is merge-ready, and docs/release-notes-v1.0.0.md:134 requires CI plus Codex Review Routing and Triggers and Codex Review Coverage before tagging. At review time, gh pr checks 358 --repo jaharris87/fTimer showed coverage failing, with build-mpi-mpich, build-mpi-openmp, build-mpi-openmp-bench, and route-and-trigger still pending. This is not a docs-content defect because the PR and validation record correctly state the gate, but it remains a blocker for closing Feature: prepare v1.0 release notes, validation record, and artifact closeout #354 as done.

Required questions:

1. What is demonstrably complete after this diff? The PR adds a v1.0.0 release-notes draft covering the supported workflows, public surface, CSV/package/artifact policy, migration notes, known limitations, validation expectations, benchmark evidence handling, and release-readiness links (docs/release-notes-v1.0.0.md:13, docs/release-notes-v1.0.0.md:53, docs/release-notes-v1.0.0.md:75, docs/release-notes-v1.0.0.md:107, docs/release-notes-v1.0.0.md:139). It adds a validation/artifact record with exact local commands, toolchains, skips, artifact closeout, benchmark closeout, and post-release triage expectations (docs/release-validation-v1.0.0.md:23, docs/release-validation-v1.0.0.md:43, docs/release-validation-v1.0.0.md:65, docs/release-validation-v1.0.0.md:106, docs/release-validation-v1.0.0.md:119, docs/release-validation-v1.0.0.md:128). docs/release.md now points to both new records (docs/release.md:286), and tests/check_release_docs_contract.cmake includes both paths (tests/check_release_docs_contract.cmake:17). The local release-doc contract script passed in this review. The version/package claims are backed by current CMakeLists.txt state: VERSION 1.0.0, SameMajorVersion, and installed LICENSE plus docs/installed-api.md (CMakeLists.txt:3, CMakeLists.txt:195, CMakeLists.txt:336).

2. What is only partially complete or conditionally complete? Completion is conditional on required CI/review gates. The validation record also honestly documents conditional evidence: local MPI pFUnit CTest launcher did not complete, but direct generated pFUnit commands passed and corresponding CI remains required (docs/release-validation-v1.0.0.md:53); unavailable flang-19, local MPICH, Spack/EasyBuild, and NVHPC runs are explicitly recorded as skips or non-claims (docs/release-validation-v1.0.0.md:67).

3. What is being claimed more strongly than the evidence supports? No actionable release-note or validation-record overstatement found. The docs preserve the MPICH MPI+OpenMP caveat, package-manager non-ownership, NVHPC non-claim, and no benchmark trend claim (docs/release-notes-v1.0.0.md:109, docs/release-notes-v1.0.0.md:113, docs/release-notes-v1.0.0.md:121, docs/release-notes-v1.0.0.md:141). The PR’s “Closes Feature: prepare v1.0 release notes, validation record, and artifact closeout #354” is acceptable only as a merge-time closure once the required gates are green.

4. What remains before this can honestly be called complete? Get every required CI/review gate green on the PR head, especially the currently failing/pending coverage/routing/build checks. After merge, tag/publish remains a maintainer-owned release step, not something this PR claims to have done.

5. What can safely be deferred, and what should block completion? Safe deferrals are clearly bounded: Strategic question: decide package-manager ownership after v1.0 #355 package-manager ownership, Explore opt-in fixed-team OpenMP worker timing mode #294 broader OpenMP ergonomics, Track Ubuntu 24.04 MPICH pFUnit re-enable path #259 Ubuntu 24.04 MPICH runner migration, and Investigate NVHPC nvfortran serial smoke validation #256 NVHPC validation (docs/release-validation-v1.0.0.md:15; docs/release-notes-v1.0.0.md:113). The blocker is the required CI/review proof not yet green. No further docs-content blocker found.

[chatgpt-codex-connector]

Codex review is not enabled for this repo. Please contact the admins of this repo to enable Codex.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: 792b0ced77105b58a9ee8cc09417057ee30c0ce3
Fallback wave: 2
Role: software
Outcome: no-findings
Source: fresh-context subagent

Software Review

Findings

No actionable software-correctness findings.

Required Questions

1. Does this diff change public behavior?
   No runtime, API, CLI, default-value, or file-format behavior changes. The diff adds release-facing documentation and strengthens tests/check_release_docs_contract.cmake.

2. Are docs, CLI help, and tests updated together with the behavior change?
   Yes for the scope of this PR. docs/release.md links the new v1.0.0 release notes and validation record, and tests/check_release_docs_contract.cmake now validates their presence, important release terms, the CMakeLists.txt version/package-compatibility claims, and listed CI job names. CLI help is not applicable.

3. Are new defaults safe?
   Not applicable. No defaults are changed.

4. Is any behavior silently lossy or imputed?
   No actionable issue found. The release notes explicitly avoid benchmark trend claims, binary/package-manager claims, and overclaiming MPICH MPI+OpenMP or NVHPC validation. The validation record documents local skips and the MPI CTest launcher caveat rather than hiding them behind a fallback.

5. Is there an end-to-end test path for the new feature?
   Yes for the new release-doc contract coverage. The CMake validator checks the new files as part of the release docs contract, including link existence, required release-boundary terms, version/package compatibility text, and CI job-name consistency with .github/workflows/ci.yml. I also ran cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake at head 792b0ced77105b58a9ee8cc09417057ee30c0ce3, and it passed.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: 792b0ced77105b58a9ee8cc09417057ee30c0ce3
Fallback wave: 2
Role: docs-contract
Outcome: no-findings
Source: fresh-context subagent

Docs / Contract Review

Actionable findings: None.

Required questions:

1. What does main guarantee after this diff? No runtime behavior changes are introduced. The diff adds v1.0.0 release-note and validation records, links them from docs/release.md, and extends the release docs contract check. The stated guarantees are clear and match the existing claim ledger: supported serial, pure-MPI, OpenMP compatibility, ftimer_openmp_t, strict/sparse hybrid, CSV, source-only artifact, package compatibility, and caveat boundaries are consistent across docs/release-notes-v1.0.0.md, docs/release-validation-v1.0.0.md, docs/release.md, and docs/release-evidence.md.

2. Do any docs describe deferred or future behavior as if it already exists? No. Deferred/non-goal areas remain caveated: MPICH MPI+OpenMP is local-evidence-backed rather than permanent PR CI, package-manager availability remains issue Strategic question: decide package-manager ownership after v1.0 #355, fixed-team/no-explicit-region OpenMP ergonomics remain issue Explore opt-in fixed-team OpenMP worker timing mode #294, Ubuntu 24.04 MPICH pFUnit migration remains issue Track Ubuntu 24.04 MPICH pFUnit re-enable path #259, NVHPC remains issue Investigate NVHPC nvfortran serial smoke validation #256, and benchmark trend claims require CSV plus sidecar evidence.

3. Are README, CLAUDE.md, maintainer docs, examples, and TODO.md mutually consistent after this change? Yes for the files present. README/CLAUDE/AGENTS/release/maintainer wording all keep the same OpenMP, MPI+OpenMP, package-manager, package-compatibility, benchmark, and artifact boundaries. The named examples exist and align with the claimed API families. There is no TODO.md in this checkout, so there is no TODO document to reconcile.

4. Are current-state behavior and target design clearly separated? Yes. The new release note explicitly says it is a draft and does not tag, publish, or add assets; the validation record likewise says it does not tag or publish the release. Future/deferred items are kept in “Known Limitations And Deferred Work” and are tied to issue numbers rather than presented as implemented support.

5. Would a new contributor or coding agent be likely to misunderstand what is implemented today? If so, where? I did not find an actionable misunderstanding risk. The release-note draft points readers to docs/release-evidence.md for claim boundaries and docs/release.md for execution policy, while the validation record separates passed local checks, unavailable local validation, and required CI proof.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: 792b0ced77105b58a9ee8cc09417057ee30c0ce3
Fallback wave: 2
Role: build-portability
Outcome: no-findings
Source: fresh-context subagent

Build / Portability Review

Reviewed PR #358 at head 792b0ced77105b58a9ee8cc09417057ee30c0ce3, covering the changed release docs and tests/check_release_docs_contract.cmake. I also sanity-checked the changed CMake script directly with cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake, which passed.

Required questions:

1. Does this diff build correctly across the intended modes?
   Yes for the scope of this diff. It does not change Fortran sources, CMake target wiring, feature options, MPI/OpenMP preprocessing, or install rules. The new contract-test checks are CMake-script-only and passed locally; the release-validation doc also keeps serial, MPI, OpenMP, MPI+OpenMP, smoke, pFUnit, installed-consumer, and benchmark proof separated by mode.

2. Does this diff introduce compiler- or toolchain-specific assumptions?
   No actionable issue found. The local Homebrew/Darwin paths and tool versions are recorded as validation provenance, not baked into build logic or downstream package instructions. The release notes continue to caveat compiler-, wrapper-, runtime-, and feature-mode-specific .mod artifacts.

3. Are CMake options, preprocessing, and dependencies wired correctly and consistently?
   Yes. The diff adds release-document contract assertions and required-path checks only. The assertions align with existing project(fTimer VERSION 1.0.0), FTIMER_PACKAGE_VERSION_COMPATIBILITY SameMajorVersion, existing CI job keys, and the installed-package documentation contract.

4. Could this diff work on the author’s machine but fail in another reasonable environment? Why?
   No actionable portability risk found. The changed test uses standard CMake script operations and repository-relative paths through REPO_ROOT. The docs explicitly distinguish local validation from required CI proof, including unavailable local MPICH, flang-19, Spack/EasyBuild, and NVHPC validation.

5. Does the installed/exported package remain usable by downstream consumers?
   Yes. The diff does not alter exported targets, installed module handling, package config/version generation, install destinations, or downstream consumer fixtures. The new release notes and validation record reinforce the existing same-major package-version rule and the feature-mode/compiler-specific installed-module boundary.

Actionable findings: none.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: 792b0ced77105b58a9ee8cc09417057ee30c0ce3
Fallback wave: 2
Role: test-quality
Outcome: findings
Source: fresh-context subagent

Test Quality Review

Findings

1. test gap — tests/check_release_docs_contract.cmake:1141-1155

The release-notes compatibility check is too weak for the version/package caveat it is meant to protect. It requires only `SameMajorVersion` and the substring compiler module, so docs/release-notes-v1.0.0.md could drop the actual user-facing semantics at lines 55-61: same-major requests at or older than the installed version, rejection of future-major and newer same-major requests, and .mod non-portability across compiler/wrapper/runtime/feature modes. The broader docs checks cover README, installed-api, and release-evidence, but the release note itself is the artifact this PR is adding.

Concrete test to add: require the release-notes text to contain terms equivalent to older than the installed package version, rejects future-major requests, rejects same-major requests newer than the installed package, compiler-, wrapper-, runtime-, and feature-mode-specific, and A serial install is not promised to satisfy an MPI, OpenMP, MPI+OpenMP, or different-compiler downstream build.

2. test gap — tests/check_release_docs_contract.cmake:1230-1251

The CI synchronization check is still one-way and partly hard-coded. It verifies that a fixed list in the test appears in docs/release-validation-v1.0.0.md and that those fixed CI job IDs exist in .github/workflows/ci.yml, but it does not parse the actual Required CI Proof list at docs/release-validation-v1.0.0.md:87-104. A stale extra bullet in the release record, an omitted newly added CI job, or renamed Codex workflow names in .github/workflows/codex-review.yml:1 / .github/workflows/codex-review-coverage.yml:1 could still pass.

Concrete test to add: extract the backticked bullets from the Required CI Proof section, compare CI job bullets bidirectionally against top-level job IDs parsed from .github/workflows/ci.yml, and verify the two Codex status bullets against the name: fields of the Codex review workflows.

Required Questions

1. Do the tests actually prove the behavior the PR claims to implement? Partly. The new checks meaningfully protect release-note existence, many caveats, project(fTimer VERSION 1.0.0), SameMajorVersion, and listed ci.yml job IDs. They do not fully prove release-note package compatibility wording or exact CI/status-check synchronization.

2. Would these tests fail for the most likely incorrect implementations? They would fail for many simple omissions, such as removing the MPICH caveat, benchmark-provenance caveat, or a listed CI job from ci.yml. They would not fail if the release notes kept only token package-compatibility words, or if the validation record accumulated stale extra CI/status names.

3. Are the important edge cases covered? Release-note caveats around MPICH, package-manager scope, NVHPC, and benchmark claims are mostly covered. Missing edge cases are exact release-note version/package semantics and bidirectional synchronization of the Required CI Proof list.

4. Are the tests deterministic and appropriately isolated? Yes. This is deterministic file-content validation with no timing, network, or mutable runtime dependency. I did not run the tests because this was a read-only inspection request.

5. What are the highest-value additional tests this PR or a follow-up should add? Add the two concrete contract checks above: stronger release-note package-compatibility needles, and an extracted/bidirectional Required CI Proof synchronization check including Codex workflow name: validation.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: 792b0ced77105b58a9ee8cc09417057ee30c0ce3
Fallback wave: 2
Role: completion-audit
Outcome: external-gates-pending
Source: fresh-context subagent

Completion Audit Review

Verdict: partially complete. The release-closeout documentation itself appears complete for #354, and I found no docs-content completion findings. The remaining incompleteness is external: the PR head still needs CI/review gates to finish and turn green before the issue can honestly be closed.

1. What is demonstrably complete after this diff?

The PR adds the v1.0.0 release-notes draft and validation/artifact record, links them from the release checklist, and adds contract-test coverage for the new closeout terms. The notes cover the required supported workflows in docs/release-notes-v1.0.0.md:13 through docs/release-notes-v1.0.0.md:22, public/API/CSV/package boundaries in docs/release-notes-v1.0.0.md:53 through docs/release-notes-v1.0.0.md:69, source-only artifact policy in docs/release-notes-v1.0.0.md:75 through docs/release-notes-v1.0.0.md:92, migration guidance in docs/release-notes-v1.0.0.md:94 through docs/release-notes-v1.0.0.md:105, known limitations/deferred work in docs/release-notes-v1.0.0.md:107 through docs/release-notes-v1.0.0.md:125, validation-gate wording in docs/release-notes-v1.0.0.md:127 through docs/release-notes-v1.0.0.md:137, and benchmark evidence handling in docs/release-notes-v1.0.0.md:139 through docs/release-notes-v1.0.0.md:145.

The validation record captures local toolchain details and exact commands/statuses in docs/release-validation-v1.0.0.md:23 through docs/release-validation-v1.0.0.md:63, unavailable local toolchains/skips in docs/release-validation-v1.0.0.md:65 through docs/release-validation-v1.0.0.md:80, required CI/review proof in docs/release-validation-v1.0.0.md:82 through docs/release-validation-v1.0.0.md:104, artifact closeout in docs/release-validation-v1.0.0.md:106 through docs/release-validation-v1.0.0.md:117, benchmark closeout in docs/release-validation-v1.0.0.md:119 through docs/release-validation-v1.0.0.md:126, and post-release triage expectations in docs/release-validation-v1.0.0.md:128 through docs/release-validation-v1.0.0.md:134.

The version/package criteria are backed by project(fTimer VERSION 1.0.0) in CMakeLists.txt:3 through CMakeLists.txt:5 and FTIMER_PACKAGE_VERSION_COMPATIBILITY SameMajorVersion in CMakeLists.txt:195. Installed docs include LICENSE and docs/installed-api.md via CMakeLists.txt:336 through CMakeLists.txt:340, with installed-artifact checks in tests/installed-consumer-contract/installed-artifacts.cmake:49 through tests/installed-consumer-contract/installed-artifacts.cmake:75.

2. What is only partially complete or conditionally complete?

Validation is conditionally complete. The docs correctly say the PR is not merge-ready until required CI and review checks are green (docs/release-validation-v1.0.0.md:82 through docs/release-validation-v1.0.0.md:104). Current gh pr checks for head 792b0ced77105b58a9ee8cc09417057ee30c0ce3 shows coverage failing and many CI jobs still pending, while some jobs such as build-contract-regressions, build-serial, benchmark smoke jobs, and lint have passed. This is a gate/evidence state, not a docs-content defect.

3. What is being claimed more strongly than the evidence supports?

I did not find an overstated docs claim. The release notes avoid benchmark trend claims (docs/release-notes-v1.0.0.md:141 through docs/release-notes-v1.0.0.md:145), keep MPICH MPI+OpenMP caveated (docs/release-notes-v1.0.0.md:109 through docs/release-notes-v1.0.0.md:112), identify package-manager work as post-v1.0/readiness-only (docs/release-notes-v1.0.0.md:113 through docs/release-notes-v1.0.0.md:116), and keep NVHPC unclaimed (docs/release-notes-v1.0.0.md:121 through docs/release-notes-v1.0.0.md:122).

4. What remains before this can honestly be called complete?

Validation gap, external gate only: all required CI jobs and review gates listed in docs/release-validation-v1.0.0.md:87 through docs/release-validation-v1.0.0.md:104 need to complete successfully on the PR head. In particular, the current coverage failure must be resolved or rerun to green, and the pending CI jobs must finish green. I did not identify a release-docs content change needed before completion.

5. What can safely be deferred, and what should block completion?

Safe deferrals are already named and bounded: package-manager ownership #355, fixed-team/no-explicit-region OpenMP ergonomics #294, Ubuntu 24.04 MPICH pFUnit runner migration #259, NVHPC #256, and non-goals such as binary packages, FPM, profiler backends, hardware counters, traces, dashboards, accelerator synchronization, and automatic MPI barriers are all kept outside the v1.0 claim in docs/release-notes-v1.0.0.md:107 through docs/release-notes-v1.0.0.md:125 and match the release ledger in docs/release-evidence.md:49 through docs/release-evidence.md:58.

Blocking completion: the external CI/review gates only. No actionable completion/evidence gaps were found in the release-note draft, validation record, artifact policy, benchmark handling, or post-release triage wording.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: a479211f665a89810a0bfb15feea382299a60084
Fallback wave: 3
Role: test-quality
Outcome: no-findings
Source: fresh-context subagent

Test Quality Review

No actionable findings.

Prior findings are satisfied on HEAD a479211f665a. The expanded contract test now checks stronger v1 package-compatibility release-note needles, including SameMajorVersion, older-than-installed requests, future-major rejection, newer same-major rejection, and feature/compiler artifact caveats in tests/check_release_docs_contract.cmake. It also checks the real CMake version and compatibility settings at lines 1189 and 1195.

The Required CI Proof synchronization is now meaningfully bidirectional: it extracts CI job ids from .github/workflows/ci.yml, extracts Required CI Proof bullets from docs/release-validation-v1.0.0.md, reads Codex workflow name: fields, requires every CI job/status to be listed, and rejects unknown proof entries in tests/check_release_docs_contract.cmake. The validation record lists the current CI jobs and Codex statuses in docs/release-validation-v1.0.0.md.

Required questions:

1. Do the tests actually prove the behavior the PR claims to implement?
   Yes for the release-docs contract scope. They prove the new v1 release notes keep the expected support/artifact/package-compatibility claims, and that Required CI Proof stays synchronized with current ci.yml job ids plus the two PR-facing Codex review workflow names.

2. Would these tests fail for the most likely incorrect implementations?
   Yes. Missing a CI job from Required CI Proof, adding a stale/unknown proof bullet, renaming a Codex review workflow without updating the validation record, dropping SameMajorVersion, or weakening the release-note package-compatibility language should fail. A misleading document could still pass if it preserves all required phrases while contradicting them elsewhere, but that is a normal limitation of phrase-based docs contract tests and not a blocker for this PR.

3. Are the important edge cases covered?
   Covered: missing release files, missing required release-note/package/artifact terms, CMake version/compatibility drift, CI job omissions, extra Required CI Proof entries, and Codex workflow display-name drift. Not fully covered: semantic contradictions elsewhere in prose, future YAML job-id forms outside the current simple top-level job pattern, and whether the recorded local validation commands truly ran. Those are reasonable human-review boundaries.

4. Are the tests deterministic and appropriately isolated?
   Yes. The contract test reads repository files only and does not depend on timing, network, external toolchains, or shared mutable state.

5. What are the highest-value additional tests this PR or a follow-up should add?
   Non-blocking follow-up only: if this parser grows, factor the CI-proof extraction into small CMake functions with fixture-style negative cases for missing, extra, and renamed entries. If more required non-CI workflows become branch-protection checks, extend the status-check allowlist rather than relying on ad hoc prose review.

Local read-only verification run:

• git diff --check main...HEAD passed.
• cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake passed.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: a479211f665a89810a0bfb15feea382299a60084
Fallback wave: 3
Role: software
Outcome: no-findings
Source: fresh-context subagent

Software Review

No actionable findings.

I confirmed the local checkout is on codex/354-v1-release-closeout at a479211f665a89810a0bfb15feea382299a60084. I reviewed the PR diff only: docs/release-notes-v1.0.0.md, docs/release-validation-v1.0.0.md, docs/release.md, and tests/check_release_docs_contract.cmake.

Required questions:

1. Does this diff change public behavior? No runtime/API behavior change. It adds release documentation and strengthens a release-doc contract test.
2. Are docs, CLI help, and tests updated together with the behavior change? Applicable docs and the contract test are updated. No CLI/help/runtime behavior is changed.
3. Are new defaults safe? No new defaults are introduced.
4. Is any behavior silently lossy or imputed? I did not find silent lossy behavior in the changed contract logic or release docs. The docs explicitly call out unvalidated/skipped areas.
5. Is there an end-to-end test path for the new feature? Yes for this docs/records change: ftimer_release_docs_contract is extended to require the new files, release terms, version/compatibility claims, and CI proof entries. I also ran the script directly:
   cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake

Current-head blockers: none found.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: a479211f665a89810a0bfb15feea382299a60084
Fallback wave: 3
Role: docs-contract
Outcome: no-findings
Source: fresh-context subagent

Docs / Contract Review

No actionable findings.

Current head confirmed locally: a479211f665a89810a0bfb15feea382299a60084 on codex/354-v1-release-closeout.

I also ran the changed contract script locally:

cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake

It passed with no output.

Required questions:

1. What does main guarantee after this diff?
   It guarantees a v1.0.0 release-prep documentation set: draft release notes, validation/artifact record, release checklist routing, and a contract check tying the release wording to current evidence, CI job names, package compatibility, artifact policy, and known caveats. That is stated clearly.

2. Do any docs describe deferred or future behavior as if it already exists?
   I did not find that. Package-manager support, NVHPC validation, fixed-team/no-explicit-region OpenMP ergonomics, permanent MPICH hybrid CI, profiler integrations, hardware counters, traces, FPM, and binary packages are all kept as deferred, caveated, or non-goal items.

3. Are README, CLAUDE.md, maintainer docs, examples, and TODO.md mutually consistent after this change?
   README, CLAUDE.md/AGENTS.md, release/maintainer-facing docs, and examples are consistent with the new release notes. I found no TODO.md in this checkout, so that part is not applicable.

4. Are current-state behavior and target design clearly separated?
   Yes. Current supported behavior is described as serial, pure MPI, OpenMP compatibility, explicit ftimer_openmp_t, and strict/sparse hybrid surfaces. Future/deferred work is explicitly separated in docs/release-notes-v1.0.0.md, docs/release-validation-v1.0.0.md, and docs/release-evidence.md.

5. Would a new contributor or coding agent be likely to misunderstand what is implemented today?
   I do not think so from this diff. The added release notes and validation record repeatedly point back to the evidence ledger and avoid turning readiness notes or local-only caveats into broader support claims.

Current-head blockers: none.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: a479211f665a89810a0bfb15feea382299a60084
Fallback wave: 3
Role: build-portability
Outcome: no-findings
Source: fresh-context subagent

Build / Portability Review

No actionable findings.

Current head confirmed locally: a479211f665a89810a0bfb15feea382299a60084 on codex/354-v1-release-closeout.

Current-head blockers: none found.

Required questions:

1. Does this diff build correctly across intended modes?
   The diff is docs plus the release-docs CMake contract check. I ran cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake and git diff --check fd5912405e2589aef825125b54e196344d231a52...HEAD; both passed. I did not rerun full serial/MPI/OpenMP builds because this was a final read-only refresh and the changed executable surface is the CMake script.

2. Does this diff introduce compiler- or toolchain-specific assumptions?
   No new source compiler assumptions found. The new release validation record explicitly labels Homebrew/Darwin toolchain paths as local evidence and keeps unavailable MPICH, flang-19, Spack/EasyBuild, and NVHPC validation caveated rather than promoted to portable support.

3. Are CMake options, preprocessing, and dependencies wired correctly and consistently?
   Yes for this diff. The added contract checks are CMake-script-only, compatible with the repository’s cmake_minimum_required(VERSION 3.16) style, and they validate the current project(fTimer VERSION 1.0.0), FTIMER_PACKAGE_VERSION_COMPATIBILITY SameMajorVersion, CI job list, and Codex review workflow names against current files.

4. Could this diff work on the author’s machine but fail in another reasonable environment? Why?
   I did not find a current blocker. The release-validation prose records local machine-specific paths, but as evidence rather than commands downstream users are expected to run. The contract test itself avoids shell-specific behavior and ran through cmake -P.

5. Does the installed/exported package remain usable by downstream consumers?
   Yes. The diff does not change install/export logic. The new docs preserve the existing caveat that installed Fortran .mod artifacts are compiler, wrapper, runtime, and feature-mode specific, and the contract check verifies the v1 SameMajorVersion package compatibility wording against the current CMake configuration.

[jaharris87]

Manual fallback review record

Reviewed PR head SHA: a479211f665a89810a0bfb15feea382299a60084
Fallback wave: 3
Role: completion-audit
Outcome: no-findings
Source: fresh-context subagent

Completion Audit Review

Verdict: complete for issue #354, with no current-head blockers found. The only remaining blockers are external gates: PR-head CI and Codex review coverage must be green before merge/tagging.

Actionable findings: None.

Required questions:

1. Demonstrably complete: The PR adds a v1.0.0 release-note draft, validation/artifact record, release checklist links, and contract coverage. It documents source-only artifacts, license/source archive policy, benchmark evidence handling, post-release triage, required CI, and deferred issues. See docs/release-notes-v1.0.0.md:75, docs/release-validation-v1.0.0.md:82, and docs/release.md:286.

2. Partially or conditionally complete: Tag creation, GitHub release publication, and PR-head CI/review proof are intentionally not complete in this branch. The docs state this explicitly at docs/release-notes-v1.0.0.md:3 and docs/release-validation-v1.0.0.md:3.

3. Overstated claims: I did not find overclaiming in scope. MPICH hybrid, package-manager support, NVHPC, benchmark trends, and binary artifacts are all caveated or deferred.

4. Remaining before honest completion: External green gates only: all listed CI jobs and Codex Review Routing and Triggers / Codex Review Coverage per docs/release-validation-v1.0.0.md:84.

5. Safe deferrals vs blockers: Strategic question: decide package-manager ownership after v1.0 #355, Explore opt-in fixed-team OpenMP worker timing mode #294, Track Ubuntu 24.04 MPICH pFUnit re-enable path #259, and Investigate NVHPC nvfortran serial smoke validation #256 are safely deferred/non-blocking as documented. The merge/tag blockers are CI/review gates, not current-head content gaps.

Local refresh notes: confirmed branch codex/354-v1-release-closeout at a479211f665a89810a0bfb15feea382299a60084, clean worktree, cmake -DREPO_ROOT=/Users/hrh/.codex/worktrees/dec9/fTimer -P tests/check_release_docs_contract.cmake passed, and git diff --check main...HEAD passed.

[jaharris87]

Codex review coverage: software covered for a479211 via manual fallback.

[jaharris87]

Codex review coverage: docs-contract covered for a479211 via manual fallback.

[jaharris87]

Codex review coverage: test-quality covered for a479211 via manual fallback.

[jaharris87]

Codex review coverage: build-portability covered for a479211 via manual fallback.

[jaharris87]

Codex review coverage: completion-audit covered for a479211 via manual fallback.

[jaharris87]

Manual fallback findings disposition

Reviewed current head: a479211f665a89810a0bfb15feea382299a60084

• Wave 1 test-quality findings were addressed in 792b0ced77105b58a9ee8cc09417057ee30c0ce3 by adding semantic v1 release-note, validation-record, CMake version/package-compatibility, and CI proof checks to tests/check_release_docs_contract.cmake.
• Wave 2 test-quality findings were addressed in a479211f665a89810a0bfb15feea382299a60084 by strengthening release-note package-compatibility needles and making Required CI Proof synchronization bidirectional against .github/workflows/ci.yml plus Codex workflow name: fields.
• Wave 3 fresh-context reviewers reported no current-head blockers for active roles: software, docs-contract, test-quality, and completion-audit. build-portability was also reviewed cleanly on the current head, then its label was removed because Codex Review Coverage reported it as stale for the final diff router state.
• Focused local checks after the final fix: cmake -E chdir build-smoke ctest --output-on-failure -R '^ftimer_release_docs_contract$' and git diff --check both passed.

No unresolved review threads remain.