-
Notifications
You must be signed in to change notification settings - Fork 0
Home
This page explains the library end to end: what governs an edit, how a case moves from idea to finished teaching material, how citations are kept honest, how the knowledge graph holds the argument together, and how a GitHub Project tracks the work alongside it. Each part has a narrative and a diagram. The diagrams are Mermaid, which GitHub renders in both the repository and the wiki.
- The governing files and their precedence
- Where content lives and where workflow lives
- The case lifecycle
- The twin citation rule
- The knowledge graph
- The citation-integrity pipeline
- The GitHub Project workflow
- Publishing this wiki
Five files govern every edit, read in order before any work: README.md,
00_style_guide.md, 01_library_map.md, 03_ontology.md, and
04_knowledge_graph.yaml. 02_case_template.md is the shape every case follows.
CLAUDE.md carries the project context for agent sessions.
When two rules disagree there is a fixed precedence, so a conflict has one answer. The style guide outranks the library map, the library map outranks the knowledge graph, and the knowledge graph outranks any stale prose in a case file.
flowchart TD
CL["CLAUDE.md<br/>project context, sealed dimensions"]
SG["00_style_guide.md<br/>voice, twin rule, citation integrity"]
LM["01_library_map.md<br/>dimensions, themes, backlog"]
ON["03_ontology.md<br/>node and edge types"]
KG["04_knowledge_graph.yaml<br/>live typed graph"]
TM["02_case_template.md<br/>the case structure"]
PR["cases/*.md<br/>case prose"]
CL --> SG
SG -->|wins over| LM
LM -->|wins over| KG
KG -->|wins over| PR
ON -.defines schema for.-> KG
TM -.shapes.-> PR
The repository and the GitHub Project are two layers. The repository is the source of truth for content (the case files) and for the argument (the knowledge graph). The Project is the source of truth for workflow state (which case is being drafted, which sources still need verifying). The two link, and they never duplicate. Claims and twins stay in the YAML; the Project never holds a second copy of them.
flowchart LR
subgraph Repo["Git repository"]
files["cases/, references.bib,<br/>bibliography.md, glossary.md"]
kg["04_knowledge_graph.yaml<br/>source of truth for<br/>claims and twins"]
end
subgraph Project["GitHub Project (private)"]
issues["Issues = candidate cases"]
fields["Fields: Dimension, Status,<br/>Sources verified"]
views["Views: backlog, pipeline,<br/>coverage, roadmap"]
end
issues -. links to .-> files
issues -. links to .-> kg
Project -. never duplicates .-> kg
A case moves through four states. Each transition has a gate. A candidate has a
graph node and verified sources but no prose. A draft has prose and passes the
voice and twin self-check. Review is a second reader. Final is release-ready, with
sources_verified set true in the frontmatter.
stateDiagram-v2
[*] --> Candidate
Candidate --> Draft: sources gathered and read
Draft --> Review: self-check passes (voice, twins)
Review --> Final: second reader, sources_verified true
Final --> [*]
Draft --> Candidate: a fact will not verify
Review --> Draft: a twin fails the super-match
The two backward arrows matter. A fact that will not verify sends a case back to candidate. A twin that fails the super-match sends it back to draft. The gates run forward; the failures send work back to where it can be fixed.
Every analytical paragraph carries one seminal source and one current source, and the current source engages the seminal source on the same claim. A modern citation paired with an unrelated old one is a name-drop and does not count. The narrative paragraphs that report what happened at a named institution are exempt, as long as every fact they carry is sourced.
flowchart TD
P["Analytical paragraph<br/>states one claim"] --> S["Name the seminal source<br/>about 15+ years old"]
P --> C["Name the current source<br/>within the last 5 years"]
S --> M{"Super-match?<br/>current engages seminal<br/>on the same claim"}
C --> M
M -->|yes| OK["Twin valid<br/>add a twin: node in the KG"]
M -->|no| RE["Name-drop. Re-pair the sources."]
RE --> S
The argument is a typed graph. A case addresses one or more dimensions, is set in
an institution, teaches lessons, advances claims, and reports outcomes. A claim is
anchored by a twin, which pairs a seminal source with a current source. The schema
is declared in 03_ontology.md; the live graph is 04_knowledge_graph.yaml.
erDiagram
CASE ||--|{ DIMENSION : addresses
CASE ||--|| INSTITUTION : set_in
CASE ||--o{ LESSON : teaches
CASE ||--o{ CLAIM : advances
CASE ||--o{ OUTCOME : reports
TWIN ||--|| CLAIM : anchors
SEMINAL_SOURCE ||--o{ TWIN : seminal_of
CURRENT_SOURCE ||--o{ TWIN : current_of
CURRENT_SOURCE ||--|| SEMINAL_SOURCE : extends
CLAIM ||--o{ CONCEPT : uses
CONCEPT ||--o{ THEME : instantiates
OUTCOME ||--|| DATASOURCE : derived_from
The constraints the graph enforces: every dimension label matches the sealed
eight; every twin has one seminal and one current end with an extends edge
between them; every claim a case advances is anchored by a twin; every case
addresses a dimension, sits in an institution, and teaches a lesson; every outcome
names a data source; and every source maps one to one to a references.bib key.
A source earns its place by passing the integrity rules before it anchors anything. Rule 0 is cardinal: do not cite a document you have not read yourself. Rule 1 verifies the DOI or stable URL against the publisher. Rule 5 confirms the work is still live and not retracted or withdrawn.
flowchart LR
cand["Candidate source<br/>found via a search tool"] --> read["Read the full text<br/>(Rule 0)"]
read --> ver["Verify DOI or stable URL<br/>against the publisher (Rule 1)"]
ver --> live{"Live? not retracted<br/>or withdrawn (Rule 5)"}
live -->|no| drop["Drop it. Re-anchor any<br/>claim it held."]
live -->|yes| bib["Enter references.bib<br/>and add a source: node"]
bib --> anchor["May now anchor a claim<br/>through a twin"]
The eleven seeded sources passed Rule 1 on 24 June 2026 (metadata and DOI or ISBN checked against the publisher). The bibliography records the date on each. Rule 0 still applies before any of them anchors a published case.
The Project turns each candidate case into an Issue and moves it through the
pipeline while its fields drive several views. The full field and view
specification is in PROJECT_SETUP.md.
flowchart TD
new["New candidate case"] --> issue["Open an Issue, label: case"]
issue --> auto["Workflow auto-adds it<br/>Status = Candidate"]
auto --> fields["Set fields:<br/>Dimension, Theme, Institution,<br/>Sources verified"]
fields --> board["Pipeline board:<br/>Candidate to Final"]
fields --> vq["Verification queue:<br/>Sources verified is not Yes"]
fields --> cov["Coverage board:<br/>grouped by Dimension"]
cov --> ins["Insights chart:<br/>cases per dimension"]
board --> done["Final, sources_verified true,<br/>file linked in cases/"]
The coverage board and the cases-per-dimension chart answer the same question the
backlog table in 01_library_map.md asks: which of the eight dimensions still has
no strong case. An empty column is the next case to write.
These pages live in wiki/ inside the repository so they version with the code
and render on GitHub as ordinary Markdown. To surface them as the repository's
GitHub Wiki, see wiki/README.md for the two-line publish step. Edit the source
here, then publish, so the wiki and the repository never disagree.