The practice catalog turns defined engineering practices into review criteria. Product terminology lives in the practice feedback language guide; this page covers how to maintain the catalog.
The effective catalog combines three scopes:
| Scope | Source | Owner | Effect |
|---|---|---|---|
| Hephaestus defaults | default-catalog.json and its precompute scripts |
repository maintainers | provides bundled definitions and order |
| Instance catalog | bundled defaults plus sparse database overrides | instance administrators | defines what new workspaces receive |
| Workspace practices | independent database copies | workspace administrators | defines reviews in one workspace |
The same definition fields are used at all three scopes. What changes is who owns the value and when it propagates:
| Decision | Hephaestus defaults | Instance catalog | Workspace practices |
|---|---|---|---|
| Name, criteria, and guidance | maintained in the repository | inherited or customized by an instance administrator | copied at workspace creation, then owned by the workspace |
| Binding — the one occasion a practice is reviewed on and the evidence it reads | declared as on in the bundled catalog; optional precompute input is explicit |
inherited or customized in the practice form | copied, then customizable in the same practice form |
| Review frame — contract version, review mode, known limitations | taken from the artifact kind's default; not written per practice in the bundled catalog | inherited or customized in the practice form | copied, then customizable in the same practice form |
| Included in new workspaces | default is included | instance administrator can include or exclude | not applicable after installation |
| Practice autonomy | not a repository setting | not a curated-catalog setting | workspace administrator controls it; a practice Hephaestus cannot review is forced to OFF |
| Review scope | not a repository setting | not a curated-catalog setting | workspace administrator sets it once for the whole workspace |
| Area and order | JSON array order | inherited or changed with drag-and-drop or move actions | copied, then independently managed |
This is a one-way lifecycle: a repository update can update an uncustomized instance definition, and an instance definition can seed a new workspace. Neither step silently rewrites a customized instance definition or an existing workspace.
| Stakeholder | Primary task | Deliberately not their task |
|---|---|---|
| Practice author | Define the habit, guidance, and responsible mentoring support | Authorize collection or certify review accuracy |
| Instance administrator | Curate the defaults offered to new workspaces | Rewrite existing workspace practices |
| Workspace administrator | Adapt practices, set the workspace default autonomy and override it per area or practice, and scope which work is reviewed | Authorize a new data source for the instance |
| Instance operator | Approve source purposes, privacy, retention, and erasure coverage | Decide that connected evidence proves a practice |
| Developer, peer, or mentor | Use observations and available human context in a review | Supply hidden context to Hephaestus implicitly |
The practice editor follows the decisions an author can make confidently:
- Practice — give one observable habit a short, action-oriented name, choose the work it applies to, and optionally group it in an area.
- Review guidance — describe what to look for, why it matters, and one concrete example.
- How Hephaestus can help — choose AI-supported mentoring, human review, or guidance only.
The generated identifier, the occasion a review runs on, and the optional static-analysis script are under Technical settings. A new practice starts with a binding that fits the selected work type. Authors only change that default when the practice genuinely needs a different occasion. This keeps runtime plumbing out of the common path without hiding it from expert authors. A practice has exactly one occasion: reading different evidence at a different moment is a second practice, which is what the shipped catalogue does, and asking for a review by hand is not an occasion to choose at all. The definition-options API supplies the signals a practice on that work type may bind to, the evidence a new binding starts with, and the sources it may read, so the editor and runtime cannot silently disagree about what is bindable. The practice never states its artifact kind: it is read off the signals' shared prefix, which is what stops a declared kind and its triggers from drifting apart.
Write What to look for as a review boundary, not as a personality or a score. Define one observable habit, the signals that demonstrate it, and the cases where a reviewer should stay silent. Do not require intent, private context, runtime behavior, or any other fact outside the selected work and evidence boundary.
The practice form starts with one product choice instead of separate model and evidence-sufficiency settings:
- AI-supported mentoring lets Hephaestus review connected work after every required source passes.
- Human review needed records that connected work is not enough. Hephaestus skips the practice,
while a developer, peer, or mentor may still review it from context the system does not collect.
It still names its occasion — that is where its artifact kind comes from, and saying what a
practice is about was never the same claim as asking Hephaestus to act on it — but it cannot define
a static-analysis script and its autonomy is forced to
OFF. - Guidance only keeps the criteria and guidance without configuring Hephaestus to review it.
The binding starts with the recommended evidence for its work type. Most authors should keep it.
Customize evidence reveals each source's display name, privacy class, the capture quality its
contract demands, and whether it can be captured whole — so an author knows whether an EXHAUSTIVE
stance is available — along with the practice's known limitations. How strictly a source must be
captured is not a per-practice choice: it is stated once in the source contract, which every shipped
practice already agreed with. Selecting a source never authorizes collection; instance governance and
workspace integrations remain separate gates.
| Field | Definition |
|---|---|
| Name | Explain what changed and why |
| Review this kind of work | Pull or merge request |
| What to look for | Look for a description that explains the behavior change and why. Stay silent for automated dependency updates. |
| Why it matters | Reviewers can judge a change faster when they understand its purpose. |
| What good looks like | “This changes retry behavior so temporary network failures no longer end the sync.” |
| Hephaestus support | AI-supported mentoring with the recommended bindings and evidence |
The author does not choose source-contract identifiers or runtime states in this common path. If the required pull-request details or diff are missing, or captured less completely than their contract demands, Hephaestus skips the practice instead of inventing an observation. A more contextual practice, such as whether a developer understood a trade-off discussed privately with a mentor, should use Human review needed and name that missing context.
The instance tables store only decisions that differ from the bundled catalog: a customized definition, inclusion policy, accepted bundled digest, or position. No override row means the bundled definition and order apply. See ADR 0028 for the architectural decision.
- Slug is the current operational identity. It participates in provenance and observation recurrence. Change the display name freely; rename a slug only with an explicit remapping strategy. This is the pre-1.0 workspace-copy model, not the final catalogue identity design.
- Definitions and order are independent. Reordering does not create a definition override or an audit event. Use Hephaestus order removes custom positions.
- Legacy workspace installation happens once. Startup repair preserves the snapshots created before explicit adoption shipped; later instance changes never rewrite those workspace copies. New workspaces start empty and choose what to adopt.
- Adoption is deliberate. Workspace administrators can browse the entries the instance currently offers, inspect the complete effective definition and its validation fingerprint, and then adopt an independent copy. The preview's entity tag must still match when the copy is created.
- Adoption does not authorize automatic sending. A newly adopted practice receives its own
HUMAN_APPROVALautonomy (Review before sending). Reviews may run, but eligible feedback waits for a workspace owner or administrator to approve or reject it. Moving to Send automatically is a separate administrator decision; validation evidence does not make that authorization implicitly. - Provenance is descriptive, not referential. Matched workspace copies retain the source slug and comparison fingerprint without a foreign key. A bundled source may have no database row and may disappear in a later release.
- Unmatched migrated copies remain unlinked. Backfill links only definitions that still match the bundled review rules or area details.
- Exclusion affects future workspaces only. Excluding an area also excludes its practices from new installations; existing workspaces do not change.
Array order in default-catalog.json is the bundled order. Until an administrator reorders a list,
bundled entries continue to follow repository order and instance-created entries append. The first
deliberate reorder records the complete affected list. Moving a practice to another area is a
definition change and is audited.
Explicit review before adoption remains the product boundary, but workspace-local copies keyed by slug are transitional. The 1.0 catalogue design is tracked in #1445: repository-minted stable identities, immutable revisions, adoption records, and repository-managed specializations for technology or course context. A workspace should adopt the general practice once; review-time resolution can then select one applicable specialization and pin its exact revision on the observation.
Do not add one-off technology fields or treat specializations as unrelated practices in this model. Applicability, ambiguity checks, stack confirmation, history, and family-level rollups need one coherent catalogue design. Until that lands, adoption stores the exact source slug and review-rule fingerprint and never derives automatic-delivery authority from a detected technology.
Each effective entry is resolved from the running bundled definition and any instance override:
| Existing instance state | Effective result after upgrade | Admin-page state |
|---|---|---|
| Default not customized | new bundled definition | no badge |
| Customized; bundled definition unchanged | saved customization | Customized on this instance |
| Customized; bundled definition changed | saved customization | Hephaestus update available |
| Instance-created entry | saved definition | No Hephaestus default |
| Uncustomized default removed | entry disappears | — |
| Customized default removed | saved customization | Removed from Hephaestus defaults |
An update never replaces a customization silently. Administrators can inspect the complete bundled definition and whether applying it changes review rules, guidance, or area appearance. Applying an update removes only the definition customization; inclusion policy and custom order remain. Keeping the saved version records the bundled digest that was reviewed.
Git versions bundled defaults. Content-derived ETags reject concurrent writes based on stale content, and the configuration audit records definition and inclusion changes. There is no separate catalog revision counter or materialized copy of every bundled definition.
Catalog-installed or successfully matched workspace copies retain their source slug and the comparison fingerprint captured at installation. The workspace UI derives drift by comparing:
- the definition currently used by the workspace;
- the definition copied originally; and
- the current effective instance definition.
The ordinary matching state has no badge. Exceptions say Customized for this workspace, Instance catalog changed, or Not in the current instance catalog. Drift is informational and never rewrites the workspace.
A practice comparison covers the inputs that affect review behavior: slug, name, bindings (their signals, draft handling, and evidence needs with stances), criteria, precompute script, the automated-review policy, and area. The artifact kind is not compared separately — every signal name carries it, so digesting it too would only give a rename two places to be recorded. Why it matters and What good looks like are guidance and do not affect review-rule drift. An area comparison covers name, description, icon, and color; position is excluded.
Autonomy is a workspace decision, not a catalog one: a practice's autonomy and the workspace's review
scope both live outside the curated catalogue, and a curator never sets either. The
practice review glossary defines both in full — the three autonomy states, what each
one does, and the refusal reasons an out-of-scope or autonomy-OFF artifact records.
What matters for curation is only this: move a noisy but still meaningful practice to HUMAN_APPROVAL so
measurement continues under supervised release. Use OFF when the practice itself should not run; neither
operational choice changes the curated definition.
A practice must:
- identify who is expected to review the habit and from which context;
- distinguish evidence from inference and avoid claims that the code is correct;
- define applicability and the evidence required to report it;
- define false-positive exclusions and proportionate severity;
- use language useful to the developer doing the work; and
- cite research, a standard, or an explicitly identified practitioner norm.
Evidence is declared per binding against the versioned
artifact-source contract and the canonical
practice review glossary. Each entry names a source and a stance —
REQUIRED, EXHAUSTIVE, or CONTEXTUAL — and the practice's policy adds conservative skipping and
known limitations. Requirements must not infer availability from a missing file. What an author declares
is a declaration and nothing more — the product validates no policy independently, and every shipped
policy carries the single status AUTHOR_DECLARED to say so. Requirements also say nothing about whether
a developer, peer, or human mentor can review the practice outside the governed integrations.
The review-rule fingerprint uses an explicit scheme prefix, bumped whenever its inputs change rather than the rules, so a stored fingerprint is never compared against one computed from a different set of facts. Each scheme retains its original meaning, so two schemes never compare equal by accident. Bump the prefix in the same change that alters the input set.
Architecture-wide qualities cannot be inferred from one change. A practice may review an observable act, such as recording a decision, without turning it into a claim about the whole system.
Classify evidence accurately:
| Classification | Requirement |
|---|---|
| Peer-reviewed evidence | an empirical study directly supports the claimed relationship |
| Standard or canonical guidance | a recognized standard or established engineering guide recommends it |
| Practitioner norm | a community convention with no controlled-outcome claim |
Record exact sources in the proposal or pull request that changes the practice. Do not present a standard as an experiment or a convention as a proven outcome.
- State the user problem and supported reviewed work.
- Cite and classify the evidence.
- Draft applicability, signals, exclusions, the binding's evidence, and severity.
- Confirm every source applies to the binding's artifact kind and that its governance decision permits the product purpose, audience, processor egress, and retention. A new source follows the artifact-source governance gate.
- Update
server/src/main/resources/practices/default-catalog.json; its adjacent JSON Schema provides editor completion and CI validation, and Git history is the bundled version history. Declare the one occasion ason— a bare signal name is shorthand for a binding on that signal reading the artifact kind's default evidence. Reference any precompute script explicitly; a script must be named after the practice slug, and an unreferenced one fails validation. - Add or update focused automated-review tests, including required-source skipping and valid-empty evidence.
- Review the admin presentation and a representative piece of delivered feedback.
Create workspace-specific practices through the admin UI or API so validation, ordering, revisions, and audit behavior remain intact.