Skip to content

Latest commit

 

History

History
141 lines (98 loc) · 5.88 KB

HANDOVER.md

File metadata and controls

141 lines (98 loc) · 5.88 KB

Handover: 2026-03-03 - Phase A+B Implementation Complete

Branch: main (at 3affdc98) Release: v1.11.0 -- https://github.com/terraphim/terraphim-ai/releases/tag/v1.11.0 CI Status: GREEN (workspace tests all passing locally)

Session Summary

Completed the full Phase A+B implementation plan from .docs/implementation-plan-2026-03-03.md. Seven commits implementing bug fixes (#579, #620, flaky webhook test) and the dynamic ontology CLI epic (#544 with children #545-#548). All GitHub issues commented and closed.

What Was Done

Phase A: Bug Fixes

A1: Fix #579 - CLI Config Loading (commit 1844cec0)

Ported the config loading priority chain from terraphim-agent to terraphim-cli:

  1. --config CLI flag (always loads from JSON, no persistence check)
  2. role_config in settings.toml (bootstrap-then-persistence)
  3. Persistence layer (SQLite)
  4. Embedded defaults (hardcoded roles)

Bootstrap-then-persistence: first run loads JSON and saves to persistence; subsequent runs use persistence so CLI changes stick.

A2: Fix Flaky Webhook Test (commit 45855954)

Replaced per-request Settings::from_env() with Salvo Depot injection. Added SettingsInjector middleware that injects Settings into the Depot. Tests use test_router() helper with deterministic settings via create_test_settings().

A3: Fix #620 - Signature Verification (commit 43779452)

Downgraded MissingSignature from hard error to warning. Self-update now proceeds when archives are unsigned. Verification still runs when signatures exist.

Phase B: Dynamic Ontology CLI (Epic #544)

B1: OntologySchema Types - #547 (commit ab4f2848)

Added to terraphim_types:

  • OntologyEntityType -- entity type with id, label, uri_prefix, aliases, category
  • OntologyRelationshipType -- typed relationship between entity types
  • OntologyAntiPattern -- anti-pattern indicators for governance
  • OntologySchema -- top-level container with load_from_file(), to_thesaurus_entries(), category_ids(), uri_for()

Test fixture: crates/terraphim_types/test-fixtures/sample_ontology_schema.json

B2: Extract with Grounding - #548 (commit 65d25f3f)

Added extract command to terraphim-cli with --json flag:

terraphim extract "text to analyze" --role "System Operator" --json

Returns ExtractedEntity list with GroundingMetadata (URI, label, provenance, confidence, normalization method).

B3: Schema-Based Extraction - #545 (commit 824accb4)

Added --schema flag to extract command:

terraphim extract "text" --schema domain-model.json --json

Builds temporary thesaurus from OntologySchema entity types + aliases, runs Aho-Corasick matching, returns SchemaSignal with typed entities and confidence.

B4: Coverage Subcommand - #546 (commit 3affdc98)

Added coverage subcommand for ontology governance:

terraphim coverage "text" --schema schema.json --threshold 0.7 --json

Computes coverage ratio of schema entity types matched in text. Exits with code 1 when coverage < threshold for CI gate integration.

Commits This Session

Commit Description
1844cec0 fix(cli): port config loading priority chain from agent to CLI (#579)
45855954 fix(webhook): inject Settings via Depot instead of per-request env lookup
43779452 fix(update): downgrade missing signature from error to warning (#620)
ab4f2848 feat(types): add OntologySchema types for schema-first extraction (#547)
65d25f3f feat(cli): add extract command with grounding metadata (#548)
824accb4 feat(cli): add --schema flag for schema-based extraction (#545)
3affdc98 feat(cli): add coverage subcommand for ontology governance (#546)

GitHub Issues Updated

Issue Title Status
#544 Epic: Dynamic ontology CLI Closed
#545 CLI extract --schema outputs SchemaSignal Closed
#546 CLI coverage --schema --threshold --json Closed
#547 Define ontology schema file format Closed
#548 CLI extract includes GroundingMetadata Closed
#579 CLI config loading priority chain Closed (was already closed)
#620 Signature verification error Closed (was already closed)

Current State

Branch: main
HEAD:   3affdc98 feat(cli): add coverage subcommand for ontology governance (#546)
Working tree: clean (after committing HANDOVER.md and lessons-learned.md)
Tests: All passing (workspace --exclude terraphim_agent)

Files Modified

File Change
crates/terraphim_cli/src/service.rs Added extract_with_grounding, extract_with_schema, build_thesaurus_from_schema, calculate_coverage, CoverageResult
crates/terraphim_cli/src/main.rs Added Extract and Coverage commands, handle_extract, handle_coverage
crates/terraphim_types/src/lib.rs Added OntologyEntityType, OntologyRelationshipType, OntologyAntiPattern, OntologySchema
crates/terraphim_types/test-fixtures/sample_ontology_schema.json New test fixture
crates/terraphim_github_runner_server/src/main.rs SettingsInjector middleware, Depot-based settings
crates/terraphim_update/src/lib.rs Downgraded MissingSignature to warning

Blockers and Known Issues

  1. Docker root-owned files: Docker builds leave root-owned files in target/. Current fix is sudo chown before checkout. Cleaner fix would be --user $(id -u):$(id -g).

  2. Bulmaswatch assets in git: ~4MB of CSS themes tracked in git. Acceptable for now.

Next Steps (Recommended Priority)

  1. Phase 4: Verification -- Run disciplined-verification skill to verify implementation against design
  2. Release v1.12.0 -- Tag and release with new CLI commands
  3. Investigate Docker --user flag -- Avoid root-owned files
  4. Implement #566 -- Cross-compile Windows binaries with cargo-xwin
  5. Implement #560 -- TinyClaw: agent spawning via terraphim_spawner