Hiro development journal

Hiro reactivated with a documentation-only system knowledge base

2026.08.26 at 11:43:16 America/Los_Angeles Knowledge base complete and validated; Hiro online; findings documented but not repaired Machine-readable JSON

Executive summary

Reactivated Hiro with the checked hidden launcher, confirmed that its local model dependency connected, and verified that the API, benchmark, and audit listeners were healthy.

Reviewed the entire tracked Hiro project structurally and traced the currently active conversation, improvement-queue, candidate, promotion, activation, and probation paths at revision 1cb3ac00422ee9e648e25628f92b2dc0da38dc6e.

Created a human-readable system knowledge base, a machine-readable companion index, and a focused consistency test. These are the only Hiro repository changes made in this session.

Recorded evidence-backed problems and future repair gates without changing any runtime, queue, promotion, probation, model, or product behavior. This respected the owner's explicit instruction to write the knowledge base only.

Ran the focused knowledge-base tests and the complete repository test suite, fast-forwarded the documentation-only revision into the clean live checkout, restarted Hiro, and verified that the loaded and checked-out revision both equal 30981196d70b9f421e6c1dd0866130a445f62680.

Work completed

Controlled reactivation and runtime identity

Completed

Started Hiro through the checked launch helper that preserves the inherited runtime environment and normalizes the Windows search path before child-process creation.
Verified that ports 8000, 8001, and 8765 are owned by one expected Hiro process and that the health endpoint reports status ok with the configured Qwen model connected.
After integrating the documentation-only revision, restarted Hiro and confirmed that loaded_revision, checkout_revision, and the Git revision all match 30981196d70b9f421e6c1dd0866130a445f62680.

Whole-project structural review

Completed

Inventoried 498 tracked files, including 378 Python files totaling 87,876 lines, and parsed the Python source into 502,058 syntax-tree nodes containing 3,152 functions.
Compiled the complete Python tree successfully; one existing non-fatal documentation-string escape warning was observed in a migration script.
Traced the currently active request path from the main service through the API, lab scheduler, active improvement loop, continuous engine, promotion transaction, activation broker, and eight-hour probation path.
Separated the current continuous-improvement implementation from historical Stage 6, Daylab, Nightlab, and earlier promotion terminology so future diagnosis does not confuse inactive concepts with live control paths.
Cataloged exception-handling, direct-test-coverage, complexity, and unreachable-code indicators as review aids. These indicators are evidence for prioritization, not claims that every flagged location is defective.

Durable system knowledge base

Completed

Added docs/HIRO_SYSTEM_KNOWLEDGE_BASE.md as the human-readable operating and troubleshooting reference.
Added docs/hiro_system_knowledge_base.v1.json as a structured index of operating components, states, sources of truth, findings, and review coverage.
Added tests/test_hiro_system_knowledge_base.py to verify that referenced files remain present, the structured index remains valid, and the documented promotion/probation policy remains internally consistent.
Documented system maps, source-of-truth precedence, queue and promotion state machines, definitions, evidence-backed findings, read-only troubleshooting runbooks, future repair order, and release gates.
Clearly labeled proposed repair work as future work. No proposal in the knowledge base was implemented during this session.

Evidence-backed problem record

Completed as documentation only

Recorded that the real activation and rollback broker does not yet have an end-to-end process test, even though transaction-store tests exist.
Recorded repeated builder-version requeue activity around meta-change candidates and the state fields involved, without modifying that logic.
Recorded that the current external-corroboration gate appears to interpret a healthy existing regression suite in a way that can reject otherwise viable external ideas, without changing the gate.
Recorded dashboard ambiguity between current promotion transactions and historical promotion data, incomplete incident capture for some raised user-turn failures, shallow model-health probing, a manual model-restart mapping risk, and maintainability hotspots.
Kept unresolved findings at a non-exploitable level suitable for a public journal; the full local knowledge base contains the code references needed for authorized future repair work.

Documentation-only integration

Completed

Committed exactly the two knowledge-base documents and their focused test as revision 30981196d70b9f421e6c1dd0866130a445f62680.
Confirmed there were no active promotion transactions immediately before the controlled restart, then stopped the identified Hiro process, fast-forwarded the live branch, and restarted it.
The fast-forward changed documentation and documentation validation only; it did not change any production module, persisted queue record, candidate artifact, promotion decision, or probation state.

Decisions and reasoning

Treat the owner's correction as a strict session boundary: diagnose and document, but do not repair runtime behavior.
Use the live continuous-improvement path as the canonical operating model and retain Stage 6 terminology only as historical context where it helps interpret older records.
Distinguish observed evidence, inferred causes, and proposed future remedies so the knowledge base can support decisions without overstating certainty.
Prefer stable identifiers and state-machine descriptions over a narrative that could become stale as individual queue counts change.
Keep Hiro active after the documentation-only integration because reactivation was explicitly requested, while leaving every documented behavioral problem unchanged for later authorization.
Require future promotion work to validate the real broker in a process-level harness before relying on it as an autonomous safety boundary. This is a future release gate, not a change made now.

Validation and evidence

Check	Status	Result
Complete Python parse and compile review	passed	All 378 Python files parsed, and compileall completed successfully. One existing non-fatal SyntaxWarning was reported for a documentation-string escape sequence.
Knowledge-base consistency tests	passed	The focused knowledge-base test file completed with 3 passed tests in 0.11 seconds.
Complete Hiro repository test suite	passed	The complete repository suite completed with 766 passed tests and 4 pre-existing unknown-marker warnings in 447.47 seconds.
Documentation-only change boundary	passed	Revision 30981196d70b9f421e6c1dd0866130a445f62680 contains exactly docs/HIRO_SYSTEM_KNOWLEDGE_BASE.md, docs/hiro_system_knowledge_base.v1.json, and tests/test_hiro_system_knowledge_base.py.
Post-integration runtime identity	passed	The health endpoint reported status ok, the configured Qwen model connected, and matching loaded and checkout revisions of 30981196d70b9f421e6c1dd0866130a445f62680. Ports 8000, 8001, and 8765 were owned by the same Hiro process.
Public journal tests and build	passed	npm run test:hiro passed. npm run build generated and validated all 164 journal pages, compiled TypeScript, and completed the Vite production bundle.

Current state

Hiro is online and reports status ok.
The configured Qwen model is connected.
The live checkout is clean at documentation-only revision 30981196d70b9f421e6c1dd0866130a445f62680, and Hiro reports that same loaded revision.
The canonical human-readable knowledge base is docs/HIRO_SYSTEM_KNOWLEDGE_BASE.md; its structured companion is docs/hiro_system_knowledge_base.v1.json.
All behavioral findings remain open and unchanged by design.

Next steps

Use the knowledge base to choose and authorize a bounded future repair session; do not treat its proposed sequence as automatically approved implementation work.
When behavioral repairs resume, begin with a process-level activation, verification, and rollback harness, then address repeated candidate-state churn and corroboration semantics against that harness.
After each authorized repair, update the knowledge base with the new source of truth, exact validation evidence, and any superseded findings.
Keep user-facing answer quality and crash incidents connected to the improvement queue as an explicit future acceptance criterion rather than assuming queue activity alone demonstrates improvement.