Skip to content

local-development-workflow.md

Latest commit

 

History

History
289 lines (227 loc) · 7.34 KB

local-development-workflow.md

File metadata and controls

289 lines (227 loc) · 7.34 KB
Raw

Local Development Workflow for ACR-reasoner

1. Purpose

This workflow defines how ACR-reasoner should be developed locally using GitHub Desktop and then synchronised with the online GitHub repository. It is designed to keep reasoning-engine work separate from ACR-platform, while still supporting controlled promotion of validated changes into the working ACRAgent demo platform.

2. Core Principle

ACR-reasoner is the source of truth for:

  • ontology assets
  • SWRL rules
  • SQWRL queries
  • Bayesian enhancement
  • CDS schemas
  • Bayesian test harness
  • interim acr_pathway bridge logic

ACR-platform remains the demo platform and web application.

Reasoning logic should be developed and validated in ACR-reasoner first, then selectively integrated into ACR-platform.

3. Local Tools

Recommended local toolchain:

  • GitHub Desktop
  • VS Code or another code editor
  • local terminal
  • browser developer tools
  • DB Browser for SQLite where relevant
  • local PHP server when testing integration with the platform
  • optional Node or Python tooling for scripts and validation

4. Initial Setup

Step 1

Create the GitHub repository:

  • KY-BChain/ACR-reasoner

Step 2

Clone it locally using GitHub Desktop.

Step 3

Create the agreed folder structure.

Step 4

Import the baseline files:

  • SWRL and SQWRL assets
  • Bayes engine files
  • Bayesian test harness files
  • CDS schemas
  • current acr_pathway.html
  • Bayes-modified acr_pathway_bayes_modified.html
  • mapping and notes files

Step 5

Commit the initial repository baseline and push it.

5. Branch Model

Recommended branches:

  • main — stable, validated reasoning assets
  • develop — active integration and pre-release work
  • feature branches for focused changes

Examples:

  • feature/import-current-assets
  • feature/bayes-engine
  • feature/cds-schema
  • feature/pathway-bridge
  • feature/harness-ui
  • feature/swrl-coverage

6. Daily Working Cycle

6.1 Start of day

  1. Open GitHub Desktop.
  2. Select ACR-reasoner.
  3. Pull latest changes.
  4. Switch to the correct branch or create a new feature branch.

6.2 Make changes

Edit only the files relevant to the workstream:

  • ontology updates in ontology/
  • Bayesian logic in bayes/
  • harness changes in harness/
  • interim pathway bridge changes in integration/
  • documentation in docs/

6.3 Validate locally

Before committing, run the relevant local checks:

  • JSON syntax validation
  • schema validation
  • Bayes calculation checks
  • harness case execution
  • coverage table updates
  • pathway before/after inspection where applicable

6.4 Review changes

Use GitHub Desktop to inspect diffs before committing.

6.5 Commit

Use focused commit messages.

Examples:

  • Add posterior regression cases for Luminal B and HER2-positive cohorts
  • Revise Bayes-aware CDS schema
  • Map SWRL rules 11-16 into coverage table
  • Add Bayes ON/OFF harness UI layout

6.6 Push

Push the feature branch to GitHub.

6.7 Merge

After local validation, merge feature branches into develop. Only merge develop into main when the changes are stable and validated.

7. Workstreams

7.1 Ontology and rules workstream

Used for:

  • SWRL revisions
  • SQWRL revisions
  • native rule and query files
  • language variants
  • ontology rationale documentation

Process:

  1. update rule/query assets
  2. update JSON mirrors if required
  3. update rule/query rationale
  4. update coverage files
  5. run harness cases affected by the change
  6. commit and push

7.2 Bayesian workstream

Used for:

  • priors
  • likelihood ratios
  • evidence mapping
  • posterior calculation logic
  • Bayes debug outputs

Process:

  1. edit Bayes config or code
  2. run Bayes unit checks
  3. run representative posterior regression cases
  4. verify expected output ranges
  5. update schema if output changed
  6. commit and push

7.3 Harness workstream

Used for:

  • case library
  • before/after comparison cases
  • pass/fail reporting
  • coverage matrices
  • harness UI

Process:

  1. add or revise case
  2. map to intended SWRL/SQWRL coverage
  3. define expected deterministic result
  4. define expected Bayes posterior range
  5. run harness
  6. review pass/fail status
  7. commit and push

7.4 Pathway bridge workstream

Used for:

  • interim acr_pathway logic
  • Bayes integration bridge
  • CDS schema adapter
  • packaging notes for ACR-platform

Process:

  1. update integration/acr_pathway/
  2. keep baseline and Bayes-modified copies
  3. document what is mirrored from ontology
  4. document what remains unimplemented
  5. validate against harness cases
  6. prepare integration bundle if ready

8. Validation Levels

Every meaningful change should pass these four levels.

Level 1 — Syntax and structure

Check:

  • valid JSON
  • valid schema structure
  • correct file references
  • no broken paths

Level 2 — Unit validation

Check:

  • Bayes math correctness
  • evidence mapper correctness
  • schema validation

Level 3 — Harness validation

Check:

  • deterministic result matches expectation
  • Bayes posterior lies within expected tolerance
  • explanation trace is present
  • pass/fail output is intelligible

Level 4 — Integration validation

Check:

  • interim acr_pathway files still behave correctly
  • export bundle for ACR-platform is coherent
  • local platform integration does not introduce regressions

9. Integration with ACR-platform

ACR-reasoner should not directly become the live demo platform.

Promotion path:

  1. finalise reasoning changes in ACR-reasoner
  2. validate locally
  3. prepare an integration bundle
  4. open the local working copy of ACR-platform
  5. replace only intended files
  6. run local platform regression tests
  7. only then promote to the hosted demo environment

10. Local Integration Test Procedure

When testing reasoning changes inside the local ACR-platform working copy:

  1. take a backup snapshot of the local platform tree
  2. copy only the required files from ACR-reasoner
  3. run the local PHP server from the platform root
  4. test:
    • index.html
    • acr_pathway.html
    • acr_test_data.html
    • login/auth flow
    • control panel
    • relevant API endpoints
  5. inspect browser console and network output
  6. confirm no regression before any hosted update

11. GitHub Desktop Operating Rules

  • always pull before starting work
  • keep commits small and focused
  • do not mix ontology changes, Bayes changes, and platform-bridge changes in one large commit if avoidable
  • write meaningful commit messages
  • push feature branches frequently
  • merge only after local pass

12. Documentation Rule

Every non-trivial change should also update at least one of:

  • mapping documentation
  • coverage files
  • validation notes
  • schema notes
  • release or integration notes

13. Practical Rule

Nothing should move from ACR-reasoner into ACR-platform unless it is:

  • versioned
  • documented
  • locally tested
  • reversible

14. Recommended First Commits

  1. Initial repository structure for ACR-reasoner
  2. Import current SWRL and SQWRL assets
  3. Import Bayes engine and CDS schemas
  4. Add acr_pathway baseline and Bayes-modified files
  5. Add rule/query coverage and validation documents
  6. Add local development and release workflow

15. End State

A healthy local development cycle means:

  • ACR-reasoner remains the reasoning-engine source of truth
  • ACR-platform remains the demo platform
  • integration is controlled
  • the hosted demo platform is updated only from validated local releases