Instruction and reviewer implementation review¶
The review covers every Python function in the seven modules listed below, including nested helpers and model validators. It examines their current contracts, branches, bounds, side effects and existing tests. It is a scoped implementation review, not a claim that all Horizon functions were audited. The extended backend review records complete function coverage for the surrounding instruction, review, integration, provider and search modules.
Changes and invariants¶
Behavioral instructions are readable Markdown under
src/archon_horizon/pipeline/instructions/templates/. The installed instruction
catalog exposes every template with its content digest. Its dashboard browser
lists current templates and legacy compatibility templates separately. The
reserved prompts/ bundle namespace cannot be overridden by added project
skills.
New contexts pin all templates in their existing skill artifact. Retained phase,
completion, recovery and prepared-review prompts read that artifact rather than
the current installed source. Prepared reviewer manifests also retain the fully
rendered prompt and complete immutable review context. Named {{identifier}}
fields interpolate once; JSON braces and shell variables are literal text. A
missing or corrupted new-bundle template fails explicitly instead of changing
instructions silently.
Older bundles contain core, planner and maintainer text but no prompt template
index. Their original fields remain authoritative. Fragments that were never
pinned historically use the packaged compatibility text; the old missing text
cannot be reconstructed from those bundles. A new context is needed to adopt
new behavior deliberately. The legacy supervisor template remains visible only
under legacy/orchestrator; preserving it supports already-persisted runs.
Objective continuations carry current mission scope and commitments without repeating planner/maintainer startup. Duplicate mission text is replaced by a ledger reference. Both Markdown and JSON ledger rendering charge identifiers, markup and (for JSON) character escaping against the aggregate inline budget. Exact omitted content stays in linked records or immutable snapshots. A bounded briefing therefore never proves all obligations were inspected or fulfilled.
Function coverage¶
| Module | Functions inspected | Findings and disposition |
|---|---|---|
instructions/prompts.py |
catalog, _phase_repositories, _review_readiness_batch, operations_context, nested size and sanitized, orchestrator_context, _orchestrator_goal, _pinned_bundle, objective_goal, goal, nested excerpt |
Fixed live-source phase/handoff/recovery fragments, objective startup repetition, duplicated seed text and aggregate ledger bounds. Objective repository lookup now permits a document without a frozen snapshot. Operational snapshots remain read-only, project-scoped and bounded; their textual annotations describe data, not new authority. |
instructions/bundles.py |
_skill_metadata, skill_overview, skill_files, skill_path |
Extended the existing deterministic byte/file bounds to packaged templates; metadata remains discovery-only. Symlinks are rejected and installed templates win over added skill sources. Duplicate skill/subagent names remain rejected. |
instructions/instruction_catalog.py |
read_catalog |
Added lazy template discovery and preview. Existing file membership, UTF-8 and preview-size checks apply; previews do not edit project descriptors or retained bundles. |
instructions/templates.py |
template |
Added restricted, single-pass field substitution and digest-checked pinned resolution. Legacy fallback is explicit. Name validation prevents traversal; unresolved or extra fields fail. |
projects/bootstrap.py |
RecipeRecord.known_kind, launch, expanded, resolve, preview, operator, apply |
Extracted seeded policy prose. Existing explicit recipe ordering, reviewed IDs, credential references, transactional application and idempotency checks remain necessary. Default advisory guidance treats graph milestones as planning data; destination libraries must be sorry-free. Existing saved policy records are not overwritten. |
review/invocations.py |
ReviewerPrepare.explicit_retry, report, _maintainer, _owned, provider_limits, _capacity, prepare, prepare_assignment, _assignment_result, _work_key, _verification_evidence, _verification_discovery, _existing_work, _record_work, _prepare, assignment_manifest, assignment_request_fields, read, attach, bind_native, _bind_observed_child, cancel, release_child_claims, account_observed_child |
Extracted reviewer startup, reporting, optional plan/retry instructions and durable lifecycle into parent-pinned templates. Preparation remains authorization rather than launch. Exact-head/rubric/policy ownership, diagnosed retries, physical-stop confirmation and capacity settlement remain enforced Python. Verification discovery retains legacy packet field names for compatibility but uses the general Lean API; they supply evidence rather than prescribe mathematical strategy. |
review/packets.py |
encode, prepare_packet |
Moved substantial reporting requirements to pinned templates. Structured report fields, exact-source links, byte budgets and complete-artifact locators remain Python data. Prior objections must remain available in the complete context even when omitted inline. |
Validation¶
Focused regressions cover retained and historical catalogs, fail-closed template resolution, literal interpolation, reviewer template/packet provenance, and both ledger budgets. Existing prompt, review invocation, review packet, reviewer preset and instruction catalog tests check behavior across these boundaries. Distribution validators now require every source template in both wheel and source archives, including reviewer startup instructions.