Skip to content

Changelog

All notable changes to Mistaber are documented here.

Format based on Keep a Changelog, with a Formal Specification Changes section tracking modifications to the formal model and semantics.

This project adheres to Semantic Versioning.

[Unreleased]

Summary

DSL-first architecture, security hardening, and open-source publication readiness. dsl/ is now the sole source of truth for all ontology content. A 4-stage HLL compiler (parse → normalize → type-check → emit) compiles .hll source files into .lp output in ontology/. The predicate registry (base.yaml) is auto-generated from @declare, @sort, and @enum directives — never edited manually. Enriched Kripke semantics add provenance tracking (holds_via/3), endorsement modes, and world metadata. A comprehensive security audit addressed 26 findings across the dashboard backend and frontend. Directive enforcement, encoding decision framework, and dashboard improvements round out the release.

Added

  • HLL compiler pipeline rewrite — 4-stage compilation with 15+ directives
  • grammar.lark extended with @sort, @subsort, @declare, @enum, @world_def, @endorses, @interprets, @interpretation, @show, @encoding_note, @constraint, @makor, @madrega, @rule, @world
  • Arithmetic expressions and #count/#max/#min/#sum aggregates
  • Compiler stages: parser.py, normalizer.py, type_checker.py, emitter.py
  • Warnings-first type checker (undeclared predicates, arity mismatches, invalid enums, missing @makor → warnings; structural errors → hard errors)
  • Contextual error messages in HLL parser with line/column info
  • Auto-generated headers in compiled .lp files with source provenance
  • Build pipeline (dsl/build.py)
  • BuildManifest: collects directives across .hll files with provenance
  • YAMLMerger: merges manifest into base.yaml atomically
  • .lp passthrough for asprin syntax (preferences.lp) with naming conflict detection
  • LAYER_ORDER: schema → base → worlds → engine → interpretations → corpus
  • Normalized source_file paths in base.yaml to repo root
  • Enriched Kripke semantics
  • holds_via/3 (asserted/endorsed/inherited modes)
  • holding_strength/3, inheritance_source/3
  • @endorses directive for independent affirmation vs mere inheritance
  • @world_def with era, endorsement_mode metadata
  • Full ontology migration to .hll (27 .hll + 1 .lp passthrough)
  • schema/ (3): sorts, constraints, disjointness
  • base/ (7): context, issur_types, madrega, shiur, status, substance, temporal
  • worlds/ (9): base, mechaber, rema, gra, ashk_ah, ashk_mb, sefardi_yo, kripke_rules
  • engine/ (4+1): safek, priorities, interpretations, policy + preferences.lp
  • interpretations/ (2): shach, taz
  • corpus/ (3): yd_87/base, yd_89/base, yd_89/seif_1
  • Dashboard improvements
  • World node visualization: purple hexagon world nodes, directed accessible edges, tooltips, sidebar detail panel
  • Predicate/World/Enum filter toggles in ontology sidebar
  • .hll scenario file support in test runner with @show filtering and xclingo derivation traces
  • Full worktree tree in file explorer with .hll support
  • GraphQL file tree query deepened to 5 levels
  • HLL test files visible in tests sidebar panel
  • xclingo explain wired to GraphQL and ProofView
  • Terminal session persistence
  • PTY processes survive browser refresh and session switches (no more --resume needed)
  • Concurrent tab guard: second tab evicts the first with close code 4009
  • Jiggle resize on PTY reattach forces Claude TUI redraw
  • Terminal tab shows active session name (e.g., "Terminal: test1")
  • Session manual controls (Sync, Publish, Commit, Merge, Delete)
  • 5 GraphQL mutations for session lifecycle operations
  • Git service functions: sync, push, commit+push, merge into main, delete remote branch
  • Action bar in SessionHeader with loading states and confirmation dialogs
  • Delete cleans up PTY, worktree, remote branch, and DB records
  • All operations add notes to session state for agent discoverability
  • Session infrastructure
  • Worktree restoration from remote branches on container rebuild
  • Deterministic Claude session ID assignment (no more polling)
  • Orphan cleanup at startup: restore-first strategy prevents data loss
  • GitHub CLI added to backend container for git operations
  • Pre-deploy drain and GITHUB_TOKEN in CI/CD pipeline
  • Monaco editor: HLL syntax highlighting
  • Custom hll language with Monarch tokenizer extending clingo/ASP
  • 15 @directive keywords highlighted as bold magenta annotations
  • Custom vs-dark-hll theme with token-level color rules
  • Bracket highlighting for [enum, values] in gold
  • Encoding decision framework (paper Section 4.7)
  • Four mandatory decision types: event identification, feature selection, category assignment, boundary cases
  • Structured YAML artifact (encoding-decisions-YD-{siman}-{seif}.yaml) with alternatives, confidence, practical impact
  • Inline HLL cross-references via @encoding_note("ED-{siman}-{seif}-{NNN}: ...")
  • Phase enforcement: decisions elicited in corpus-prep, cross-referenced in hll-encode, verified in validate, audited in review
  • Directive enforcement across skills
  • Vocabulary completeness check in validate skill (validate-hll.py)
  • Directive enforcement in hll-encode, review, and orchestrator skills
  • Directive usage added to all encoding patterns in CLAUDE.md
  • @declare/@encoding_note added to yd_87/base.hll corpus
  • safe_negation mechanism for OWA predicates
  • New safe_negation field in @declare and Predicate dataclass
  • is_unsafe_owa_negation() registry method — suppresses type checker warning for OWA predicates where negation-as-failure is architecturally intentional
  • Applied to asserts, endorses, priority, madrega_of_safek, sfek_sfeika_strict, used_with_davar_charif
  • Security hardening (26 findings across 3 audit rounds):
  • Enforce JWT_SECRET_KEY env var with minimum length, remove hardcoded default
  • Require authentication on all GraphQL endpoints and shared terminal WebSocket
  • Prevent command injection in terminal manager via shell metacharacter rejection
  • Prevent path traversal via symlink rejection and is_relative_to() checks
  • Validate filenames, branch names, and checkpoint status transitions
  • Add input validation for ASP query patterns (reject shell metacharacters)
  • Harden rate limiting with proper IP detection, tighter limits, and full API coverage
  • Add security headers middleware (X-Content-Type-Options, X-Frame-Options, CSP) and lock down CORS
  • Disable unauthenticated GraphQL introspection in production
  • Escape D3 tooltip content and sanitize mermaid SVG output with DOMPurify to prevent XSS
  • Prevent DB_ECHO in production PostgreSQL
  • Pin all backend dependencies to exact versions
  • SECURITY.md — responsible disclosure policy with scope and reporting process
  • Paper updates
  • Rev2 (Deleuzian lens) and Rev3 (Asher commentary) patches applied
  • arXiv submission preparation
  • Skills & documentation updates
  • using-mistaber: DSL-first workflow section, directive reference, "never write to ontology/" rule
  • hll-encode: 8-phase encoding guide, directive selection decision tree
  • hll-syntax.md: complete 361-line directive reference for all 15 directives
  • validate/commit: updated for dsl/ → ontology/ pipeline
  • CLAUDE.md: DSL-first rules, ontology-guard hook documentation, engine loading scope, API method signatures, .hll test file patterns
  • Coverage pipeline aligned with commit skill spec
  • Full build pipeline documented in compiler-pipeline architecture

Changed

  • ontology/ is now 100% generated output — never edited directly
  • base.yaml predicate registry is auto-generated from @declare/@sort/@enum directives
  • ontology-guard hook blocks direct writes to ontology/
  • Build pipeline regenerates meta.lp from base.yaml on every build
  • README.md simplified and professionalized for open-source audiences
  • Plugin README license corrected from MIT to Apache-2.0
  • @rule/@makor/@madrega changed to block-scoped semantics with encoding guard enforcement
  • @show directive syntax corrected to @show(pred/arity) per HLL grammar
  • Stub/TODO scanner (test_production_gaps.py) expanded to cover marketplace/plugins/
  • Validation runner (run-validation.py) replaced fabricated placeholder results with real test execution
  • WORKTREE_PATH env var exported to session agent
  • CLAUDE.md copied into backend Docker container

Fixed

  • DSL build warnings — eliminated all 407 type checker warnings across 25 HLL files
  • Fixed predicate arity declarations (forbidden/permitted 1→4, ratio 3→2, enum predicates 2→1)
  • Fixed enum values (policy_type, policy_value, status_type, safek_resolution, bishul_manner)
  • Added missing infrastructure declarations (world, asserts, holds, rule, scope, etc.)
  • Removed idempotent @sort re-declaration warnings from type checker
  • Fixed safek_policy signature across 5 world files
  • Fixed makor and madrega sort references
  • DSL compiler fixes
  • Added missing @declare directives and linked enums in ontology graph
  • Removed stale sorts from registry
  • Used ASCII dashes in auto-generated .lp headers (Unicode compatibility)
  • Removed extraneous f-string prefix in parser error message
  • Dashboard fixes
  • Removed file tree depth limits and fixed all test failures
  • World nodes emitted correctly in ontology graph visualization
  • All mypy type errors resolved across backend
  • All ESLint errors and prettier formatting fixed across frontend
  • Prettier formatting fixed in ForceGraph.tsx
  • Terminal & session fixes
  • Claude TUI blank on session switch (jiggle resize forces ink renderer redraw)
  • "No conversation found" on browser refresh (PTY persistence replaces kill+resume)
  • Docker worktree volume mount ownership (/app/.worktrees)
  • Git identity set before clone/init to prevent fallback failure
  • Engine fixes
  • corpus/ directory loaded in MistaberEngine (was previously skipped)
  • Dependency security
  • Resolved all Dependabot security alerts
  • Removed dead subscriptions module and placeholder subscription stubs
  • CI/CD fixes
  • Deploy workflow uses GH_DEPLOY_TOKEN PAT instead of runner-scoped GITHUB_TOKEN
  • GraphQL resolver tests set dummy JWT_SECRET_KEY to prevent import-time crash
  • All ruff lint/format and mypy type errors resolved

Formal Specification Changes

  • Enriched Provenance Tracking:
  • holds_via(Prop, World, Mode) where Mode ∈ {asserted, endorsed, inherited}
  • holding_strength(Prop, World, Strength) for graduated belief

  • inheritance_source(Prop, World, SourceWorld) for provenance chains

  • Endorsement Semantics:

  • @endorses(World, Atom) → asserts(World, Atom) with holds_via(Atom, World, endorsed)
  • Distinguished from inheritance: endorsed propositions are independently affirmed

  • Enables tracking whether an authority actively holds a position vs passively inherits it

  • World Metadata:

  • world_era(World, Era) — temporal period (e.g., rishonim, acharonim)
  • world_endorsement_mode(World, Mode) — how the authority typically adopts positions

  • world_aware_of(World, OtherWorld) — epistemic accessibility (who knows of whom)

  • Safe Negation Waiver:

  • safe_negation=true on @declare marks OWA predicates where not pred(...) is architecturally safe
  • Does not change CWA/OWA semantics — only suppresses the type checker warning

  • Requires documented justification per predicate

  • Block-Scoped Rule Metadata:

  • @rule/@makor/@madrega are now block-scoped — each @rule opens a new metadata context
  • Multiple rule blocks per file supported
  • Orphan @makor/@madrega without preceding @rule generates warning

[0.4.0] - 2026-02-07

Summary

Dashboard MVP milestone. The browser-based IDE at ide.mistaber.ai is live with full encoding workflow, ontology visualization, and Claude Code integration. Documentation moved to docs.mistaber.ai.

This release consolidates the v0.3.2–v0.3.4 work into a minor version bump reflecting the scope of changes: a complete web IDE, Docker deployment pipeline, CI/CD automation, and self-hosted documentation.

Added

  • Documentation site deployed to docs.mistaber.ai (moved from GitHub Pages)
  • MkDocs builds via GitHub Actions and rsyncs to droplet
  • DNS, nginx, and Let's Encrypt SSL configured
  • All CI checks passing (lint, format, type-check, tests across Python 3.10–3.12)

Changed

  • site_url updated from brainyblaze.github.io/mistraber/ to docs.mistaber.ai
  • Docs workflow deploys via SSH/rsync instead of mkdocs gh-deploy
  • Deleted gh-pages branch

Fixed

  • 84 ruff lint errors (unused imports, import sorting, trailing whitespace)
  • 62 files reformatted to pass ruff 0.15.0 format check
  • 13 mypy type-check errors (stale type ignores, missing annotations)
  • CI test job now installs dashboard backend dependencies
  • Broken link in contributing docs (CODE_OF_CONDUCT.md → code-of-conduct.md)

[0.3.4] - 2026-02-06

Added

  • DigitalOcean droplet provisioning (mistaber-ide, fra1, 4 vCPU / 8 GB)
  • DNS A record: ide.mistaber.ai → droplet IP
  • SSL/TLS via Let's Encrypt with automatic renewal (certbot)
  • Host-level nginx reverse proxy with WebSocket support (24h timeout)
  • UFW firewall (SSH + Nginx only)
  • GitHub Actions CI/CD pipeline (.github/workflows/deploy.yml)
  • Automatic deployment on push to main (path-filtered)
  • Manual deployment via workflow_dispatch
  • SCP-based .env upload from GitHub Secrets
  • SSH-based docker compose up --build with health check
  • Concurrency control (single deploy at a time)
  • Startup cleanup of orphaned sessions (worktree path validation)
  • Frontend stale session state clearing on reload

Changed

  • Removed tmux from terminal architecture — direct shell mode (USE_TMUX=0)
  • Fixes mouse/keyboard input conflicts between tmux and xterm.js
  • Claude CLI sessions spawn directly via PTY
  • Docker Compose frontend port changed from 80:80 to 3000:80 (host nginx uses port 80)
  • MCP servers configured with --scope user for global availability across worktrees
  • Entrypoint installs mistaber-skills plugin from local marketplace

Fixed

  • Terminal scroll and input broken when tmux mouse mode enabled
  • Claude CLI not auto-launching in terminal sessions (direct shell mode)
  • Shell crashing when worktree path doesn't exist (fallback to /app)
  • MCP servers not available in worktree-based Claude sessions
  • Stale activeSessionId in localStorage causing phantom terminal connections

[0.3.3] - 2026-02-05

Added

  • Docker deployment for DigitalOcean droplet with managed Postgres
  • Multi-stage frontend Dockerfile (Node build → Nginx reverse proxy)
  • Backend Dockerfile with full encoding toolchain (clingo, asprin, xclingo, tmux, Claude Code CLI)
  • Docker Compose orchestration (frontend + backend, external managed DB)
  • Nginx reverse proxy for GraphQL, WebSocket, REST API, and SPA fallback
  • Entrypoint with Claude Code shared subscription auth (claude setup-token)
  • Alembic migrations run automatically at container startup
  • Environment-driven configuration
  • DATABASE_URL with automatic scheme normalization (postgresql → asyncpg)
  • CORS_ORIGINS for configurable CORS policy
  • JWT_SECRET_KEY for production token signing
  • CLAUDE_TOKEN for shared Claude Code subscription
  • .env.example template for deployment configuration

Fixed

  • DateTime columns now use timezone=True for Postgres compatibility
  • Frontend URLs derive from window.location.origin instead of hardcoded localhost
  • WebSocket terminal connects through nginx proxy in containerized deployments
  • File explorer and tests panel resolve REPO_ROOT via MISTABER_ONTOLOGY env var in Docker
  • Makefile dev target points to correct backend/ path and port 8001

[0.3.2] - 2026-02-05

Added

  • Mistaber Dashboard IDE — browser-based encoding workbench at ide.mistaber.ai
  • VS Code-like layout with Activity Bar, resizable panels, and tabbed editor
  • Session management with 5-phase workflow tracking and phase timeline
  • Ontology visualizer — interactive force-directed graph (D3.js) with domain filtering, search, hover highlighting, and SVG export
  • Coverage dashboard with seif-level heatmap, quality metrics, and 30-day activity timeline
  • Integrated terminal backed by tmux — per-session worktrees, Claude Code agent, persistent across refreshes
  • Query executor for running ASP queries with results display
  • Four validation views: Proof (derivation tree), Narrative, Side-by-Side, and Diff
  • Monaco code editor with Clingo/LP syntax highlighting
  • Command palette (Ctrl+K) and keyboard shortcuts for fast navigation
  • GraphQL API (Strawberry/FastAPI) with 20+ query fields and real-time subscriptions
  • SQLAlchemy database for session state, checkpoints, source chains, and notes
  • JWT authentication
  • Standalone dashboard user guide for encoders (16 documentation files at docs/dashboard/)
  • Sessions, ontology, encoding, coverage, tools, and UI glossary walkthroughs
  • Written for halachic scholars, not developers

[0.3.1] - 2026-01-25

Added

  • mistaber-skills Claude Code plugin for AI-assisted halacha encoding
  • 5-phase encoding workflow: Corpus Prep → HLL Encode → Validate → Review → Commit
  • Human supervision checkpoints at every phase transition
  • Sefaria MCP integration for text corpora access
  • Skills:
    • corpus-prep - Fetch and analyze sources from Sefaria, build derivation chains
    • hll-encode - Transform halachic statements to formal HLL rules
    • validate - ASP compilation, behavioral tests, semantic validation
    • review - Generate review packages for human approval
    • commit - Archive session artifacts and finalize commits
  • Hooks:
    • session-init - Initialize encoding session state
    • phase-gate - Enforce phase transition requirements
    • encoding-guard - Validate HLL syntax before writes
    • sefaria-logger - Log all Sefaria API interactions
    • validation-handler - Run validation on encoding changes
    • checkpoint-enforcement - Require human approval at checkpoints
    • git-commit-guard - Enforce commit message conventions
  • Agents:
    • encoding-orchestrator - Multi-seif encoding coordination
  • Comprehensive documentation site with MkDocs Material
  • Navigation tabs for top-level sections
  • Encoding tutorials and guidelines
  • Plugin documentation with skills, hooks, and agents reference
  • Formal foundations (modal logic, deontic logic, Kripke semantics)

[0.3.0] - 2026-01-21

Added

  • Apache 2.0 open source license
  • pyproject.toml for modern Python packaging
  • CONTRIBUTING.md with development setup guide
  • CODE_OF_CONDUCT.md (community standards)
  • GitHub Actions CI workflow (lint, type-check, test)
  • GitHub issue and PR templates

Changed

  • Renamed package from core to mistaber for PyPI distribution
  • CLI command changed from hsrs to mistaber
  • Updated all documentation with new package name and paths

Fixed

  • Float positioning for all tables and figures in paper

[0.2.0] - 2026-01-19

Added

  • Complete 7-world Kripke DAG with 3-tier inheritance hierarchy
  • Tier 1: base (common halachic ground)
  • Tier 2: mechaber, rema, gra (primary authorities)
  • Tier 3: ashk_mb, ashk_ah, sefardi_yo (modern authorities)
  • Shach and Taz interpretation layers with formal modification predicates
  • adds_condition/3 - adds preconditions to rules
  • removes_condition/3 - removes conditions from rules
  • expands_scope/3 - extends rule applicability
  • Engine API methods:
  • configure() - runtime configuration for world, safek policy, interpretation precedence
  • ask() - boolean queries with policy-aware resolution
  • query_with_completeness() - OWA-aware queries with missing fact detection
  • query_preferred() - asprin-based preference optimization
  • CLI commands:
  • query - query for atoms matching a pattern
  • compare - compare query results across multiple worlds
  • analyze - analyze a scenario (push mode)
  • explain - generate derivation tree explanations
  • machloket - detect disputes between authorities
  • Completeness checking with MissingFact detection for OWA predicates
  • XClingo-based explanation engine with derivation tree generation
  • Kripke validation module for world graph integrity checks
  • Production-grade safek calculus with:
  • safek/5 propagation through derivation chains
  • sfek_sfeika/4 double-doubt handling
  • World-level safek_policy/3 configuration
  • Machloket detection module for cross-world dispute analysis
  • YD 87 (basar bechalav) corpus with complete ruling encodings

Changed

  • Engine initialization now loads interpretation layer rules automatically
  • World files include corpus imports via #include directives
  • Safek resolution respects world-specific policies

Formal Specification Changes

  • Kripke Frame Properties:
  • Non-reflexive: not (w R w) for all worlds
  • Transitive: accessible_transitive/2 computed via closure

  • Antisymmetric: no cycles in world DAG (except via base)

  • Truth Propagation Semantics: 

    holds(Prop, W) :- asserts(W, Prop), world(W).
holds(Prop, W_child) :- accessible(W_child, W_parent),
                        holds(Prop, W_parent),
                        not overridden(Prop, W_child).

  • Override Mechanism: 

    overridden(Prop, W) :- override(W, Prop, _).

  • Interpretation Layer Predicates:

  • adds_condition(Commentator, RuleID, Condition) - rule fires only if Condition holds
  • removes_condition(Commentator, RuleID, Condition) - condition no longer required

  • expands_scope(Commentator, RuleID, Extension) - extends rule applicability

  • Interpretation Precedence:

  • Configured via interpretation_precedence list in EngineConfig
  • Higher index in list wins on conflict

  • Default: ["shach", "taz"]

  • Safek Policies:

  • World-level: safek_policy(W, MadregaLevel, Resolution)
  • Resolution values: l_chumra (stringent), l_kula (lenient)

  • Default: safek_policy(base, d_oraita, l_chumra), safek_policy(base, d_rabanan, l_kula)

  • Madrega Ordering (unchanged from 0.1.0): 

    d_oraita > d_rabanan > minhag > chumra

Fixed

  • Proper inheritance of safek policies through world DAG
  • Override semantics correctly block inherited propositions
  • Interpretation modifications correctly compose with base rules

[0.1.0] - 2026-01-15

Added

  • HLL (Halachic Logic Language) compiler pipeline
  • Lark-based parser with custom grammar
  • Normalizer for surface syntax expansion
  • Type checker with predicate registry validation
  • ASP code emitter
  • Predicate registry specification
  • 69 predicates across multiple domains
  • 29 sorts (types)
  • 12 enumeration categories
  • CWA/OWA classification per predicate
  • Base ontology schema
  • sorts.lp - sort declarations
  • constraints.lp - integrity constraints
  • disjointness.lp - mutual exclusivity rules
  • Base ontology files
  • substance.lp - food and material properties
  • madrega.lp - normative level hierarchy
  • issur_types.lp - prohibition categories
  • status.lp - status modalities
  • shiur.lp - halachic measurements
  • temporal.lp - time-based reasoning
  • context.lp - normative contexts
  • DSL builtins
  • temporal.lp - time predicates
  • measures.lp - measurement predicates
  • bitul.lp - nullification rules
  • Initial world files
  • base.lp - common ground
  • mechaber.lp - Shulchan Aruch author (Sefardi)
  • rema.lp - Ashkenazi glosses

Formal Specification Changes

  • Initial Formal Model Established:
  • Kripke frame <W, R> where W = set of worlds, R = accessibility relation
  • world/1 declares world membership

  • accessible/2 declares accessibility (inheritance) relation

  • Sort System:

  • Two primary domains: Physical, Normative
  • Physical: food, mixture, vessel, time_point
  • Normative: action, issur_type, madrega, context

  • Subsort relations encoded in schema

  • CWA/OWA Classification:

  • CWA predicates: is_food/1, food_type/2, mixture/1, contains/2

  • OWA predicates: forbidden/4, permitted/4, safek/5

  • Madrega Ordering:

  • Total order: d_oraita > d_rabanan > minhag > chumra
  • Encoded via stronger/2 predicate

  • Transitive closure: stronger_transitive/2

  • Context Hierarchy:

  • ctx_normal (default, most strict)
  • ctx_hefsed (financial loss)
  • ctx_shaat_hadchak (pressing circumstances, most lenient)

  • Monotonic leniency: permitted in strict context -> permitted in lenient

  • Source Attribution Requirement:

  • All normative rules require @makor directive
  • Encodes source citations as makor(RuleID, Source) facts
  • Source types: sa/1, rambam/1, tur/1, gemara/1, rema/1, taz/1, shach/1

Version History Summary

Version Date Highlights
0.4.0 2026-02-07 Dashboard MVP milestone — IDE live, docs site, all CI green
0.3.4 2026-02-06 DigitalOcean deployment, SSL, CI/CD pipeline, terminal fixes
0.3.3 2026-02-05 Docker containerization, managed Postgres, environment config
0.3.2 2026-02-05 Dashboard IDE, ontology visualizer, coverage heatmap, user guide
0.3.1 2026-01-25 mistaber-skills Claude Code plugin, documentation site
0.3.0 2026-01-21 OSS release, Apache 2.0, pyproject.toml, CI/CD
0.2.0 2026-01-19 Kripke gaps, interpretation layer, CLI, 7 worlds
0.1.0 2026-01-15 HLL compiler, predicate registry, base ontology