# Quizzman Paper Standard — ISO Profile (QPS-ISO)

- **Standard Identifier:** QPS-ISO
- **Edition:** 1.0
- **Release Date:** 2026-10-01
- **Status:** Normative Standard (Quizzman Internal)
- **Publisher:** Quizzman Research & Engineering Architecture Board
- **Canonical Repository:** `https://github.com/quizzman/qm-paper`
- **Publishing Portal:** `https://paper.quizzman.com`

---

## Important Notice and Disclaimer

> **QPS-ISO is an internal scholarly and technical publishing profile developed by Quizzman. It adopts selected structural and bibliographic principles from relevant ISO standards. Conformance with QPS-ISO does not imply certification or endorsement by ISO.**

This specification defines the editorial, architectural, mathematical, and programmatic standards for research papers, formal algorithm specifications, calendar models, and computational validation studies across the Quizzman knowledge ecosystem.

---

## 1 Scope

This document specifies the structural, bibliographic, metadata, and lifecycle requirements for academic papers and technical specifications published within the Quizzman ecosystem (`https://paper.quizzman.com`).

The objectives of QPS-ISO are:
1. To establish immutable, machine-readable specifications that serve as the **authoritative source of truth** for Quizzman algorithms, models, historical computations, and validation suites.
2. To guarantee full end-to-end traceability: from ancient or astronomical primary sources, through formal models and mathematical proofs, to software implementation and executable test vectors.
3. To enforce rigorous, reproducible validation and eliminate unsubstantiated promotional language from technical literature.
4. To provide a deterministic schema and automated Continuous Integration (CI) verification process for all published works.

---

## 2 Normative References

The following referenced standards provide the baseline principles adopted by QPS-ISO. Specific adaptations and profile deviations are detailed in their respective sections:

- **ISO 7144:1986** — *Documentation — Presentation of theses and similar documents* (structural layout and front matter organization).
- **ISO 214:1976** — *Documentation — Abstracts for publications and documentation* (abstract completeness and composition).
- **ISO 2145:1978** — *Documentation — Numbering of divisions and subdivisions in written documents* (hierarchical decimal numbering without terminal period).
- **ISO 690:2021** — *Information and documentation — Guidelines for bibliographic references and citations to information resources* (citation schema and reference structuring).
- **ISO 8601-1:2019** — *Date and time — Representations for information interchange* (all date/time stamps).
- **ISO 639-1 / ISO 639-2** — *Codes for the representation of names of languages*.
- **ISO 3166-1** — *Codes for the representation of names of countries and their subdivisions*.

---

## 3 Terms and Definitions

### 3.1 paper
Structured scholarly or technical document published with an immutable identifier, semantic version, machine-readable metadata, and complete bibliographic references.

### 3.2 canonical language
The designated primary language edition of a paper against which normative assertions, rules, and proofs are authoritatively evaluated.

### 3.3 normative content
Document content that specifies requirements, rules, algorithms, or definitions with which all conformant implementations SHALL comply.

### 3.4 informative content
Document content that provides context, rationale, historical background, non-binding examples, implementation commentary, or exploratory discussion.

### 3.5 test vector
A deterministic pair of specified input parameters and expected output values used to empirically verify the correctness of an algorithm or rule implementation.

### 3.6 reproducibility manifest
Machine-readable metadata block specifying the exact software versions, runtime environments, external ephemerides/datasets, and compiler targets required to replicate computational results.

---

## 4 Document Identification and Versioning

### 4.1 Paper Identifier (QP-ID)
Every document SHALL possess a globally unique, invariant identifier conforming to the following format:

```text
QP-{DOMAIN}-{NUMBER}
```

- `QP`: Prefix designating Quizzman Paper.
- `{DOMAIN}`: Uppercase alphanumeric domain code identifying the subject domain. Standard domains include:
  - `CAL`: Calendar systems, ephemerides, lunisolar synchronization.
  - `ASTRO`: Celestial mechanics, planetary positions, coordinate transformations.
  - `YINGQI`: Ying Qi and cyclical timing models.
  - `GANZHI`: Sexagenary cycle (Can Chi / Gan Zhi) rules and calculations.
  - `LIUYAO`: Hexagram combinatorics and mathematical transformations.
  - `SYS`: Distributed architecture, knowledge graph, and search engine infrastructure.
  - `BENCH`: Benchmark corpora and verification datasets.
- `{NUMBER}`: Zero-padded sequential decimal number with a minimum of three digits (e.g., `001`, `042`).

**Rule:** The Paper ID SHALL NOT change across revisions, minor updates, or major rewrites. A paper maintains its identity permanently.

### 4.2 Versioning Model
Every paper SHALL specify a semantic version conforming to SemVer 2.0.0 (`MAJOR.MINOR.PATCH`):

```text
QP-{DOMAIN}-{NUMBER}@{MAJOR}.{MINOR}.{PATCH}
```

- **PATCH (`x.y.Z`)**: Editorial adjustments, typographical corrections, citation link fixes, formatting improvements, or non-normative clarifying phrasing. Normative rules and algorithm outputs MUST NOT change.
- **MINOR (`x.Y.z`)**: Addition of supplementary test vectors, new illustrative examples, expanded informative discussions, or backward-compatible rule clarifications that do not invalidate prior conformant implementations.
- **MAJOR (`X.y.z`)**: Fundamental modifications to mathematical models, normative rules, algorithm equations, variable definitions, or breaking behavioral changes in the reference specification.

**Rule:** Published versions (`stable`, `deprecated`, `superseded`) are immutable in Git history. Authors SHALL NOT silently modify previously released papers without incrementing the version tag.

---

## 5 Document Lifecycle

Every paper SHALL declare its lifecycle status in `metadata.yaml` using one of the following eight enumerated values:

```mermaid
graph TD
    draft([draft]) --> review([review])
    review --> proposed([proposed])
    proposed --> stable([stable])
    draft --> experimental([experimental])
    stable --> deprecated([deprecated])
    stable --> superseded([superseded])
    stable --> retracted([retracted])
    deprecated --> superseded
```

1. **`draft`**: Work in progress. The structure, formulas, and normative statements are subject to arbitrary changes. Not eligible for production reliance.
2. **`review`**: Author-frozen draft submitted for formal peer review, mathematical audit, or historical source criticism.
3. **`proposed`**: Passed peer review; pending final sign-off or public comment period.
4. **`stable`**: Fully vetted and published. Normative rules serve as the authoritative **source of truth** for all Quizzman engineering libraries.
5. **`experimental`**: Fully articulated research paper documenting preliminary exploratory methodologies, heuristic approximations, or prototype models without normative stability guarantees.
6. **`deprecated`**: Still valid for legacy codebases, but scheduled for obsolescence. A warning note SHALL specify migration targets.
7. **`superseded`**: Replaced by a newer paper or major revision. The `superseded_by` metadata attribute SHALL reference the new Paper ID.
8. **`retracted`**: Severely flawed, factually erroneous, or historically invalid. Retracted papers remain archived for historical auditing, but their normative assertions SHALL NOT be relied upon under any circumstances.

---

## 6 Document Taxonomy

QPS-ISO classifies all publications into eight distinct types:

| Type | Purpose | Validation Requirements | Source & Citation Requirements |
|---|---|---|---|
| **`method`** | Formal algorithmic or mathematical method for computing calendar, astronomical, or combinatoric states. | Automated test vectors, computational complexity analysis, error bounds. | Primary astronomical/mathematical literature cited with edition and page references. |
| **`validation`** | Empirical benchmark comparing Quizzman implementations against external authoritative ground truth. | Full test suite execution, confusion matrices, pass/fail counts, failure analysis. | Ground truth datasets and reference tools cited with exact versions. |
| **`specification`** | Normative technical standard defining data structures, interfaces, rule engines, or protocol semantics. | Conformance test suite, edge-case coverage, JSON/TypeScript schema verification. | Upstream standard references (ISO, IETF, Unicode) where applicable. |
| **`technical-note`** | Focused analysis of an isolated anomaly, leap-second edge case, or mathematical derivation. | Numerical verification of the specific case. | Specific primary citation for the examined edge case. |
| **`historical-study`** | Scholarly analysis of historical calendar decrees, dynasty almanacs, or classical texts. | Source criticism, collation of textual variants, philological analysis. | Rigorous distinction between primary text, commentaries, and modern translations. |
| **`dataset`** | Description and curation methodology of a formal validation corpus or historical astronomical catalog. | Schema validation, checksum verification, provenance record. | Original observational records or archival source repositories. |
| **`system`** | Architectural description of large-scale computational infrastructure or distributed services. | System load benchmarks, latency profiles, fault-tolerance analysis. | Architecture references, open-source protocol specifications. |
| **`review`** | Comprehensive critical survey of existing literature, competing algorithms, or traditional models. | Comparative feature/accuracy matrix across published methods. | Exhaustive bibliography of survey corpus. |

---

## 7 Standard Paper Structure and Applicability Matrix

### 7.1 Structural Components

A QPS-ISO paper consists of three major divisions:

1. **Front Matter**:
   - Paper Title (Multilingual: `en`, `vi`, etc.)
   - Paper ID & Semantic Version
   - Status, Publication Date, Revision Date
   - Authors, Affiliations, ORCID identifiers, and CRediT roles
   - Abstract (Self-contained, structured)
   - Standardized Keywords
2. **Main Body (Divisions 1–16)**:
   - 1 Scope
   - 2 Normative references
   - 3 Terms and definitions
   - 4 Symbols and abbreviated terms
   - 5 Conventions and assumptions
   - 6 Background
   - 7 Sources and materials
   - 8 Methodology
   - 9 Formal model
   - 10 Algorithm or rules
   - 11 Implementation
   - 12 Validation
   - 13 Results
   - 14 Discussion
   - 15 Limitations
   - 16 Conclusion
   - Bibliography
3. **Annexes**:
   - Annex A — Algorithms
   - Annex B — Test vectors
   - Annex C — Source tables
   - Annex D — Derivations
   - Annex E — Supplementary data

### 7.2 Section Applicability Matrix

```text
M = Mandatory
O = Optional
C = Conditional (Mandatory under specific statuses, e.g. stable)
N = Not normally applicable
```

| Section | Method | Validation | Specification | Technical Note | Historical Study | Dataset | System | Review |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| **Front Matter** | M | M | M | M | M | M | M | M |
| **1 Scope** | M | M | M | M | M | M | M | M |
| **2 Normative references** | M | M | M | O | M | M | M | M |
| **3 Terms and definitions** | M | M | M | O | M | M | M | M |
| **4 Symbols and abbreviated terms** | O | O | O | O | O | O | O | O |
| **5 Conventions and assumptions** | M | O | M | O | M | M | M | O |
| **6 Background** | O | O | O | O | M | O | O | M |
| **7 Sources and materials** | M | M | O | O | M | M | O | M |
| **8 Methodology** | M | M | O | O | M | M | M | O |
| **9 Formal model** | M | O | M | O | O | O | M | O |
| **10 Algorithm or rules** | M | O | M | O | N | N | M | N |
| **11 Implementation** | O | M | M | O | N | O | M | N |
| **12 Validation** | M | M | C | O | N | M | M | N |
| **13 Results** | M | M | O | M | M | M | M | M |
| **14 Discussion** | O | M | O | O | M | O | M | M |
| **15 Limitations** | C | M | C | M | M | M | M | M |
| **16 Conclusion** | M | M | M | M | M | M | M | M |
| **Bibliography** | M | M | M | M | M | M | M | M |
| **Annexes** | O | O | O | O | O | O | O | O |

*Conditional rules:*
- For `stable` Method papers, **15 Limitations** and **12 Validation** are **Mandatory**.
- For `stable` Validation papers, **12 Validation** and **13 Results** are **Mandatory**.
- For `stable` Specification papers, **12 Validation** (conformance testing) and **15 Limitations** are **Mandatory**.

---

## 8 Numbering Principles (ISO 2145 Profile)

QPS-ISO adheres strictly to ISO 2145 for division and subdivision numbering:

1. **Hierarchy**: Divisions are numbered with Arabic numerals separated by single dots:
   ```text
   1 Scope
   2 Normative references
   3 Terms and definitions
   3.1 civil day
   3.2 solar term
   3.2.1 major solar term (Zhongqi)
   ```
2. **Terminal Period Prohibition**: Division numbers **SHALL NOT** end with a period.
   - Correct: `1 Scope`, `3.1 civil day`
   - Strictly Prohibited: `1. Scope`, `3.1. civil day`, `3.1.1.`
3. **Cross-References**: References to sections within prose SHALL use lowercase keywords with exact division numbers:
   - Correct: `see 7.3`, `as specified in 10.2`, `refer to Annex B`
   - Prohibited: `see section 7.3.`, `as defined in Section #10`
4. **Generated Anchors**: Heading slugs are automatically generated as `section-{number}` (e.g., `#section-3-1`) to ensure permanent, stable hyperlink anchors.

---

## 9 Normative and Informative Content

### 9.1 Distinctions
- **Normative Content**: Establishes mandatory behavior, formulas, and constraints that reference software libraries MUST execute without deviation.
- **Informative Content**: Explains context, rationale, historical context, or suggested optimizations. Informative content cannot establish binding requirements.

### 9.2 Markup and Metadata Annotation
Sections or Annexes may declare their normative designation explicitly:

```markdown
<!-- section_type: normative -->
## 10 Algorithm or rules
```
or
```markdown
<!-- section_type: informative -->
## 6 Background
```

Annexes SHALL explicitly declare their type in the title:
- `## Annex A — Astronomical Algorithms (Normative)`
- `## Annex B — Test Vectors and Benchmarks (Informative)`

---

## 10 Normative Vocabulary

When defining normative requirements, algorithms, and interfaces, papers SHALL use the following standardized modal verbs in capital letters:

| Keyword | Definition |
|---|---|
| **SHALL** | An absolute, mandatory requirement of the specification. Conformance is impossible without compliance. |
| **SHALL NOT** | An absolute prohibition. Any implementation exhibiting this behavior is non-conformant. |
| **SHOULD** | A strong recommendation. Valid reasons may exist in particular circumstances to ignore this item, but the full implications MUST be understood and documented. |
| **SHOULD NOT** | A strong recommendation against. |
| **MAY** | Truly optional behavior. |

*Usage constraint:* Authors SHALL NOT use uppercase `SHALL`, `SHOULD`, etc., in narrative or historical background prose where no normative rule is being formulated.

---

## 11 Abstract Composition (ISO 214 Profile)

In accordance with ISO 214 principles, an abstract in QPS-ISO:
1. SHALL be completely **self-contained**, intelligible without reading the paper.
2. SHALL NOT exceed 300 words.
3. SHALL NOT contain promotional hype, commercial calls to action (CTA), or subjective marketing slogans.
4. SHALL be structured into four distinct informational segments:
   - **Background / Problem**: The specific computational, historical, or astronomical problem addressed.
   - **Method**: The formal algorithm, mathematical approach, or philological method applied.
   - **Results**: Quantitative accuracy bounds, verified test cases, or historical findings.
   - **Conclusion**: The normative implications or recommended implementation standard.

---

## 12 Source and Evidence Model

To ensure scholarly and algorithmic integrity, Quizzman papers distinguish epistemic assertions according to a strict classification:

```text
source           → Direct citation of an uninterpreted primary text or ephemeris.
computed         → Output produced deterministically by an audited computational model.
derived          → Mathematical deduction proven from established axioms or rules.
interpretation   → Scholarly hypothesis or commentary explaining an ambiguous source.
tradition        → Heuristic convention transmitted through historical lineages without physical proof.
hypothesis       → Proposed explanation subject to ongoing empirical verification.
normative-rule   → Binding operational decision codified into software logic.
```

### 12.1 Source Classification Hierarchy
Sources listed in `references.yaml` SHALL be classified into:
1. `primary`: Original dynasty astronomical tables, ephemeris archives (JPL DE440), foundational mathematical treatises.
2. `secondary`: Peer-reviewed scholarly monographs, commentaries, and critical editions.
3. `tertiary`: Encyclopedias, general textbooks, overview surveys.
4. `software`: Reference astronomical engines, official standard libraries.
5. `dataset`: Structured validation sets, benchmark databases.
6. `traditional-text`: Pre-modern manuscript copies, woodblock prints, transmitted canons.
7. `legal`: Official state calendar decrees or governmental standards.
8. `archival`: Historical observatory logs or rare manuscripts.
9. `web`: Online resources, documentation portals.

**Authoring Rule:** Writers SHALL NOT present a later scholarly interpretation as if it were the direct text of a primary source.

---

## 13 Reproducibility Manifest

Every paper that introduces or validates computational methods SHALL provide a `reproducibility` manifest in `metadata.yaml`, including:

```yaml
reproducibility:
  software:
    name: Quizzman Calendar Engine
    version: 2.1.0
    commit: a9b4c81f7e02
  runtime:
    node: 20.x
  algorithms:
    - VSOP87D
    - ELP2000-82B
  datasets:
    - CAL-BENCH-001@1.2.0
  timezone_database:
    name: IANA tzdb
    version: 2026b
```

Finite test suite outcomes (e.g. `139/139 test cases passed`) SHALL specify the exact input domain and limitations. Authors SHALL NOT extrapolate finite test passes into claims of "universal 100% accuracy".

---

## 14 Multilingual Model

A paper MAY provide translations alongside its canonical text:

```yaml
language: vi
translations:
  - en
  - zh-Hant
```

### Prevailing Edition Rule
In the event of semantic discrepancy, grammatical divergence, or translation ambiguity between language editions:

> **The canonical-language version SHALL prevail.**

This rule guarantees unambiguous legal and algorithmic interpretations across international deployments.

---

## 15 Conformance and Designation

A document may claim compliance with this standard if and only if it satisfies all of the following requirements:
1. `metadata.yaml` passes schema validation against `schema/paper.schema.json`.
2. All cited references in `references.yaml` validate against `schema/citation.schema.json`.
3. Division numbering conforms to ISO 2145 rules without terminal dots.
4. All mandatory sections for its declared paper type are present.
5. All internal cross-references and citation links resolve without error.
6. The paper complies with `docs/EDITORIAL-POLICY.md`.

Documents meeting these criteria are designated:

```text
QPS-ISO 1.0 Conformant
```

**Prohibited Designations:** Under no circumstances SHALL any paper be labeled "ISO Certified", "ISO Approved", or "Official ISO Standard".