Skills And Reviewer Workflow¶
Structured Assessments And Shadow Plans¶
The reviewer report endpoint accepts assessment instead of a Markdown summary.
Version 1 records scope, dimensions, complete, classification_confirmed,
evidence, limitations, findings, and resolutions. The server renders a
concise public assessment; typed reports do not need prescribed Markdown headings.
Legacy summaries remain accepted so retained sessions can publish their evidence.
Dimensions are mathematical_contract, public_design, proof_trust,
computational_cost, distributability, and scholarly_traceability. They are
questions, not reviewer accounts. A finding records a stable report-local key,
dimension, severity (blocking or improvement), scope, finding, evidence and
requested change. Approval requires a complete assessment without blocking findings.
An incomplete or change-requesting review never satisfies specialist coverage.
The latest current-head assessment controls coverage; old-head change requests
remain unresolved after a push. A resolution names the prior review_id, a
disposition (repaired or withdrawn), explanation and evidence. The original
reviewer must publish that confirmation through a prepared invocation at the
current head. The maintainer can implement the repair but cannot self-waive its
independent assessment. Resolution becomes effective after Forge delivery and
actual reviewer completion;
policy, rubric or target changes invalidate stale evidence. A valid explicit
carry-forward can retain a previously confirmed resolution together with its
unchanged reviewed scope. This first protocol supports the original reviewer;
delegating adjudication to a different persona is not yet supported.
Reviewer preparation optionally accepts review_plan with version: 1,
mode: "shadow", base_commit_oid, scope_paths, questions (dimension and
question), and risk_triggers. It pins selected questions into the invocation
manifest alongside the head, policy and descriptor revisions. The independent
reviewer must confirm the classification and assess all selected questions to
approve; it can broaden the assessment when necessary. Delivery verifies the
target base, and merge refuses stale or inconsistent bases.
Shadow plans do not reduce any repository's required reviewer panel. Activating a proportional dimension policy requires a separately calibrated implementation; passing a plan cannot waive existing phase or repository requirements. No active project descriptor, policy or retained catalog is rewritten by installing these contracts. Administrative rollout must account for older unresolved reviews.
The current runtime is src/archon_horizon/pipeline. Its source skills are in
pipeline/skills/{operations,lean,review}/, and specialist reviewer descriptions
are in pipeline/subagents/reviewers/. Worker specialties occupy the sibling
implementation/, research/, validation/ and planning/ folders.
They ship together in the immutable
instruction bundle, but a reviewer is a subagent descriptor, not a skill.
Skill Discovery¶
Each skill has a short frontmatter description and metadata.category:
operations, lean, or review, matching its source directory. The
control plane builds a grouped SKILLS.md index inside the immutable bundle;
initial prompts expose descriptions, while agents load the relevant full skill
only when needed. Continuation keeps the existing context and pinned bundle.
Operator additions/overrides use skill_source_root in server configuration.
Override the existing category/name path to replace a skill; duplicate names
at different paths are rejected. A session resolves its entrypoint from its
pinned index, so reorganizing source does not invalidate retained contexts.
The operations catalog covers startup, delegation, workspaces, Forge, Zulip, roadmaps, obligations, progress, efficiency, and source research. Lean skills cover search, builds, repair, refactoring, profiling, proof minimization, simplification, counterexamples, and tactics. Review procedures cover statement alignment, definition quality, proof review, and the maintainer workflow.
The entrypoint links a bundled harness orientation: phase semantics, durable
ownership, continuation and where authoritative evidence lives. Agents need no
checkout of Horizon's development docs. horizon-communication provides shared
Markdown, mathematical notation, semantic emoji and low-noise message conventions.
Markers are presentation, not database statuses or notification commands.
Selected Lean skills adapt MIT-licensed material from cameronfreer/lean4-skills.
Pinned provenance and the license ship in skills/_sources/lean4-skills/.
They require no plugin runtime, extra installation, hooks, or model provider.
Cameron's upstream repository combines a central skill with many references and
commands; top-level skill counts alone do not measure retained guidance.
Administrators can browse installed skills and their supporting files under Agents > Skills, and source descriptors under Agents > Subagent library. Agents > Reviewers edits the descriptors enabled for the selected project. These are distinct views: installed templates do not imply enabled reviewers. Prepared reviewer invocations inject the selected revision's instructions and exact PR head directly. Their relevant skills remain available on demand; they do not rely on the reviewer discovering its own persona in a skill.
Preparation includes an exact-head review packet whose ASCII JSON representation is bounded to 16 KiB. It contains the selected policy and rubric, reporting contract, trusted-check summary, and exact evidence URLs with their response fields. Complete instructions and the typed report schema remain in an immutable context artifact; oversized sections have explicit omission markers and JSON pointers. Reviewers start from this packet, read omitted requirements, and fetch deeper skills or evidence for concrete questions. They still assess semantics independently and recheck relevant discussion and head/base pins before reporting.
The report response's id is its outbox UUID; its idempotency_key identifies
the API receipt. Check delivery through
GET /api/v3/operations/{idempotency_key}?operation=reviewer_report, even though
the returned outbox kind is forge_review. A completed receipt with
result_ref_id establishes delivery. It does not finish the provider turn or
establish acceptance of the PR.
Worker Specialists¶
Nine optional templates support bounded native delegation:
| Category | Descriptors |
|---|---|
| Implementation | lean-worker, refactorer, forge-integrator |
| Research | source-researcher, page-transcriber |
| Validation | build-checker, debug, library-auditor |
| Planning | graph-planner |
The pinned SUBAGENTS.md index exposes names, descriptions and file paths.
Initial assignment prompts include the worker-specialist summaries; continuation
does not reload them. The parent reads a selected descriptor and includes its
body, task, exact inputs, editing scope, skill-directory path and expected result
in the native child prompt. The provider's actual subagent tool launches the
child; a descriptor file alone does not register a native agent type.
Workers can use specialists without becoming maintainers. Parent sessions retain
integration and ledger ownership, and respect provider capacity. Native children
are not durable future assignments. When work must outlive the parent, use the
ordinary assignment queue with the selected instructions and a concrete mission;
specialist names are not entries in the assignment functions field.
graph-planner addresses mathematical decomposition. Run scheduling remains the
existing worker planner function. The former collaborator and maintainer profiles
are represented by the two execution roles; this catalog adds no new permission
profiles, automatic dispatch loops or accounts. Formal PR reviewers continue to
use the prepared invocation and attribution workflow described below.
Review Perspectives¶
| Destination And Phase | Available Perspectives | Intended Scrutiny |
|---|---|---|
| Roadmap, preprocessing | Statement fidelity, decomposition, definitions, library API | Route selection first, then strict compiled contracts and concrete definitions before human baseline approval |
| Roadmap, formalization | Roadmap consistency; full contract panel for corrections | Proportionate graph/progress review; strict review for frozen contract changes |
| Library, postprocessing | Mathematical fidelity, library API, library architecture, Lean proof quality, Lean performance, repository quality, scholarly quality | Strict, starting with statements and definitions, then proofs and publishing quality |
| Workspace | None by default | Free working space; destination policies apply when promoting code |
Installed templates alone do not impose a panel. For postprocessing, however, every enabled descriptor linked to the repository policy must provide a current-head receipt before merging; a maintainer-only decision cannot replace it. Milestone projects enforce decomposition approval for route PRs and all four contract perspectives for Lean contract PRs, with a trusted current-head receipt. This also applies to contract corrections during formalization. Legacy projects and verified graph-only changes retain proportionate selection. The maintainer can repair bounded issues directly and manage several PRs at once. Independent reviewers use fresh contexts and the exact PR head. A statement or API defect may make proof polishing premature; independent concerns and PRs can run in parallel within the existing provider capacity. The common review contract distinguishes blockers, useful improvements and preferences. Reviewers must return concrete evidence, not manufacture objections to appear strict.
Before launching a round, the maintainer posts its brief review intent on the PR:
selected perspectives, concrete questions, relevant prior coverage and integration
owner. New project review presets use durable reviewer assignments, configured
with invocation: assignment. Each selected perspective gets a narrow mission,
an independently leased worker and an immutable exact-head review manifest.
Reviewers consume primary slots only when dispatched; the dispatching maintainer
can finish after delegating its obligations and queueing a terminal-conditioned
integration maintainer. Native subrequests remain an explicit option for short
reviews collected during one parent execution. Existing descriptors and pinned
invocations keep their mode; missing native completion events must be reconciled,
not bypassed by duplicating already owned work in another mode.
For a durable review, call POST /api/v3/reviewer-assignments with the same
ReviewerPrepare fields as native preparation. The response contains the queued
assignment, pinned manifest, parent obligation, and completion_condition.
Delegate that obligation explicitly to the returned assignment; combine all
selected completion expressions with op: all in one integration assignment's
start condition. Completed, failed and cancelled reviewers all wake integration,
which inspects their receipts and current-head coverage before approving or
arranging a diagnosed retry. The reviewer publishes using its own current
provider request ID, settles its own obligation with the delivered review,
completes its narrow mission, and returns. It does not wait for authors or the
gate that requires its own completion.
A completed reviewer with an unusable report can receive an explicit correction
on unchanged pins when review_readiness.next_actions identifies that defect.
Submit the supplied retry_of and a concrete retry_note. The service preserves
the reviewer identity, head, policy and review plan, and checks that the previous
process and deliveries are settled. Valid approvals and substantive change
requests cannot be rerun to seek a different verdict. Old reports remain visible.
Review packets include the reviewer's earlier objections; approving a repair
requires explicit evidence-backed resolutions, not just a new approval label.
Preset recipes accept invocation: subrequest to opt into native mode. For an
existing project, revise a descriptor through the supported catalog API before
its first preparation on the intended head; a descriptor revision change can
invalidate previously pinned coverage. Do not rewrite an active invocation's
manifest or switch its mode to recover a missing event.
Use the PR's review_readiness to identify missing current-head coverage and
existing review work before preparing another invocation. Its next_actions
provide the exact schema lookup and accepted request fields; diagnostic metadata
is not part of the preparation request. For a new native invocation, preserve
the full prepared prompt, including its exact Review label, in the actual
subagent launch. Attach the child ID returned by the provider. The review label
identifies the task; it is not a native child ID. Attachment registers a launch
that has already happened and does not start a reviewer itself.
In native mode, keep the parent active until its reviewers finish and their independent reports are delivered. Reviewers verify their outbox delivery receipt, return it to the maintainer and finish their native turn. They must not wait for their own approval/readiness gate, which requires actual native completion. Delivered reports and amendments retain their evidence without closing provider requests or releasing capacity; native terminal observations or confirmed execution stops control that lifecycle. A confirmed stop without a native result records an interruption, not a successful review. Lease loss alone, however old, retains capacity until the host confirms cleanup or an operator records physical fencing. A child observed before attachment can be reconciled only when its live execution, parent and pinned environment match the prepared invocation. Interrupted or ambiguous histories remain explicit repair work. Confirm both the delivered report and the gate result: a successfully published comment alone does not establish review acceptance. Retries reference the interrupted attempt and explain the repair; existing active work is collected rather than duplicated.
Prepared prompts include a bounded current-head verification discovery URL,
plus any matching pending verification job and existing trusted receipt. A job
can finish after preparation: refresh the published evidence at a useful review
boundary before reporting a missing check. The check ID and job ID name different
endpoints. Reuse evidence only when its repository, source/base commits, manifest
and toolchain apply; a successful build does not establish semantic correctness.
Do not duplicate a full build while matching trusted verification is pending or
passed without a specific uncovered concern. Necessary focused probes belong in
reviewer-owned disk-backed $TMPDIR, never in host-managed job checkouts or caches.
Selection is adaptive: start with the questions that matter, inspect reports, then add perspectives for material remaining uncertainty. The catalog groups reuse/naming/generality under library API, packaging/imports under repository quality, and attribution/exposition under scholarly quality. Projects can split or combine these in custom revisioned descriptors. Explicit destination policy requirements still apply; the installed list itself imposes no review quota. Postprocessing policy links define the mandatory panel; maintainers can also select any enabled project descriptor for an additional relevant concern. Register a custom descriptor in the project before preparing its attributed invocation.
The shared contract requires coverage of significant changed declarations in each perspective, concrete positive checks, severity-calibrated findings and exact evidence. Public reports lead with the decision and actionable findings; a clean approval is short and links its detailed coverage/check evidence. Scope, blocking findings, verified checks, validation limits and verdict may be combined instead of repeated as long sections. Follow-ups inspect affected findings and the new delta, linking unchanged evidence while retaining required current-head receipts. Direct maintainer reviews use the same evidence standards. Source templates receive the shared contract through the loader; existing project descriptors must be updated explicitly.
The detailed phase workflow ships in
horizon-pipeline/references/phases.md, available to workers and maintainers.
For already proved input, postprocessing normally adapts coherent result families
with their proofs. Review public statements and definitions first within those
PRs. A separate prototype is useful for materially uncertain interfaces, not a
mandatory stage for every port. Prototypes may contain explicit sorry: the README, or
a prominently linked proof ledger, records each declaration, accepted statement
PR, proof status, dependencies and durable owner. Subsequent PRs progressively
prove those milestones and explain the contribution's consumer path. Statement
acceptance and proof closure are distinct claims; library review is strict about
the former immediately without requiring the latter prematurely. Reviewers can
ask for strategy and design discussion even when code elaborates, comparing
relevant mathlib declarations and proposals before accepting a competing API.
Postprocessing requires bounded, low-cost improvements to useful generality, public signatures, definitions, naming and structure. A current consumer passing does not justify accidental specialization, duplicate infrastructure or avoidable layers. Reviewers identify the concrete benefit and tested alternative; the maintainer repairs it directly or records a specific tradeoff before acceptance. Speculative generalization and personal preferences remain distinct. Public design takes priority over proof micro-optimization.
When the workspace already supplies the proofs, workers port and adapt independent proof groups in parallel against pinned source and destination interfaces. Separate file ownership and a shared integration owner prevent collisions. New research needs an identified source gap or concrete simplification benefit; the campaign should not routinely reprove existing results. Statement and definition review remains strict, and destination proof closure must be verified independently of the source's completed status.
The PR contains the cumulative review history. Maintainers read earlier reviews,
inline findings and replies before choosing additional perspectives. Each
substantive specialist assessment is published through the durable Forge review
operation by the reviewer itself, including clean assessments and disagreements.
The maintainer tracks publication for native and durable reviewers and verifies
the receipt; a private report or its own approval is not a substitute. The
semantic emoji and bold labels from horizon-communication distinguish scope,
blockers, improvements, evidence and verdict. Review-state labels summarize the
selected descriptor's running, accepted, change-requested or other outcome while
the PR discussion preserves every round and unresolved finding.
Lifecycle labels use the policy's maintainer Forge identity, or the configured integration account when no maintainer identity is selected. Reviewer accounts retain read-only repository collaborator access; their substantive assessments still publish under the selected specialist identity. Label history therefore records control-plane projection, while review records preserve authorship.
Previously queued label intents retain their original credential choice. A definitive HTTP 403 from a specialist-owned label must not be retried unchanged: cancel that failed or pending intent, then queue the current label state with a new idempotency key through the operational identity. Reconcile running or uncertain deliveries first, and leave already-cancelled labels cancelled.
For a superseded head, changed base, closed PR or recovered incomplete assessment,
submit historical: true and verdict: commented against the original invocation.
Its manifest retains the reviewed commit. Inline coordinates are prohibited in this mode; use stable file references
in the summary. Horizon preserves pinned rubric provenance and labels lifecycle
uncertainty. This publishes feedback without completing the invocation or granting
approval. Historical reports use the descriptor's current publishing identity;
current approvals retain the identity pinned when the reviewer was prepared.
Setting a descriptor's identity alone does not authorize an external account;
its native permissions and credential must be provisioned and verified.
Library Audits And Tools¶
library-architecture examines composition across modules and PRs: canonical
objects, bridge lemmas, instances, simplification, dependency direction and
constructed inputs. library-audit provides the broader workflow when accepted
PRs may be locally sound but collectively problematic. The maintainer pins an
accepted commit, subsystem, concrete doubt and representative consumers, then
selects specialists as the evidence warrants. Sampling is explicit. Findings
identify affected endpoints, bounded repairs, an integration owner and checks
on the repaired composition.
An audit with no open PR uses an ordinary native child or durable assignment, not a fabricated reviewer invocation. The parent records evidence and owned repair issues/assignments. Audits do not automatically block unrelated PRs, rewrite accepted code or run periodically without a mission/trigger.
The bundled review tool guide covers source/search, Lean probes, trust checks, consumer builds and Radar/CI performance evidence. Radar is a separately configured benchmark server/runner service; Horizon does not install one or assume its GitHub commands work on Forgejo. Existing configured benchmark requests follow their project authorization and durable Forge delivery path.
lean-performance/scripts/compare_measurements.py is a read-only, standard-library
Python helper packaged with the skill. It compares existing Radar-format JSONL
artifacts, sums duplicate metrics with matching units, reports missing metrics
and unit changes, and leaves percentage change unknown for a zero baseline.
It does not authenticate caller-supplied provenance, launch benchmarks, publish
results or impose a performance threshold. The tool guide documents invocation
and comparability requirements. New Radar deployments remain operator setup.
Authorship And Native Accounts¶
Execution roles remain worker and maintainer. A reviewer descriptor supplies
perspective, instructions and optional model settings; it does not create a new
permission role. Prepared invocations pin the descriptor, repository, phase,
commit and selected integration identity. Their lifecycle is tracked independently
from the parent's other reviews.
Configured reviewer descriptors use their own Forge accounts through
integration_identity_id; the maintainer account owns its own assessment and
final merge decision. Invocation-backed results preserve their descriptor,
rubric revision and reviewed commit through the durable delivery queue.
Project setup must provision and link the selected accounts, reusing an existing
identity when applicable. A template's presence in the catalog alone does not
launch a reviewer or grant repository permissions.
The maintainer receives HORIZON_REVIEWER_ACCOUNTS_FILE, a private descriptor
account mapping for authorized direct Forge interactions. Retained executions
can retrieve the mapping through their scoped reviewer-accounts API directly
into a private mode-0600 scratch file, without printing the JSON response. A reviewer
uses only its selected identity and never copies credential values into prompts,
logs or published evidence. Ordinary assessments use the reviewer-owned report
endpoint so that publication remains journaled and recoverable. Direct Forge
discussion operations can use the matching account where the scoped writer
does not yet expose the native operation; record their published URLs.
Zulip remains for decisions needing attention, with the existing configured identity. Attribute a specialist discussion with a reviewer heading and a link to the PR review; do not copy every finding or credential to chat.
Reviews And Line Discussions¶
Read the PR description, diff, existing reviews and relevant replies first. Use
the Forge inspection API for reviews and review_comments, including pagination.
The reviewer submits its structured report to
POST /api/v3/reviewer-invocations/{provider_request_id}/report; the manifest
binds the descriptor, identity and reviewed revision. Native reviewers use their
inherited execution credential; durable reviewers use their own. Reporting is
separate from provider lifecycle completion and can carry line-specific findings:
{
"verdict": "changes_requested",
"summary": "The public definition excludes a case required by the source.",
"historical": false,
"comments": [
{
"path": "Geometry/Curve.lean",
"new_position": 18,
"body": "This hypothesis excludes closed curves; compare the source definition."
}
]
}
For the current reporting contract, use
horizon-pipeline agent schema --section operations --name reviewer_report.
Submit through agent request so idempotency and reconciliation are preserved.
If new evidence corrects an assessment while the native reviewer invocation is still active,
the same reviewer can amend it through the same invocation's /report endpoint.
Reconcile any uncertain previous delivery first; a changed assessment is a new
intent, not a replay of the old body. Explain the correction and explicitly
resolve earlier blocking findings. Once that native turn has returned, a live
parent execution alone does not authorize more reviewer work: arrange an
explicitly authorized reservation before resuming it. Use current API receipts and contracts for
this decision; old release source trees are not authoritative runtime evidence.
new_position and old_position are file line numbers on the corresponding diff
side; specify exactly one positive position. General observations belong in the
summary. Comments and the review are created in one native API operation, with
the same idempotency/reconciliation marker, so a lost response cannot create a
second review on retry. Reading native thread replies is supported; the current
writer creates review discussions, not arbitrary nested replies or resolve-thread
operations. Those capabilities must not be implied by a generic issue comment.
Only the maintainer makes the final policy decision. Specialist approvals remain advisory and cannot independently open a merge gate. Recheck the current head and required checks before merging; changed evidence can require a focused follow-up.
Updating Existing Projects¶
Shipped preset changes affect new project recipes. Existing reviewer descriptors
are revisioned records, editable in Agents > Reviewers or through the catalog API.
Update their instructions and use functions: ["reviewer"]; rubric names belong
in the descriptor slug, not the execution function list. Preserve custom identity,
harness, model and policy choices. New invocations capture the updated revision;
old invocations and old provider contexts keep their pinned evidence.