feat(webapp): explain practice-group standings with supporting evidence

.changeset/practice-group-detail-page.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": minor
+---
+
+A developer can open a practice group from their profile and see what its standing is actually built from: which practices contribute to the group, where each of them stands, and the feedback behind them. A standing is no longer a label you have to take on trust.

.changeset/practice-group-empty-states-and-severity-wording.md

@@ -0,0 +1,9 @@
+---
+"hephaestus": minor
+---
+
+A practice group with no verdict now says which kind of silence it is instead of one catch-all "No feedback yet": whether nothing in it has been reviewed for you yet, or whether it was reviewed and nothing could be judged — because the practices did not apply, or because the evidence did not settle the question. A developer can tell a review that ran and found nothing from one that never ran.
+
+An observation carries the same severity wording wherever it appears, and every severity is told apart by its own icon rather than by colour alone.
+
+The evidence behind an observation reads as a quoted passage with its source named. A quote from code shows the file and the line range, with numbered lines below, and is marked when it comes from the old side of the change — the line quoted is then not what the file says now. A quote from a conversation or a document shows the source and the passage without line numbers — those numbers are positions inside a stored copy, not places you could open, and printing them made a chat message look like a file. When a quote is withheld, the block says why: the secret scanner never stores text that looks like a credential, and the location is still named so you can read it at the source.

.changeset/practice-group-review-runs.md

@@ -0,0 +1,7 @@
+---
+"hephaestus": minor
+---
+
+A practice group now shows its review runs as complete moments: every observation from one review stays together, instead of being split across pages so that a review is only ever half-visible.
+
+Developers can answer the feedback they receive, not just rate it. Alongside marking a piece of feedback helpful or unhelpful, they can record what they did about it — addressed, disputed, or not applicable — and explain it in their own words. Disputing asks for that explanation, so a disagreement always arrives with a reason attached. Any part of an answer can be changed or withdrawn later.

.changeset/practice-group-standing-cards.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": minor
+---
+
+On their own profile, a developer now sees a compact summary per practice group: where they currently stand, the guidance behind that standing, and how the group has developed across recently reviewed work. These summaries appear on your own profile only — the standing is derived for the signed-in developer, so another person's profile does not show them.

.changeset/practice-standing-feedback-api.md

@@ -4,4 +4,4 @@
 
 The application API can now answer where a developer stands in each practice group: the current standing and its guidance, how the group has developed across recently reviewed work, which kinds of work contributed feedback, a filterable observation history, and the complete review runs behind it. An undecided observation remains visible in that history without being presented as a verdict. Developers can also replace or delete their response to delivered feedback, recording whether it was helpful, how they handled it, and an optional explanation. Every endpoint answers only for the signed-in developer.
 
-**Operators:** direct API callers must replace `/practice-areas` with `/practice-groups`, use the corresponding group schema and field names, replace `/practices/learner` with `/practices/reviewed`, and move from the older reaction endpoint to the combined response endpoint. Existing response history is preserved; `MIGRATION.md` lists the contract changes. The generated Hephaestus web client is updated in the same release.
+**Operators:** direct API callers must replace `/practice-areas` with `/practice-groups`, use the corresponding group schema and field names, replace `/practices/developer` with `/practices/reviewed`, and move from the older reaction endpoint to the combined response endpoint. Existing response history is preserved; `MIGRATION.md` lists the contract changes. The generated Hephaestus web client is updated in the same release.

.migration/practice-standing-feedback-api.md

@@ -0,0 +1,24 @@
+#### 🔴 The practice-area endpoints are replaced by practice-group endpoints
+
+**Affected**: anything calling the application API directly — scripts, dashboards, or an integration
+built against `/practice-areas` or the developer practice list. Deployments that only run the
+bundled web client need no changes; it ships updated in this release.
+
+**Before**: practice groupings were served under `/workspaces/{workspaceSlug}/practice-areas`, with
+`PracticeArea` schemas and `areaSlug` parameters. A developer's practices came from
+`/workspaces/{workspaceSlug}/practices/developer`, and a reaction to delivered feedback was recorded
+through its own endpoint.
+
+**After**: the same groupings are served under `/workspaces/{workspaceSlug}/practice-groups`, with
+`PracticeGroup` schemas and `groupSlug` parameters — *practice area*, `PracticeArea`, `areaSlug` and
+`/practice-areas` are retired names, not synonyms, and no alias remains. The developer practice list
+is `/workspaces/{workspaceSlug}/practices/reviewed`. A developer's response to delivered feedback —
+whether it was helpful, how it was handled, and an optional explanation — is written through one
+combined response endpoint that replaces the earlier reaction endpoint. Every one of these answers
+only for the signed-in developer.
+
+**Migration**: update each caller's paths, parameter names and response field names to the group
+spelling, move any caller of `/practices/developer` to `/practices/reviewed`, and switch reaction
+writes to the combined response endpoint. Response history recorded before the upgrade is preserved
+and readable through the new endpoint, so nothing needs re-entering. Regenerate any client
+built from `server/openapi.yaml`.

webapp/.storybook/preview.tsx

@@ -141,6 +141,7 @@ const preview: Preview = {
 					"Instance admin",
 					"Practice trace",
 					"Workspace",
+					"Profile",
 					"Surveys",
 					"Common",
 					"Shared",

webapp/AGENTS.md

@@ -460,7 +460,7 @@ page throws the reader back to the top.
 |---|---|---|
 | What an instance offers | **catalog** / instance catalog | library |
 | Availability to workspaces | **include / exclude** | offer, retire |
-| A grouping of practices | **group** (user-facing); `area` stays in code, types and the API | area, section |
+| A grouping of practices | **group**, at every layer — copy, code, types and the API alike | area, section |
 | A practice with no group | **Unassigned** | No area, Not in an area, Belong to no area |
 | Inputs and criteria | **review rules** | review behavior, detection config |
 

webapp/src/components/admin/practice-reviews/ObservationFilters.stories.tsx

@@ -27,7 +27,7 @@ const PEOPLE: ReviewPeople = {
 	isLoading: false,
 	isError: false,
 };
-const AREAS: FacetSource = {
+const GROUPS: FacetSource = {
 	options: groupFacetOptions(practiceGroups),
 	isLoading: false,
 	isError: false,
@@ -48,7 +48,7 @@ const meta = {
 		search: { presence: undefined, assessment: undefined, severity: undefined },
 		onPatch: fn(),
 		onReset: fn(),
-		groups: AREAS,
+		groups: GROUPS,
 		practices: PRACTICES,
 		people: PEOPLE,
 		total: 12,

webapp/src/components/admin/practice-reviews/ObservationsListPage.stories.tsx

@@ -31,7 +31,7 @@ const PEOPLE: ReviewPeople = {
 	isLoading: false,
 	isError: false,
 };
-const AREAS: FacetSource = {
+const GROUPS: FacetSource = {
 	options: groupFacetOptions(practiceGroups),
 	isLoading: false,
 	isError: false,
@@ -124,7 +124,7 @@ const meta = {
 		isLoading: false,
 		error: undefined,
 		onRetry: fn(),
-		groups: AREAS,
+		groups: GROUPS,
 		practices: PRACTICES,
 		// The facet needs a label per slug; the hover card on a row's practice name needs the record.
 		practiceRecords: workspacePractices,

webapp/src/components/practice-vocabulary/feedback-resolution-defs.ts

@@ -0,0 +1,36 @@
+import { CircleCheckIcon, CircleSlashIcon, MessageCircleQuestionMarkIcon } from "lucide-react";
+
+import type { PracticeGroupReviewObservation } from "@/api/types.gen";
+
+import type { StatusDefs } from "./status-def";
+
+export type FeedbackResolution = NonNullable<PracticeGroupReviewObservation["feedbackResolution"]>;
+
+/**
+ * What the developer did about a piece of delivered feedback — the half of a response about the
+ * work, where `feedback-usefulness-defs` is about the review. The two are independent on the wire
+ * and stay independent here.
+ *
+ * `DISPUTED` is the only value the server demands an explanation for, so its description says so
+ * rather than leaving the reader to find out when the form refuses.
+ */
+export const FEEDBACK_RESOLUTION_DEFS: StatusDefs<FeedbackResolution> = {
+	ADDRESSED: {
+		label: "Addressed",
+		icon: CircleCheckIcon,
+		badgeVariant: "success",
+		description: "You changed the work in response to this.",
+	},
+	DISPUTED: {
+		label: "Disputed",
+		icon: MessageCircleQuestionMarkIcon,
+		badgeVariant: "warning",
+		description: "You disagree with this observation. Say why, so a human can weigh it.",
+	},
+	NOT_APPLICABLE: {
+		label: "Not applicable",
+		icon: CircleSlashIcon,
+		badgeVariant: "outline",
+		description: "The observation does not apply to this work.",
+	},
+};

webapp/src/components/practice-vocabulary/feedback-usefulness-defs.ts

@@ -0,0 +1,27 @@
+import { ThumbsDownIcon, ThumbsUpIcon } from "lucide-react";
+
+import type { PracticeGroupReviewObservation } from "@/api/types.gen";
+
+import type { StatusDefs } from "./status-def";
+
+export type FeedbackUsefulness = NonNullable<PracticeGroupReviewObservation["feedbackUsefulness"]>;
+
+/**
+ * Whether delivered feedback was worth receiving — the half of a response about the review, where
+ * `feedback-resolution-defs` is about the work. Neither derives the other: feedback can be useful
+ * and still not apply.
+ */
+export const FEEDBACK_USEFULNESS_DEFS: StatusDefs<FeedbackUsefulness> = {
+	HELPFUL: {
+		label: "Helpful",
+		icon: ThumbsUpIcon,
+		badgeVariant: "success",
+		description: "This told you something you could act on.",
+	},
+	UNHELPFUL: {
+		label: "Not helpful",
+		icon: ThumbsDownIcon,
+		badgeVariant: "destructive",
+		description: "This was not worth the read.",
+	},
+};

webapp/src/components/practice-vocabulary/practice-group-standing-defs.ts

@@ -0,0 +1,67 @@
+import {
+	CircleAlertIcon,
+	CircleCheckIcon,
+	CircleDashedIcon,
+	CircleMinusIcon,
+	CircleSlashIcon,
+} from "lucide-react";
+
+import type { PracticeGroupStanding } from "@/api/types.gen";
+
+import type { StatusDef } from "./status-def";
+
+export type PracticeGroupStandingValue = PracticeGroupStanding["standing"];
+
+export interface PracticeGroupStandingDef extends StatusDef {
+	shortLabel: string;
+}
+
+/**
+ * Where a developer stands in a practice group, worst first. `DEVELOPING` means problems
+ * *predominate* — `MIXED` has them too — and `NO_OPPORTUNITY` covers evidence that settled nothing
+ * as well as work that offered no occasion.
+ *
+ * Both silences render outline, so the icon separates them: dashed for "nothing seen yet", a slash
+ * for "nothing to see". `shortLabel` is the ring legend's wording, where five entries share a row.
+ */
+export const PRACTICE_GROUP_STANDING_DEFS: Record<
+	PracticeGroupStandingValue,
+	PracticeGroupStandingDef
+> = {
+	DEVELOPING: {
+		shortLabel: "Needs attention",
+		label: "Needs attention",
+		icon: CircleAlertIcon,
+		badgeVariant: "destructive",
+		description: "Recent reviews here were mostly problems.",
+	},
+	MIXED: {
+		shortLabel: "Mixed",
+		label: "Mixed feedback",
+		icon: CircleMinusIcon,
+		badgeVariant: "warning",
+		description: "Recent reviews found both strengths and problems here.",
+	},
+	STRENGTH: {
+		shortLabel: "Going well",
+		label: "Going well",
+		icon: CircleCheckIcon,
+		badgeVariant: "success",
+		description: "Recent reviews here were almost entirely positive.",
+	},
+	NO_OPPORTUNITY: {
+		shortLabel: "Nothing to report",
+		label: "Nothing to report yet",
+		icon: CircleSlashIcon,
+		badgeVariant: "outline",
+		description:
+			"Your work was reviewed, but nothing here could be judged — either these practices did not apply to it, or the evidence did not settle the question.",
+	},
+	NOT_OBSERVED: {
+		shortLabel: "Not observed",
+		label: "Not observed yet",
+		icon: CircleDashedIcon,
+		badgeVariant: "outline",
+		description: "No practice in this group has a current verdict for you.",
+	},
+};

webapp/src/components/practice-vocabulary/practice-trend-defs.ts

@@ -0,0 +1,38 @@
+import { CircleDashedIcon, CircleHelpIcon, TrendingDownIcon, TrendingUpIcon } from "lucide-react";
+
+import type { PracticeTrend } from "@/api/types.gen";
+
+import type { StatusDefs } from "./status-def";
+
+export type TrendDirection = PracticeTrend["direction"];
+
+/**
+ * Which way recent evidence points. `UNCERTAIN` means the comparison was made and did not separate;
+ * `INSUFFICIENT_EVIDENCE` that none was possible. Both render muted, so the icon separates them.
+ */
+export const PRACTICE_TREND_DEFS: StatusDefs<TrendDirection> = {
+	IMPROVING: {
+		label: "More positive recently",
+		icon: TrendingUpIcon,
+		badgeVariant: "success",
+		description: "Recent reviewed work carried more strengths than the stretch before it.",
+	},
+	DECLINING: {
+		label: "More difficulties recently",
+		icon: TrendingDownIcon,
+		badgeVariant: "destructive",
+		description: "Recent reviewed work carried more problems than the stretch before it.",
+	},
+	UNCERTAIN: {
+		label: "Direction unclear",
+		icon: CircleHelpIcon,
+		badgeVariant: "secondary",
+		description: "The two stretches were compared and did not separate far enough to call.",
+	},
+	INSUFFICIENT_EVIDENCE: {
+		label: "Not enough to compare yet",
+		icon: CircleDashedIcon,
+		badgeVariant: "outline",
+		description: "There is not yet enough reviewed work on both sides to compare.",
+	},
+};