Score causal graph readiness and enhance records

README.md

@@ -68,7 +68,7 @@ records, not records; phenotypes are TraitMech records. See
 | SECRETION_SYSTEM | 1 | |  |  |
 | SPORE | 1 | |  |  |
 
-17 records are grounded in GO; 2 carry minted identifiers. 19 list components, 9 carry causal graphs (56 evidence-backed edges), 8 link to TraitMech traits, and 5 carry licensed, cited imaging evidence.
+17 records are grounded in GO; 2 carry minted identifiers. 19 list components, 19 carry causal graphs (152 evidence-backed edges), 8 link to TraitMech traits, and 5 carry licensed, cited imaging evidence.
 <!-- END GENERATED CORPUS STATS -->
 
 Run `just report` for the live report. Every current record is

data/structures/appendage/bacterial_type_flagellum.yaml

@@ -558,19 +558,25 @@ causal_graphs:
   - subject: c_ring
     predicate: drives
     object: rotation
+    description: Torque on FliG and the C ring turns the MS ring, rod, hook, and filament
+      as a rigid flagellar rotor.
     evidence:
     - reference: DOI:10.1016/j.tim.2014.12.011
       notes: The C ring, MS ring and rod rotate as one rigid rotor.
   - subject: rotation
     predicate: propels
     object: filament
+    description: Rotation is transmitted from the basal body through the hook to the
+      external helical filament.
     evidence:
     - reference: DOI:10.1146/annurev.biochem.72.121801.161737
       notes: Rotation of the helical filament produces thrust.
   - subject: filament
     predicate: enables
     object: swimming
     predicate_id: RO:0002327
+    description: The rotating helical filament acts as a propeller that generates
+      thrust for swimming motility.
     evidence:
     - reference: DOI:10.1146/annurev.biochem.72.121801.161737
       notes: Berg 2003.
@@ -698,5 +704,11 @@ curation_history:
     reviewed UniProt examples, type=family entries, and unchanged family consensus
     across curated scope examples.
   llm_assisted: true
+- timestamp: '2026-09-04T01:40:08Z'
+  curator: codex
+  action: ENHANCE_CAUSAL_GRAPH
+  changes: Added descriptions to the remaining flagellar torque-generation edges so
+    every edge now states the mechanistic step it represents.
+  llm_assisted: true
 xrefs:
 - uniprot.location:SL-0307

data/structures/appendage/type_iv_pilus.yaml

@@ -71,6 +71,85 @@ functions:
 evidence:
 - reference: DOI:10.1038/nrmicro.2017.40
   notes: A comprehensive guide to pilus biogenesis in Gram-negative bacteria.
+causal_graphs:
+- graph_id: extension_retraction_twitching
+  title: PilB and PilT drive type IV pilus extension-retraction cycles
+  description: The extension ATPase assembles pilin subunits into the extracellular
+    filament, and the retraction ATPase pulls an attached filament back through the
+    envelope. Surface-attached retraction generates the force used for twitching motility.
+  graph_kind: FUNCTION
+  scope_status: MECHANISTIC
+  nodes:
+  - node_id: extension_atpase
+    label: PilB-family extension ATPase
+    node_type: GENE_OR_PROTEIN
+    component_ref: extension_atpase
+  - node_id: major_pilin
+    label: major type IV pilin
+    node_type: GENE_OR_PROTEIN
+    component_ref: major_pilin
+  - node_id: pilus_filament
+    label: type IV pilus
+    node_type: STRUCTURE
+    grounding: GO:0044096
+  - node_id: surface_bound_pilus
+    label: surface-bound type IV pilus
+    node_type: STATE
+  - node_id: retraction_atpase
+    label: PilT-family retraction ATPase
+    node_type: GENE_OR_PROTEIN
+    component_ref: retraction_atpase
+  - node_id: twitching_motility
+    label: type IV pilus-dependent motility
+    node_type: BIOLOGICAL_PROCESS
+    grounding: GO:0043107
+  edges:
+  - subject: extension_atpase
+    predicate: extends
+    object: pilus_filament
+    description: The cytoplasmic PilB-family ATPase powers pilus extension from the
+      inner-membrane assembly platform.
+    evidence:
+    - reference: DOI:10.1038/nrmicro.2017.40
+      notes: Hospenthal, Costa and Waksman 2017 review the PilB-family ATPase as the
+        motor that extends Gram-negative type IV pili.
+  - subject: major_pilin
+    predicate: polymerizes into
+    object: pilus_filament
+    description: Major pilin subunits form the surface-exposed type IV pilus polymer.
+    evidence:
+    - reference: DOI:10.1038/nrmicro.2017.40
+      notes: Hospenthal, Costa and Waksman 2017 describe T4P fibres as polymers of
+        pilin subunits assembled by the biogenesis machinery.
+  - subject: pilus_filament
+    predicate: reaches
+    object: surface_bound_pilus
+    description: Extension projects the pilus outward so its distal end can bind a
+      surface or neighboring cell.
+    evidence:
+    - reference: DOI:10.1073/pnas.121171698
+      notes: Skerker and Berg 2001 directly observed Pseudomonas aeruginosa type IV
+        pili extending, attaching at their distal ends and retracting.
+  - subject: retraction_atpase
+    predicate: retracts
+    object: surface_bound_pilus
+    description: The PilT-family ATPase depolymerizes the attached filament back into
+      the envelope.
+    evidence:
+    - reference: DOI:10.1038/35024105
+      notes: Merz, So and Sheetz 2000 measured Neisseria gonorrhoeae pilus retraction
+        and showed that force generation and motility require PilT.
+  - subject: surface_bound_pilus
+    predicate: pulls cell during
+    object: twitching_motility
+    description: Retraction of a surface-bound filament pulls the cell body forward.
+    evidence:
+    - reference: DOI:10.1038/35024105
+      notes: Merz, So and Sheetz 2000 used laser tweezers to show that T4P filaments
+        retract with enough force to move cells.
+    - reference: DOI:10.1073/pnas.121171698
+      notes: Skerker and Berg 2001 directly observed Pseudomonas aeruginosa pili alternating
+        extension and retraction during surface motility.
 mapping_status: PROPOSED
 curation_history:
 - timestamp: '2026-08-30T19:30:00Z'
@@ -107,6 +186,13 @@ curation_history:
     and exact GO identity, preserved annotation quality metadata, and stored no imaging
     volumes.
   llm_assisted: true
+- timestamp: '2026-09-04T00:58:09Z'
+  curator: codex
+  action: ADD_CAUSAL_GRAPH
+  changes: Added a DOI-backed FUNCTION graph for the PilB/PilT extension-retraction
+    cycle that assembles type IV pili and pulls surface-bound cells during twitching
+    motility.
+  llm_assisted: true
 datasets:
 - accession: CryoETDataPortal:10155
   title: Bdellovibrio attack-phase

data/structures/cytoskeleton/mreb_filament.yaml

@@ -84,6 +84,84 @@ evidence:
 - reference: DOI:10.1016/j.cell.2018.02.050
   notes: 'Shi H, Bratton BP, Gitai Z, Huang KC 2018, ''How to Build a Bacterial Cell:
     MreB as the Foreman of E. coli Construction'', Cell.'
+causal_graphs:
+- graph_id: filament_guided_sidewall_synthesis
+  title: MreB and RodZ orient sidewall synthesis to preserve a rod
+  description: MreB subunits form membrane-associated filaments that RodZ couples
+    to the elongasome. Those filaments orient circumferential sidewall peptidoglycan
+    synthesis, and the resulting feedback keeps rod-shaped cells from widening into
+    spheres.
+  graph_kind: FUNCTION
+  scope_status: MECHANISTIC
+  nodes:
+  - node_id: mreb
+    label: MreB
+    node_type: GENE_OR_PROTEIN
+    component_ref: mreb
+  - node_id: mreb_filament
+    label: MreB filament
+    node_type: STRUCTURE
+    grounding: cellstructuremech:mreb_filament
+  - node_id: rodz
+    label: RodZ
+    node_type: GENE_OR_PROTEIN
+    component_ref: elongasome_link
+  - node_id: elongasome
+    label: elongasome
+    node_type: STRUCTURE
+    grounding: cellstructuremech:elongasome
+  - node_id: sidewall_synthesis
+    label: peptidoglycan biosynthetic process
+    node_type: BIOLOGICAL_PROCESS
+    grounding: GO:0009252
+  - node_id: rod_shape
+    label: rod shaped
+    node_type: TRAIT
+    grounding: METPO:1000681
+  edges:
+  - subject: mreb
+    predicate: polymerizes into
+    object: mreb_filament
+    description: MreB monomers assemble into short membrane-bound filaments.
+    evidence:
+    - reference: DOI:10.1016/j.cell.2018.02.050
+      notes: Shi, Bratton, Gitai and Huang 2018 review E. coli MreB filament architecture
+        and membrane association.
+  - subject: rodz
+    predicate: couples
+    object: elongasome
+    description: RodZ bridges MreB filaments to the cell-wall synthesis machinery.
+    evidence:
+    - reference: DOI:10.1016/j.cell.2018.02.050
+      notes: Shi, Bratton, Gitai and Huang 2018 review cytoplasmic RodZ-MreB binding
+        and periplasmic RodZ contacts with wall-synthesis enzymes.
+  - subject: mreb_filament
+    predicate: orients
+    object: elongasome
+    description: Curvature-biased filaments constrain where and in which direction
+      the Rod complex inserts new wall.
+    evidence:
+    - reference: DOI:10.1016/j.cell.2018.02.050
+      notes: Shi, Bratton, Gitai and Huang 2018 describe MreB as a curvature sensor
+        that both detects and changes local shape.
+  - subject: elongasome
+    predicate: carries out
+    object: sidewall_synthesis
+    description: The elongasome is the RodA/PBP2 peptidoglycan synthase complex that
+      builds the cylindrical sidewall.
+    evidence:
+    - reference: DOI:10.1038/nrmicro2677
+      notes: Typas, Banzhaf, Gross and Vollmer 2011 review the elongation complex
+        that builds sidewall peptidoglycan.
+  - subject: sidewall_synthesis
+    predicate: maintains
+    object: rod_shape
+    description: Circumferential sidewall insertion elongates the cylinder and maintains
+      rod-like shape.
+    evidence:
+    - reference: DOI:10.1016/j.cell.2018.02.050
+      notes: Shi, Bratton, Gitai and Huang 2018 describe MreB-driven cell-wall feedback
+        as the self-organizing system for rod shape maintenance.
 discussions:
 - discussion_id: first_minted_identifier
   prompt: This is the corpus's first minted identifier — is the scheme right?
@@ -168,6 +246,14 @@ curation_history:
     cell-shape claim it was attached to. The paper remains cited elsewhere on this
     record, and the three verbatim snippets are unaffected.'
   llm_assisted: true
+- timestamp: '2026-09-04T00:58:09Z'
+  curator: codex
+  action: ADD_CAUSAL_GRAPH
+  changes: Added a FUNCTION graph for MreB/RodZ-guided sidewall synthesis that points
+    at the separate elongasome record, cites the existing MreB shape review and the
+    elongasome's sidewall-synthesis review, and keeps the filament-to-machine relation
+    out of equivalence-only xrefs.
+  llm_assisted: true
 associated_traits:
 - trait_id: METPO:1000681
   trait_label: rod shaped

data/structures/division_machinery/divisome_complex.yaml

@@ -123,6 +123,9 @@ causal_graphs:
   - node_id: ring
     label: FtsZ ring
     node_type: STRUCTURE
+  - node_id: treadmilling
+    label: FtsZ treadmilling
+    node_type: BIOLOGICAL_PROCESS
   - node_id: synthase
     label: FtsW-FtsI septal synthase
     node_type: GENE_OR_PROTEIN
@@ -135,15 +138,27 @@ causal_graphs:
   - subject: tether
     predicate: anchors
     object: ftsz
+    description: FtsA, ZipA or SepF-family membrane tethers attach FtsZ protofilaments
+      to the cytoplasmic membrane at the division site.
     evidence:
     - reference: DOI:10.1146/annurev-biophys-121219-081703
       notes: 'McQuillen & Xiao 2020: FtsA and ZipA hold FtsZ filaments at the membrane.'
   - subject: ftsz
     predicate: assembles into
     object: ring
+    description: Membrane-tethered FtsZ filaments polymerize into the cytokinetic
+      Z ring at midcell.
     evidence:
     - reference: DOI:10.1146/annurev-biophys-121219-081703
       notes: McQuillen & Xiao 2020 describe filament assembly into the Z ring at midcell.
+  - subject: ftsz
+    predicate: treadmills within
+    object: ring
+    description: Dynamic FtsZ filaments treadmill around the circumference of the
+      ring.
+    evidence:
+    - reference: DOI:10.1146/annurev-biophys-121219-081703
+      notes: McQuillen & Xiao 2020 review FtsZ treadmilling around the division site.
   - subject: ring
     predicate: distributes
     object: synthase
@@ -156,6 +171,8 @@ causal_graphs:
   - subject: synthase
     predicate: carries out
     object: septum
+    description: FtsW-FtsI enzymes synthesize the septal peptidoglycan that closes
+      the division plane.
     evidence:
     - reference: DOI:10.1146/annurev-biophys-121219-081703
       notes: 'McQuillen & Xiao 2020: FtsW-FtsI builds the septal peptidoglycan.'
@@ -214,6 +231,12 @@ curation_history:
     vitro EM studies ( 93 , 183 )'' -- inventing reference numbers a reader could
     have chased. `just evidence-verify` refused all four before they could be committed.'
   llm_assisted: true
+- timestamp: '2026-09-04T01:38:58Z'
+  curator: codex
+  action: ENHANCE_CAUSAL_GRAPH
+  changes: Added an explicit FtsZ treadmilling node and descriptions to the divisome
+    graph so its septal-synthase distribution mechanism is fully represented.
+  llm_assisted: true
 - timestamp: '2026-09-03T00:10:07Z'
   curator: claude
   action: CORRECT_UNIT

data/structures/energy_complex/proton_transporting_atp_synthase_complex.yaml

@@ -173,6 +173,8 @@ causal_graphs:
   - subject: pmf
     predicate: drives ion flow through
     object: a
+    description: The proton motive force drives ions through offset half-channels
+      in subunit a at the a/c-ring interface.
     evidence:
     - reference: DOI:10.1146/annurev-biochem-013118-110903
       notes: 'Kuehlbrandt 2019: ions cross via the two offset half-channels in subunit
@@ -189,12 +191,16 @@ causal_graphs:
   - subject: cring
     predicate: rotates
     object: stalk
+    description: Ion-driven rotation of the membrane c-ring carries the attached central
+      stalk as one rotor.
     evidence:
     - reference: DOI:10.1146/annurev-biochem-013118-110903
       notes: 'Kuehlbrandt 2019: the c-ring and central stalk rotate as one rotor.'
   - subject: stalk
     predicate: drives conformational cycling of
     object: head
+    description: The asymmetric rotating central stalk forces catalytic beta subunits
+      in the alpha3beta3 head through sequential conformations.
     evidence:
     - reference: DOI:10.1146/annurev-biochem-013118-110903
       notes: Kuehlbrandt 2019 describes the asymmetric gamma subunit imposing the
@@ -203,13 +209,17 @@ causal_graphs:
     predicate: catalyses formation of
     object: atp
     predicate_id: RO:0002327
+    description: Catalytic nucleotide-binding interfaces in the F1 head synthesize
+      ATP from ADP and phosphate.
     evidence:
     - reference: DOI:10.1146/annurev-biochem-013118-110903
       notes: 'Kuehlbrandt 2019: ATP is synthesised at the catalytic interfaces of
         the head.'
   - subject: head
     predicate: participates in
     object: synthesis
+    description: The F1 head is the catalytic sector of the proton-motive-force-driven
+      ATP synthase.
     evidence:
     - reference: DOI:10.1146/annurev-biochem-013118-110903
       notes: Kuehlbrandt 2019 reviews rotary catalysis as the mechanism of ATP synthesis.
@@ -250,6 +260,12 @@ curation_history:
     and polymer-entity links, and left alternate assembly stoichiometries unflattened
     at RCSB. No molecular render was ingested.
   llm_assisted: true
+- timestamp: '2026-09-04T01:40:08Z'
+  curator: codex
+  action: ENHANCE_CAUSAL_GRAPH
+  changes: Added descriptions to ATP synthase rotary-catalysis edges so every edge
+    states the ion-flow, rotor, or catalytic step it represents.
+  llm_assisted: true
 datasets:
 - accession: PDB:6OQR
   title: E. coli ATP Synthase ADP State 1a