Flywheel Loop

The grading process is a self-reinforcing flywheel: provider folders and selection definitions are imported into the workbench, graded by the provider-side and selection-side areas, and the graded state is exported back as index.json. Each turn improves the inputs to the next — a stronger schema lifts every selection that contains it, and every selection run surfaces the weakest schemas in a namespace. This chapter traces that round-trip end to end, names the three loops that keep it spinning, and lists the anti-patterns that break it.

---

The Flywheel as an IN/OUT Round-Trip

The grading process is a round-trip between the source repository and the workbench:

• IN — a provider folder (or selection definition) is imported into the workbench, snapshotted, and normalised.
• Grade — the provider-side and selection-side Areas grade the imported primitives, writing _gradings/ and rolling them up into index.json.
• OUT — the graded state, primarily the index.json, is exported back to the source.

The pattern is self-reinforcing: every improvement raises the aggregate quality of the selections that contain the schema, and every selection run identifies the weakest schemas in a namespace. The loop is iteration over the same artefacts; the workbench index.json carries the current graded state across rounds.

---

Mermaid Diagram

---

Reading Direction

Reading direction: top-down (flowchart TD) follows the iteration flow. The pre-condition gate and the stable back-reference make the flywheel effect visible: every new stable provider-side grade opens the door for selection-side grading, and every selection run identifies the weakest schemas in the namespace.

---

Reference Fields per Node

Node	Reference
IMPORT / OUT	19-folder-layout.md — the IN/OUT round-trip and folder layout
NS / SCHEMA	04-phases-single.md — provider-side Areas; 08-grading-model.md — data model
SINGLE / SGRADE	04-phases-single.md, 05-phases-selection.md — Area _gradings/ placement
IDXN / IDXS	19-folder-layout.md — the index.json rollup (live rollup + frozen lockSnapshot, 5-status)
GATE	21-pre-conditions.md — pre-conditions (only stable members pass)
STABLE / PART	06-determinism-and-tier.md — partial vs. full and the five node statuses
ABOUT	11-about-convention.md — About as a schema Resource

---

Self-Reinforcing Effect

The flywheel is self-reinforcing along three loops:

1. Quality loop per schema: SINGLE → CHECK → FIX → NEWSNAP → SCHEMA → SINGLE. Each iteration writes a new versioned snapshot (timestamp + hash in the file name); the next grading tests the improved schema variant. The hash binding lives in index.json, never in the source (see 19-folder-layout.md).
2. Aggregation loop per selection: SGRADE → (on member change) GATE → SGRADE. Every re-grading of a member updates the namespace index.json; the selection’s frozen lockSnapshot is refreshed at the next selection-grading start.
3. About-verification loop: ABOUT (route-exists + content check) → on change a new About snapshot → re-check; the namespace index.json records the new About grade.

Anti-Patterns

The following patterns break the flywheel and are excluded by the spec:

• Partial gradings without a concluding full grading: the node status never reaches stable, the selection stays blocked (see 06-determinism-and-tier.md).
• Schema edit without a new snapshot: a source edit MUST produce a new versioned snapshot file; editing in place breaks the latest-resolution and the hash binding (see 19-folder-layout.md).
• Selection grading with non-stable members: the pre-condition (see 21-pre-conditions.md) blocks the selection run before any Area runs.
• Reading the live directory instead of the frozen snapshot: the pre-condition gate MUST read the frozen index.json.lockSnapshot, not the live rollup. Reading the live directory aggregates over members that are still moving between rounds, so the gate would judge an unstable point in time and the result would not be reproducible (see 16-selection-lockfile.md).

Related

• ./00-overview.md — see chapter 00.
• ./04-phases-single.md — see chapter 04.
• ./05-phases-selection.md — see chapter 05.
• ./06-determinism-and-tier.md — see chapter 06.
• ./08-grading-model.md — see chapter 08.
• ./11-about-convention.md — see chapter 11.
• ./19-folder-layout.md — see chapter 19.
• ./21-pre-conditions.md — see chapter 21.