Reading guide¶

This repository holds more planning than code, on purpose, and the planning files are large. ROADMAP.md and ARCHITECTURE.md together run past two hundred kilobytes. Reading them front to back is the wrong first move.

Pick the route that matches the time you have.

Contents¶

Before you start: what is built
Route A: fifteen minutes
Route B: one hour
Route C: contributing
Go straight to the part you care about
Check the claims yourself
What is not here

1. Before you start: what is built¶

Phase P0 is the contract phase, it is done, and v0.1.0 tags it. It carries no product of its own, because its job is to fix the decisions a later phase cannot change without invalidating every run already recorded. Phase P1 is the one open phase, and the running parts arrive with it.

Question	Answer today
What is tagged	v0.1.0, the P0 contracts release. P1 is open and untagged
What installs	Eleven workspace members, each alone: the ten `twinflow-*` packages and the `twinflow-roadmap` tool. Each one carries a `tests/test_brick_isolated.py` that proves it
What runs	`SCN-F1`, a determinism scenario that writes an event log and matches its own hash across two runs, and `just demo`, the headless ten-minute demo over the shipped packages
What exists	The station model, an RFID portal and a temperature sensor, the Sparkplug B session, the event-sourced historian, the REST API, one agent tool, and the dashboard
What does not exist	The statistical engine, which is what phase P2 delivers
Gates	Every gate in force at the P0 exit is implemented and runnable. Four of the gates in force at P1 are specified rather than implemented, so P1 has an unarmed set to close. gates.md generates the counts from `gates.yaml`

A reader who wants a running warehouse will not find one: one station, two devices, and a dashboard tile are the P1 scope, not a facility. A reader who wants to see how someone sets up a system so that its later numbers can be trusted is in the right place.

2. Route A: fifteen minutes¶

This route answers one question: is the engineering here serious, or is it a large plan with nothing underneath it.

Read README.md, and stop at the section named "Determinism, and what it does not mean". That section states a strong property and then removes the three overclaims it invites.
Read the metric marker comment block near the top of the same file. Every quantitative result sits inside a marker. Every marker reads TBD. A release cannot be tagged while it owes one, so this repository states no number it has not measured.
Open DOCTRINE.md and read ruling D-01 only. It is one page. It catches a defect that would have failed the headline determinism claim on the first event of every log. It fixes that by splitting the run manifest.
Open gates.md and read the three-status table at the top. A gate must be declared one phase before the subsystem that satisfies it is built.
Skim section 5 of ROADMAP.md, the resequencing record. It logs every change to the build order with the clause that forced it. Nothing is ever deleted from the plan.

If those five leave you unconvinced, the rest will not change your mind. If they land, take Route B.

3. Route B: one hour¶

This route is for an engineer judging depth. Read in this order.

Section 1 of ARCHITECTURE.md, the technology decision record. Sixteen decisions, each with its rejected alternatives and the reason. Read the D16 note last. It explains why the random number generator is not numpy's default, and it is the one decision that argued its way to a numeric ceiling.
Sections 2 and 4 of the same file. Section 2 is the dual-mode determinism argument. Section 4 is the ISA-95 and Purdue layer map, which gives every component a real-world counterpart.
All of DOCTRINE.md. Fourteen rulings, each written because the same defect appeared in three or more design sections.
foundations.md, which is the section the shipped packages were built from.
The code, in this order: packages/twinflow-rng/src/twinflow/rng/derive.py, then its tests, then packages/twinflow-schemas/src/twinflow/schemas/envelope.py. The RNG derivation is content-addressed. A stream's identity comes from its name, not from the order it was requested in.
justfile, which is the whole task surface. CI calls the same recipes, so a green local run and a green CI run mean the same thing.

4. Route C: contributing¶

Read CONTRIBUTING.md first, then these six in any order:

Document	Why you need it
ENGINEERING.md	The working method, and the rules a change is judged against
testing-strategy.md	Which kind of test a change needs, and what makes a test count
testing-policy.md	The rule that a fix ships with the test that catches it
performance.md	What a speed claim owes, and which optimizations determinism forbids
code-review.md	What a reviewer checks, and what blocks a merge
DOCUMENTATION-STANDARD.md	The writing rules, and which of them CI enforces without a human

Then run just check before you write anything, so you know what green looks like on your machine.

5. Go straight to the part you care about¶

If your interest is	Read
Reproducible simulation	ARCHITECTURE.md section 2, doctrine D-01 to D-05, and `packages/twinflow-rng/`
Industrial protocols and the plant floor	ARCHITECTURE.md sections 4 to 7, and iot-fleet.md
Statistics and quality engineering	lss-engine.md, and the validation table in README.md
LLM accuracy and grounding	ai-layer.md, and the seven-layer list in README.md
Repository and release engineering	repo-craft.md, the `justfile`, and `scripts/checks/`
Software licensing in practice	Decision D14, doctrine D-14, and LICENSING.md
Technical writing under a standard	DOCUMENTATION-STANDARD.md and `scripts/checks/prose-gate.py`
Terms you do not recognize	glossary.md

6. Check the claims yourself¶

Nothing on this page asks for trust. Each command below tests a claim made above, and each one runs from a clean clone.

uv sync                  # install the workspace
just check               # lint, typecheck, and the fast test tier
just determinism         # the two-run hash match, plus the RNG known-answer corpus
just roadmap             # validate the plan, prove coverage, lint the dependency graph
just lint                # every gate that needs no container

just roadmap coverage is the one worth watching. It proves that every milestone id recorded in the plan is placed in a phase. An id with no phase is a silent cut, and this project keeps no cut list.

just determinism runs SCN-F1 twice and compares the two event logs byte for byte. One differing byte fails it.

7. What is not here¶

The repository states its own limits in README.md. The four that matter most to a reader judging the work:

All data is synthetic. Every reading, event, order, and lot is generated by this repository, and nothing here is evidence about any real facility.

No measured performance numbers exist for the system this repository models. The scaling curve, the eval accuracy, and the quickstart timing are all unfilled markers, and they stay unfilled until a recorded run produces them. The build tooling is the one exception: hook startup is measured, and those figures live beside the code they justify.

No real control hardware is in the default path. The OT layer is simulated, and an OPC UA bridge is a roadmap milestone rather than a current capability.

The statistical engine is validated, not certified. Checking outputs against published reference values is reproducible evidence on the covered cases. It does not make the software fit for regulated measurement or release decisions.