Skip to content

Reproducibility and Update Rules

Source precedence

Authority depends on claim type:

  1. Shared research pages establish OWNER INTENT and APPROVED DECISION status. Edit Scope and Decisions directly to change decisions; edit other pages for reasoning, methods, interpretation, and questions.
  2. Executable source establishes current application behaviour. Persisted immutable Project records establish what was executed.
  3. Deterministic simulation-evidence.json is the machine authority for simulation counts, execution metadata, field values, hotspots, particle-page statistics, and RSE distributions. Current Project Evidence is the sole documentation-level summary of volatile Project evidence and relevant application mismatches.
  4. Original supplied papers establish only their own methods, systems, and findings.

Documentation is input for intent, not independent scientific confirmation. There is one shared documentation set. Do not introduce a human/AI split, decision JSON register, application Decisions UI, or mandatory separate approval workflow.

When an immutable record and current implementation differ, the record governs the historical execution and source governs current capability. Neither establishes scientific validity or owner approval.

Evidence labels

  • OWNER INTENT: owner direction; not completed evidence.
  • APPROVED DECISION: explicitly recorded owner choice; approval does not prove execution or correctness.
  • PROPOSED METHOD: procedure awaiting approval or execution.
  • VERIFIED EVIDENCE: traceable implementation, record, numerical, verification, or scientific evidence within its stated boundary.
  • PRELIMINARY EVIDENCE: limited observation not yet sufficient for the intended conclusion.
  • EXTERNAL LITERATURE: evidence limited to the cited source and page.
  • UNRESOLVED: no approved answer; no value or threshold may be invented.
  • SUPERSEDED CONTEXT: older context displaced by an explicit newer documented decision. Do not use this merely because a record changed or a newer run exists.
  • IMPLEMENTATION-DOC MISMATCH: current contradiction between implementation or records and documentation, reported with both authorities.

Required status separation

Report separately:

  1. record preparation and integrity;
  2. process status and return code;
  3. transport completion, diagnostics, and library or model selection;
  4. statistical uncertainty and descriptive coverage;
  5. numerical convergence and repeated-run agreement;
  6. implementation and numerical verification;
  7. physical validation against measurements;
  8. owner-approved scientific acceptance;
  9. Assessment and Dataset inclusion; and
  10. surrogate final-test and independent-verification status.

No later status follows from an earlier one. Descriptive RSE threshold counts are observations, not approved D7 criteria.

Update process

  1. Inventory persisted Paper 1 records before consulting summaries.
  2. Preserve immutable Paper 1 Cases, Attempts, Results, failures, interruptions, exclusions, and inconclusive outcomes. Disposable application-verification records belong in the separate verification Project.
  3. Read every existing shared research page completely before updating. Preserve direct edits, requirements, explicit decisions, procedures, questions, and reasoning. A proposal, question, successful run, or code path cannot approve science.
  4. Regenerate simulation-evidence.json after record changes and use it exclusively for counts, histories, controls, timestamps, return codes, PHITS versions, field values, hotspots, particle statistics, and RSE distributions. Update Current Project Evidence through the existing reviewed documentation workflow; do not copy its volatile claims into other research pages.
  5. Inspect referenced immutable inputs and raw PHITS diagnostics only for contextual geometry, libraries, warnings, commands, and artifact roles. Bind every interpretation to its exact Case, Attempt, and Result.
  6. Compare every newer Case with its source Design and historical Cases. Never transfer a Result to changed geometry, material, source, library, or tally definition.
  7. Verify literature claims against original PDF pages and cite [Author year, p. N] or [Author year, pp. N-M].
  8. Preserve explicit owner decisions. Report ambiguities when chronology and context do not resolve conflicts.
  9. Approve criteria before use. A retrospective threshold needs an explicit amendment and cannot silently admit an older Result.
  10. Publish a Dataset only through a qualifying Study Assessment with whole-configuration grouping.
  11. Finalize the Model before final-test access and retain final-test and independent Prediction Verification records.

Mismatch handling

  • Use SUPERSEDED CONTEXT only when an explicit newer documented decision displaces older context. Use IMPLEMENTATION-DOC MISMATCH for a present contradiction.
  • Correct stale descriptions against executable code while retaining intended science and recording remaining implementation gaps.
  • Keep the Project-data reset distinct from the earlier rejected-D3 cleanup; the current reset state is maintained only in Current Project Evidence.
  • Do not carry rejected or provisional 0.8 mm, 1.2 mm, plate, FWHM, quadrature, or field values into D3/D5 candidate selection.
  • Treat the former preliminary D4 Design as historical documentation, not current authoring state or evidence.
  • Create a new Design under the current approved D3/D5 procedure rather than reconstructing deleted Design state from prose.
  • Keep the approved D6 strategy in Research Scope and Decisions; maintain current comparator-evidence availability in Current Project Evidence.
  • Report implementation capability separately from unresolved D7-D11 choices.
  • Application defaults do not constitute scientific approval. Maintain the current Study-criteria mismatch only in Current Project Evidence.
  • Treat prior generated dates, review counts, interpretations, and recommendations as provenance unless supported by a stronger approved input.

Failed, interrupted, inconclusive, high-uncertainty, fallback-physics, amended, and superseded Paper 1 research records remain traceable. They cannot be upgraded through renaming, omission, or association with a newer Design.

Current deterministic boundary

The current deterministic inventory, its provenance boundary, and strictly qualified conclusions are maintained only in Current Project Evidence.

Edit, update, and publish

Edit the shared Markdown pages directly, then run:

./tools/publish_knowledge_base.sh

The script extracts deterministic simulation evidence, updates the existing shared pages against approved local sources, rebuilds C4, validates the site, and deploys it. It retains a pre-update copy under tmp/knowledge-base-*/before; direct edits and assets must be carried forward. If documentation changes during generation, replacement must stop for reconciliation.

To publish already edited pages without AI regeneration:

./tools/publish_knowledge_base.sh --publish-only

The public site is read-only with respect to these Markdown sources. Review every resulting diff for scientific meaning, preserved reasoning, citation validity, working relative navigation, missing detail, and unreported mismatches.