# MazeXChain Reading Rules

Last updated: 2026-05-08

This file defines the mandatory reading order for future AI sessions. Its purpose is to prevent partial context, skipped protocol rules, and accidental reintroduction of old design directions.

## 1. Mandatory Start Sequence

For any project-level task, read these files in order before planning or editing:

```text
1. PROJECT_CONTEXT.md
2. PROJECT_SCOPE.md
3. PROJECT_READING_RULES.md
4. PROJECT_STATUS.md
5. README.md
6. CHANGELOG.md
7. ROADMAP.md
8. docs/protocol-vocabulary.md
```

After this sequence, continue through the task-specific reading route below.

## 2. Global Stop Rule

If the requested work touches protocol behavior, wallet behavior, chain state, storage, networking, security, deployment, or public documentation, do not edit until the matching reading route has been completed.

If two project-control files conflict, follow this order of authority:

```text
1. PROJECT_SCOPE.md
2. PROJECT_CONTEXT.md
3. PROJECT_READING_RULES.md
4. PROJECT_STATUS.md
5. README.md
6. ROADMAP.md
7. docs/*
8. older MazeX_*.md design notes
```

When a conflict is found, update the older or less authoritative file in the same change.

## 3. Task Reading Routes

| Task Area | Must Read Next | Then Inspect |
| --- | --- | --- |
| Protocol / challenge generation | `docs/architecture.md`, `docs/data-flow.md`, `docs/modules.md`, `config/chain.config.json`, `config/consensus.config.json` | `src/lib/base1_algorithm.js`, `src/lib/difficulty.js`, parameter and operator modules |
| Verification / answer budget | `docs/data-flow.md`, `docs/security.md`, `config/consensus.config.json`, `config/security.config.json` | `src/lib/expression_tree_verifier.js`, `src/lib/budget.js`, `src/lib/blackbox.js` legacy challenge-behavior alias |
| Layer / Step state transition | `docs/architecture.md`, `docs/data-flow.md`, `genesis/README.md`, `config/chain.config.json` | `src/lib/base1_state.js`, `src/lib/chain.js`, storage modules |
| Fragment registry | `docs/architecture.md`, `docs/security.md`, `config/consensus.config.json` | `src/lib/fragment_registry.js`, `src/lib/base1_state.js` fragment-related paths |
| Wallet extension | `docs/security.md`, `docs/api-design.md`, `config/wallet.config.json`, `config/security.config.json` | `extension/`, `public/wallet_crypto.mjs`, wallet bridge code in `public/app.js` |
| Transfers / balances / fees | `docs/data-flow.md`, `docs/api-design.md`, `config/chain.config.json`, `config/wallet.config.json` | `src/lib/wallet.js`, `src/lib/base1_state.js`, transfer API paths |
| Web UI | `PROJECT_CONTEXT.md` section 8, `docs/website-information-architecture.md`, `docs/api-design.md`, `README.md` | `public/index.html`, `public/app.js`, `public/styles.css`, top-level `public/*.html` pages |
| Whitepaper / public docs | `PROJECT_CONTEXT.md`, `PROJECT_SCOPE.md`, `docs/architecture.md`, `docs/security.md`, `docs/whitepaper/README.md`, `docs/whitepaper/sources/*.md` | `public/whitepaper.html`, `public/whitepaper.zh.html`, related PDF tooling |
| P2P / node sync | `docs/data-flow.md`, `docs/api-design.md`, `docs/security.md`, `config/network.config.json` | `src/lib/p2p_network.js`, node API paths, sync tools |
| Storage / replay / snapshots | `docs/architecture.md`, `docs/data-flow.md`, `docs/security.md`, `genesis/README.md` | `src/lib/sharded_chain_storage.js`, replay tools, `data/` structure |
| API security / public deployment | `docs/security.md`, `docs/deployment.md`, `docs/api-design.md`, `config/security.config.json`, `config/network.config.json` | `src/lib/mainnet_security.js`, `src/server.js` |
| Config / genesis wiring | `docs/architecture.md`, `docs/modules.md`, `genesis/README.md`, every touched `config/*.json` | runtime loader paths and modules using equivalent constants |
| Tests / stress tools | `PROJECT_STATUS.md`, `README.md`, `docs/modules.md` | `tools/`, future `tests/` tree, package scripts |
| Packaging / downloads | `docs/deployment.md`, `PROJECT_CONTEXT.md` section 8 | `tools/package_downloads.ps1`, `tools/package_extension.ps1`, `public/downloads/` |
| Server upload / public host | `docs/deployment.md`, `PROJECT_SCOPE.md`, `PROJECT_CONTEXT.md` | deployment scripts and server-only paths only after explicit user approval |

## 4. Chapter-Level Rules

When reading a project-control file, these sections require follow-up reads:

| File Section | Required Follow-Up |
| --- | --- |
| `PROJECT_CONTEXT.md` section 3 Active Protocol Line | `PROJECT_SCOPE.md` sections 2 and 4, then `docs/architecture.md` |
| `PROJECT_CONTEXT.md` section 4 Product and Protocol Decisions | `PROJECT_SCOPE.md` sections 3, 5, 6, 8, and 9 |
| `PROJECT_CONTEXT.md` section 5 Current Implementation Snapshot | `PROJECT_STATUS.md` module table |
| `PROJECT_CONTEXT.md` section 7 Safety Boundaries | `docs/security.md`, `config/security.config.json` |
| `PROJECT_CONTEXT.md` section 8 User-Facing Style Decisions | UI or wallet files only after reading the relevant task route |
| `PROJECT_SCOPE.md` section 2 Active Protocol Line | `docs/architecture.md`, `docs/data-flow.md`, active Base1 modules |
| `PROJECT_SCOPE.md` section 3 Non-Negotiable Engineering Rules | The exact module route for the requested work |
| `PROJECT_SCOPE.md` section 5 Security Boundaries | `docs/security.md`, private-vault and wallet-related modules when touched |
| `PROJECT_SCOPE.md` section 6 Wallet Boundary | `config/wallet.config.json`, `extension/`, `public/wallet_crypto.mjs` |
| `PROJECT_STATUS.md` module table | The listed main files for any area being changed |
| `README.md` Core Flow | `docs/data-flow.md` and the modules for the affected step |
| `CHANGELOG.md` current date section | Update it after meaningful changes |
| Any protocol terminology or public wording | `docs/protocol-vocabulary.md` |

## 5. Old Document Rule

Files named `MazeX_*.md` are historical design notes unless they are explicitly referenced by current control documents or active modules.

Before using an old design note:

```text
1. Check whether PROJECT_SCOPE.md allows that direction.
2. Check whether PROJECT_STATUS.md marks it as active, designed, historical, or deferred.
3. Do not promote it into active runtime behavior without a migration note.
```

## 6. Editing Readiness Checklist

Before editing, confirm:

```text
1. The mandatory start sequence was read.
2. The task-specific route was read.
3. The exact files to change are known.
4. The relevant verification command is known.
5. No private material will be exposed.
6. No deprecated logic will be reintroduced.
7. The change will update status/context/changelog if needed.
8. The change will be committed to Git.
```

If any item is false, keep reading before editing.

## 7. Verification Route

Default checks:

```powershell
git diff --check
node --check src/server.js
npm run smoke
```

Wallet changes also require:

```powershell
node --check extension\popup.mjs
node --check extension\background.mjs
node --check extension\confirm.mjs
npm run package:downloads
```

Config and genesis changes also require:

```powershell
node -e "for (const f of ['config/app.config.json','config/chain.config.json','config/network.config.json','config/consensus.config.json','config/genesis.config.json','config/wallet.config.json','config/security.config.json','genesis/genesis.json','genesis/initial-accounts.json','genesis/initial-fragments.json']) JSON.parse(require('fs').readFileSync(f,'utf8')); console.log('json ok')"
```

## 8. Final Handoff Rule

Every final answer after a meaningful change must include:

```text
1. What changed.
2. What was verified.
3. Whether runtime behavior changed.
4. Git commit hash.
5. Next recommended step.
```
