Practice review glossary
This page owns terms for the review operation and runtime. The product vocabulary owns practices, observations, problems, feedback and people. A term has one definition in one of these pages.
Review terms
| Term | Meaning | Identifier |
|---|---|---|
| Item | One thing that an observation can concern or a review can cover. Its kind states what it is. | item, item.kind |
| Version | One fixed state of an item. Its domain defines what identifies that state. | item_version |
| Event | A recorded change to an item, such as a pull request merged. | item_event |
| Review | One operation that checks practices against an item at a version and can record observations. | review |
| Scan | A review of the items held by another item at a version. The holder is a repository on its monitored default branch. | review.kind = SCAN |
| Scan exclusion | A listed file that cannot supply scan text. It stays in the inventory and has no eligible practice/file pairs. | inventory_receipt.exclusions |
| Origin | How a review started: an event, a request, a schedule or a backfill. | review.origin |
| Review status | Where a review stands as the API reports it. A started review is Queued while an invocation waits and none runs. It waits for capacity, for room for its sandbox, for the workspace's AI budget, or for a retry. Otherwise it is Running. | ReviewShownStatus |
| Practice status | Where one practice stands in its review. Queued until capture decides it is Ready or Withheld. A scan's practice is Running from the first file that a worker captures for it. A practice that capture never reached ends Withheld with its review's stop reason. | review_practice.status |
| Review scope | The repositories and people that a workspace permits Hephaestus to review. | review_scope_repository, membership.review_selected |
| Role | The developer's role a practice concerns: author, reviewer, assignee or merger. The editor label is About. | definition.about |
| Review on | The events and recorded state that select a practice for automatic review. | definition.reviewOn |
| Applies when | The conditions that establish whether a practice applies on every review origin. | definition.appliesWhen |
| Reviewed by | Who reviews a practice: Hephaestus, people or nobody. | definition.reviewedBy |
| Practice script | Code that reviews one practice for one item and returns one candidate observation. | definition.script |
| Candidate | The proposed observation that a script returns before server admission. | Candidate |
| Admission | The server checks that decide whether a candidate can become an observation. | result admission |
| Feedback mode | How the workspace permits feedback: Off, Approve first or Automatic. | feedback_mode |
| Publication context | What other reviews communicated on the same work to the same developer, as one history read issued it. A public piece keeps the context it was composed from. | publicationContext |
| Evidence | The material that a review captured and read. | result.evidence |
| Citation | A pointer into captured source text at an item version, with its quote and available coordinates. | citation |
| Coverage | What an observation read and what it did not read. | result.coverage |
| Report | A scan's summary and supported observations for workspace admins and exports. | review.report |
| Quiet window | The wait before an item event starts a review, so that newer events of the same item can join it. | planned: item_event.retry_at |
| Problem lineage | How a problem compares with the previous comparable result of the same practice on the same item. | planned: problem.lineage_id |
| Readiness edge | The moment the server decides which selected practices of an item run. It comes when the quiet window closes, or at once for an occasion that never joins a window. | planned |
| Source fingerprint | A value for one source kind of an item, computed by its source contract. Equal fingerprints mean equal captured bytes. A result stays current while the fingerprints of every source its session could read do not change. | planned: result.read_fingerprints |
Quiet window and Problem lineage are decided for 1.0 and not shipped yet (ADR 0062). Readiness edge, Source fingerprint and Feedback composer are decided for 1.0 and not shipped yet (ADR 0069).
Use Review as the short product name where the page establishes the practice context. Use practice review in prose that does not establish that context. A provider's review is always a pull request review or a merge request review. It is an item, not a Hephaestus review.
In product text, name the concrete item kind. Write “212 files,” not “212 items.” Work is a plain word with no identifier or separate taxonomy.
Origins
| Value | Started by | Meaning |
|---|---|---|
| EVENT | The named event | The adapter recorded a change that selects a review. |
| REQUEST | A request | An authorized person requested a review or scan. |
| SCHEDULE | A schedule | A workspace schedule selected a review. |
| BACKFILL | A backfill | An authorized batch reviews earlier work without delivering feedback. |
Origin and review kind are independent. A requested repository review is a scan with REQUEST origin. A backfill is not another observation outcome or another current-observation namespace. The pipeline owns ordering, eligibility and feedback restrictions.
Review definition and feedback mode
A practice version holds its definition. The editor labels Review on, Applies when, About and Reviewed by map to the fields above. The catalog guide owns definition identity and update behavior. The review pipeline owns applicability checks and capture refusal behavior.
HEPHAESTUS permits automated review. PEOPLE requires human review and an explanation of why. NOBODY keeps the practice as guidance with no automated review. A practice with a null script uses the built-in script. A script that fails does not fall back to it.
Feedback mode is separate from Reviewed by. Off prevents feedback at every destination but does not prevent eligible observation recording. Approve first requires an admin decision before feedback leaves on the work. Automatic permits that delivery after the normal policy checks. The two active modes permit eligible practice-page and conversation feedback without public approval.
A practice can inherit feedback mode from its group, then from its workspace. A null setting means inherit. It does not mean Off. Changing a setting does not approve an older proposal. Delivery pause and the developer's external-feedback preference remain separate checks. The operator guide owns their scope and controls.
Admission reasons
UNDECLARED_SOURCE_CITED (undeclared_source_cited) marks a withheld candidate that cites or says it consulted a source outside its practice's declared Reads.
The checkout's diff and tree are always readable through Git.
A source used only to check Applies when does not become a runtime read source.
The server records no observation for the refused candidate.
This refusal establishes neither missing evidence nor a defect in the developer's work.
The operations guide gives the operator's next step.
Legacy history reasons
LEGACY_AMBIGUOUS_RESULTS marks a withheld assignment with multiple migrated results for the same review, practice and item.
Its result pointer is null. At cutover, the assignment records the producing job and the number of results.
All original results remain separate history with evidence version 0. No sibling is selected as the assignment's answer.
Existing source permissions, custody, privacy controls and retention still apply.
LEGACY_REUSE_UNBOUND marks a historical reuse whose reference does not identify exactly one result.
The assignment is withheld and has no result pointer.
LEGACY_REVIEW_UNBOUND marks a withheld item event from a release that keyed submitted reviews by the pull request head.
The event stays on its pull request with its original name, revision and times. It names no review, so it cannot start one.
Retained occasion evidence is the record of a pull request or submitted review that an item event keeps when it is recorded. It holds the version, review state, roles and work record as Hephaestus stored them at that moment. It also keeps the native identity of each person it names.
An event review of that event reads only this record. It never reads the current work in its place. The record expires at a fixed time after the event is recorded. Expiry, erasure and removal of the item replace it with a statement of why it is gone.
OCCASION_EVIDENCE_UNAVAILABLE marks a withheld item event whose retained occasion evidence is missing, expired, erased or too large to keep.
The same name is the source capture code that causes it.
Runtime terms
| Term | Meaning | Identifier |
|---|---|---|
| Job | Execution of a review in a sandbox, with attempts and costs. | review_job |
| Agent | The sandboxed runtime that executes a review, or the conversation host. | agent runtime |
| Attempt | One claimed execution of a job, protected by its execution fence. | attempt |
| Attempt token | The signed credential of one attempt, of a review or of a conversation turn. It names the attempt and its workspace, and nothing else. | AttemptJwt |
| Lease | A running attempt's claim to its worker, until a time on the database clock. The claim sets it, and the worker's heartbeat renews it. When it expires, the server recovers the attempt. | review_job.leased_until |
| Model assignment | A workspace's choice of a model for an execution purpose and AI tier. | workspace model configuration |
| Model for practice scripts | A decision, embedding or reranking model that a script can call through its host. | script model purposes |
| Source contract | The definition of a source's identity, meaning, capture facts and permitted uses. | reads.contract |
| Source kind | A stable name for a logical source of captured material. | SourceKind |
| Capture | The authorized collection of material and its explicit source facts for a review. | capture stage |
| Readiness | Whether the captured sources meet the practice's declared requirements. | review_practice |
| Job folder | The worker's disposable files and repository copies for one execution attempt. | workspace ABI |
| Runtime non-result | An assigned practice that stopped without a candidate. Its stop reason describes execution, not the work. | nonResults |
| No-fault attempt | An attempt that ended for a reason that is not the review's: a worker's drain or no sandbox room. It gets a new number but spends no retry. | drain_count, room_refusals, ReviewJob.spentAttempts |
| No sandbox room | The stop reason of a review that no sandbox room can ever hold. It also ends reviews that waited an hour while no review ran and no room came. It describes capacity, never the work. "Hephaestus had no room to run this review in time." | NO_SANDBOX_ROOM |
| Composition | The preparation of feedback from admitted and eligible observations, by the worker after the sandbox ends. | feedback composition |
| Feedback composer | The model with tools that composes, posts and corrects the feedback of one review at one destination. It holds no provider token. | planned |
| Not composed | A withholding for a destination that no composed decision reached, when no more specific reason applies. | NOT_COMPOSED |
| Composition stop | The cause that left a destination without composed feedback. A passing cause hands the attempt on. | CompositionStop |
| Stage | The admission of one practice's candidate when the practice ends. The candidate waits on its membership row until the seal. | planned: review_item.state = STAGED |
| Seal | The one transaction that writes a review's staged results and problems. | planned |
| Send | One leased provider write or retraction of on-work feedback, with its reconciliation state. | feedback_send |
| Review digest | The digest of the definition inputs that can change an observation from the same evidence. | practice_version.review_digest |
| Conversation host | The one long-lived sandboxed process on a worker that runs conversation turns. | heph-host.ts, HephHost |
| Turn | One run of Hephaestus for one question in a conversation, with its attempts, lease, partial answer and usage. | mentor_turn, conversation_turn from 1.0 |
| Call pool | Provider capacity that the models in it share, whichever workspace calls them: a limit of calls in flight, an interactive reserve and a cooldown. | llm_call_pool |
| Call permit | One model call's share of its call pool, held as a lease by the worker that makes the call. | llm_call_permit |
| Call class | Whose call takes a permit: a conversation turn, or a review of one origin. Only a turn may use the interactive reserve. | LlmCallClass |
| Context folder | The read-only files that one agent may read for one person, in one workspace, for one purpose. | INDEX.md, inputs/context/, repos/ |
| Context document | One JSON document about the developer or the workspace in the context folder of a conversation. | inputs/context/*.json |
| Context loader | The integration part that stages a heavy item, such as a repository, into a context folder on request. | ContextLoader, load_context |
| Turn sandbox | The sandbox that holds the context folder of a conversation for one turn attempt, with no network and no credentials. | TurnSandboxes |
| Sandbox namespace | The Kubernetes namespace that an operator creates for the sandboxes of one release alone. | worker.sandbox.namespace |
| Isolation probe | A worker's check, with real Pods, that the cluster holds the sandbox boundary. No sandbox starts while it fails. | KubernetesIsolationProbe |
| Isolation tier | What the isolation probe records without gating: the runtime class, user namespaces and the process limit. | sandbox.isolation.* |
| Runtime attempt | One attempt of a review job or of a conversation turn, with one lease, one attempt token and writes fenced on the lease. | planned: AttemptJwt |
| Review agent Pod | The Pod of one review attempt: a trusted loop container with the token, and a tools container without one. | planned |
| Tools Pod | A Pod that runs only the tools program of a review agent Pod, bound to one conversation turn attempt, with no token and no egress. | planned |
| Conversation loop | The one long-lived trusted process that runs the conversation turns of an install and calls tools Pods for their tools. | planned |
| Tool protocol v1 | The messages from a loop to its tools, each with a request id. It has hello, put, read, streamed exec, cancel and reset, and script runs for reviews. | planned |
Stage and Seal are decided for 1.0 and not shipped yet (ADR 0063). Runtime attempt, review agent Pod, tools Pod, conversation loop and tool protocol v1 are decided for 1.0 and not shipped yet (ADR 0068).
The job folder of a review is the context folder of that review. The Conversation runtime owns turns, the conversation host, context documents, context loaders and turn sandboxes. A turn is not a job: it has no job row and no review.
A job can expire without removing its review or observations. The runtime guide owns execution, retries and retention. The workspace ABI owns file paths and capture records. The source contract owns capture states. The data model owns durable keys and guards.
USAGE_UNVERIFIABLE stops a scan because the cost of earlier model calls cannot be verified.
It does not mean that the scan used up its budget.
An execution that made no model call adds no usage row.
Standard terms
This section records conceptual correspondence, not claims of standard conformance. External terms retain the meaning of their standard. Product labels remain the labels defined above and in the product vocabulary.
| Hephaestus concept | EARL / ACT | SARIF 2.1.0 | OSCAL assessment results |
|---|---|---|---|
| Practice | Test criterion | reportingDescriptor | Control objective |
| Practice version | Criterion definition used | Rule metadata and properties | Objective definition used |
| Review | Evaluation with assertions | run | Assessment activity |
| Scan | Evaluation of a collection | run | System assessment |
| Item | Test subject or test target | artifact or logical location | Assessment subject |
| Version | State under evaluation | revisionId | State under assessment |
| Observation | Assertion and TestResult | result or run properties | Objective-status finding |
| Met | passed | pass | Satisfied objective |
| Not met | failed | fail | Unsatisfied objective |
| Does not apply | inapplicable | notApplicable | Applicability explanation |
| Could not determine | cantTell | open | Unresolved assessment explanation |
| Not reviewed | untested | Coverage properties | Scope and activity record |
| Problem | Failed expectation and pointer | fail result | Evidence of non-compliance |
| Example | Supporting evidence | Properties or supporting location | Evidence of compliance |
| Open question | Reason for cantTell | open details or properties | Assessment explanation |
| Citation | pointer | location and snippet | Relevant evidence |
| Report | Evaluation report | log | Assessment results document |
The EARL and ACT outcome terms correspond to the four observation outcomes and the separate Not reviewed state. This does not make a withheld candidate an untested claim. See EARL 1.0 and ACT Rules Format.
The SARIF specification defines export fields and allowed values. The SCM export creates one fail record per visible problem and puts coverage totals in run properties. It does not invent pass records for files it did not review. Critical and Major map to error, Minor to warning, and Trivial to note.
The original severity stays in properties. Trivial remains a fail. It is not the standard’s informational result kind. Baseline values new, unchanged, updated and absent describe problem comparison. Absent needs comparable complete proof at a changed version. Removal and admin marks do not prove absence.
The OSCAL assessment model separates evidence from objective-status conclusions. An OSCAL observation can support compliance or non-compliance. Despite the shared word, it is not a Hephaestus observation. An OSCAL finding is closer to a Hephaestus observation than to one located problem. This correspondence does not provide an OSCAL exporter.
ISO/IEC 17000 supplies conformity-assessment vocabulary. A practice review corresponds to an assessment activity, not a certification of a developer or repository. Do not claim an ISO clause mapping that the implementation does not establish.
PROV-DM separates entities, activities and attribution. Captured versions and practice versions correspond to entities. Reviews correspond to activities. A provider actor and an observation's developer have different attribution roles. This is a design comparison, not a PROV export contract.
Task, process and self-regulation are research descriptions of feedback content. The destination alone cannot prove that content has one of these levels. Do not derive or store a scientific level from ON_WORK, PRACTICE_PAGE or CONVERSATION. A research evaluation must classify the actual feedback and state its method.
Historical research records
Preserve the recorded schema and criteria of an empirical record. A historical positive behavior label does not prove the complete practice standard was met. Recomputing a definition digest does not reassess the old work. Keep the original outcome and evidence qualification separate. The evaluation provenance contract owns these limits.