From bdd803537b9b6cedc2695d6e37caba5216de367b Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Wed, 21 Oct 2026 21:14:03 -0400 Subject: [PATCH] docs(6208): the remaining frontend comments drop milestone, step and rule citations Components, stores, api clients, router, types and shared CSS now state what each piece is and why, without the milestone that introduced it. diff.ts names its consumers instead of the copy history; stores/notes and tasks state their current scope instead of the cleanup that set it; theme.css states the token practice instead of the sweep that established it. Co-Authored-By: Claude Opus 5.5 --- frontend/src/api/backups.ts | 2 +- frontend/src/api/canonicalSystems.ts | 2 +- frontend/src/api/client.ts | 4 ++-- frontend/src/api/family.ts | 2 +- frontend/src/api/inception.ts | 4 ++-- frontend/src/api/lessons.ts | 2 +- frontend/src/api/moments.ts | 7 +++---- frontend/src/api/platforms.ts | 2 +- frontend/src/api/replyShapes.ts | 2 +- frontend/src/api/rulebooks.ts | 14 +++++++------- frontend/src/api/snippets.ts | 4 ++-- frontend/src/assets/moments-shared.css | 2 +- frontend/src/assets/rules-shared.css | 4 ++-- frontend/src/assets/theme.css | 7 ++----- frontend/src/components/BackupScheduleSettings.vue | 4 ++-- frontend/src/components/FamilyAdoptionMatrix.vue | 2 +- frontend/src/components/InceptionCard.vue | 4 ++-- frontend/src/components/MomentProposals.vue | 4 ++-- frontend/src/components/MomentsSettings.vue | 2 +- frontend/src/components/NoteSweepPane.vue | 4 ++-- frontend/src/components/ProjectFamilyTab.vue | 2 +- frontend/src/components/ReplyShapesSettings.vue | 2 +- frontend/src/components/SystemsSection.vue | 6 +++--- frontend/src/components/UsageBadge.vue | 3 +-- .../src/components/rules/PreferenceDriftPane.vue | 2 +- frontend/src/components/rules/ProjectRulesTab.vue | 2 +- .../src/components/rules/RuleEditorSlideOver.vue | 6 +++--- frontend/src/components/rules/RuleHistoryPanel.vue | 2 +- frontend/src/components/rules/RuleHomePicker.vue | 2 +- .../src/components/rules/RulebookDetailPane.vue | 3 +-- frontend/src/router/index.ts | 6 +++--- frontend/src/stores/canonicalSystems.ts | 2 +- frontend/src/stores/moments.ts | 2 +- frontend/src/stores/notes.ts | 6 ++---- frontend/src/stores/platforms.ts | 2 +- frontend/src/stores/rulebooks.ts | 2 +- frontend/src/stores/tasks.ts | 5 ++--- frontend/src/types/note.ts | 4 ++-- frontend/src/types/usage.ts | 4 ++-- frontend/src/utils/diff.ts | 12 ++++-------- frontend/src/views/FamilyView.vue | 2 +- frontend/src/views/LessonDetailView.vue | 2 +- frontend/src/views/LessonEditorView.vue | 12 +++++------- frontend/src/views/NoteEditorView.vue | 4 ++-- frontend/src/views/ProjectListView.vue | 2 +- 45 files changed, 80 insertions(+), 95 deletions(-) diff --git a/frontend/src/api/backups.ts b/frontend/src/api/backups.ts index f4d777f5..08dd3087 100644 --- a/frontend/src/api/backups.ts +++ b/frontend/src/api/backups.ts @@ -1,7 +1,7 @@ import { apiGet, apiPost, apiPut } from "@/api/client"; /** - * Scheduled backups (milestone 523) — `/api/admin/backups`. One dated, + * Scheduled backups — `/api/admin/backups`. One dated, * uncompressed tar per run, delivered to a folder or an S3 bucket. */ export interface BackupConfig { diff --git a/frontend/src/api/canonicalSystems.ts b/frontend/src/api/canonicalSystems.ts index d7c26496..14f273f7 100644 --- a/frontend/src/api/canonicalSystems.ts +++ b/frontend/src/api/canonicalSystems.ts @@ -1,6 +1,6 @@ /** * Canonical systems — the GLOBAL area vocabulary every project's Systems can - * map onto (milestone 307). + * map onto. * * The mapping is an ASSOCIATION, never a rename: a project's System keeps the * name the project gave it, and `canonical_id` only records which shared area diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 2f4c1103..2a43779c 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -55,7 +55,7 @@ export function apiErrorMessage(e: unknown, fallback: string): string { /** * How long an ordinary JSON call may wait before it is declared failed. * - * Rule 156: a wait with no deadline is a bug. `fetch`'s own default is to wait + * A wait with no deadline is a bug. `fetch`'s own default is to wait * as long as the browser will, which is not a deadline — it is the absence of * one, and it renders as a spinner that never resolves. There is no state a * surface can show for "pending forever" that is not a lie. @@ -118,7 +118,7 @@ export interface RequestOpts { * The one place a request is actually made — every verb below goes through * here, so the deadline cannot be forgotten by adding a sixth. * - * EXPIRY SURFACES AS AN `ApiError`, which is rule 156's second half: the + * EXPIRY SURFACES AS AN `ApiError`, the deadline's second half: the * failure has to arrive in the shape the caller already handles. A bare * `DOMException: TimeoutError` would reach `apiErrorMessage(e, fallback)` as * an object with no `body`, so every catch site in the app would report its diff --git a/frontend/src/api/family.ts b/frontend/src/api/family.ts index 45852044..9f8b654b 100644 --- a/frontend/src/api/family.ts +++ b/frontend/src/api/family.ts @@ -1,5 +1,5 @@ /** - * Family canon (milestone 463): ideas every project on a platform shares, and + * Family canon: ideas every project on a platform shares, and * the log of every decision about them. * * The agent promotes by written criteria — no approval step. This door is for diff --git a/frontend/src/api/inception.ts b/frontend/src/api/inception.ts index f520cc21..3314eaa3 100644 --- a/frontend/src/api/inception.ts +++ b/frontend/src/api/inception.ts @@ -1,11 +1,11 @@ -/** Project inception (milestone 297): what a project was decided to inherit. */ +/** Project inception: what a project was decided to inherit. */ import { apiGet, apiPost } from "@/api/client"; import type { ProjectPlatform } from "@/api/platforms"; export interface InceptionChoices { design_system_id: number | null; seed_systems: boolean; - /** Platform slugs (milestone 463). null = not answered; a list is the + /** Platform slugs. null = not answered; a list is the * whole answer — members left out of it are recorded as "not this". * Absent on records decided before the question existed. */ platforms?: string[] | null; diff --git a/frontend/src/api/lessons.ts b/frontend/src/api/lessons.ts index 281ed8e3..066566b7 100644 --- a/frontend/src/api/lessons.ts +++ b/frontend/src/api/lessons.ts @@ -72,7 +72,7 @@ export interface Lesson { tags: string[]; note_type: string; /** Where it was LEARNED. Kept as a fact, but not a limit on where it can be - * found: a lesson is retrievable from every project (milestone 385 step 3). */ + * found: a lesson is retrievable from every project. */ project_id: number | null; permission?: string; created_at: string | null; diff --git a/frontend/src/api/moments.ts b/frontend/src/api/moments.ts index 381b567b..bb1e55c0 100644 --- a/frontend/src/api/moments.ts +++ b/frontend/src/api/moments.ts @@ -1,7 +1,7 @@ import { apiGet, apiPost, apiDelete } from "@/api/client"; /** - * The moments of work rules mount on (milestone 458), and the actions that + * The moments of work rules mount on, and the actions that * reach each one on this install — `GET /api/retrieval/moments`, the payload * the `list_moments` MCP tool returns, plus the counts the Settings view shows * beside each moment. @@ -102,9 +102,8 @@ export function unmapAction(change: MappingChange): Promise { /** * Proposals about a rule's moments, waiting on a person. A `mount` proposal - * (milestone 458 step 7) comes from a pass that read the rule, or from the - * rule being opened just after the moment fired. An `unmount` proposal (step - * 7b) comes from sessions reporting that the mount arrived where it did not + * comes from a pass that read the rule, or from the rule being opened just + * after the moment fired. An `unmount` proposal comes from sessions reporting that the mount arrived where it did not * apply. `GET /api/retrieval/moments/proposals`, the payload the * `rule_moment_proposals` MCP tool returns. */ diff --git a/frontend/src/api/platforms.ts b/frontend/src/api/platforms.ts index 8e27cd58..e560cf68 100644 --- a/frontend/src/api/platforms.ts +++ b/frontend/src/api/platforms.ts @@ -1,5 +1,5 @@ /** - * Platforms — what a project is built on or ships as (milestone 463). + * Platforms — what a project is built on or ships as. * * The catalog is GLOBAL, like the canonical areas, and admin-written. A * project's answer per platform is `declared` (a person said so), `detected` diff --git a/frontend/src/api/replyShapes.ts b/frontend/src/api/replyShapes.ts index 27b4832b..cd877eb2 100644 --- a/frontend/src/api/replyShapes.ts +++ b/frontend/src/api/replyShapes.ts @@ -1,7 +1,7 @@ import { apiGet } from "@/api/client"; /** - * The reply shapes Scribe ships (milestone 500) — `GET /api/retrieval/reply-shapes`. + * The reply shapes Scribe ships — `GET /api/retrieval/reply-shapes`. * The same catalog the `list_reply_shapes` MCP tool returns, plus what only * the operator's view needs: the preferences mounted on each shape's moment, * and how often each shape was delivered. diff --git a/frontend/src/api/rulebooks.ts b/frontend/src/api/rulebooks.ts index f4552855..06b96c1d 100644 --- a/frontend/src/api/rulebooks.ts +++ b/frontend/src/api/rulebooks.ts @@ -3,7 +3,7 @@ import type { RecordUsage } from "@/types/usage"; import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client"; import type { LinkState } from "@/api/lessons"; -/** How a rule reaches a session (milestone 307). */ +/** How a rule reaches a session. */ /** * A typed edge between two rules. Each kind exists because its absence forced @@ -56,7 +56,7 @@ export type RuleKind = "rule" | "preference"; /** A new record opened from somewhere that already knows what it is for — * "Adjust this" on a reply shape opens a preference mounted on that shape's - * moment (milestone 500 step 5). The editor applies it once, when creating. */ + * moment. The editor applies it once, when creating. */ export interface RulePreset { kind?: RuleKind; moments?: string[]; @@ -91,11 +91,11 @@ export interface Rule { updated_at: string | null; /** Present only when the rule has them (the server omits empty keys). */ systems?: { id: number; name: string }[]; - /** The moments this rule arrives at whenever they happen (milestone 458), + /** The moments this rule arrives at whenever they happen, * in catalog order. Present only when the rule is mounted. */ moments?: string[]; relations?: RuleRelation[]; - /** The lessons that point at this rule (milestone 440) — the concrete + /** The lessons that point at this rule — the concrete * situations judged instances of it, plus any suggested and awaiting a * judgment. Readable lessons only; omitted when there are none. */ lessons?: { id: number; title: string; state: LinkState; note: string }[]; @@ -124,7 +124,7 @@ export interface RuleHeader { */ last_verified?: string; /** - * Surfaced-vs-opened counts from `rule_usage_events` (milestone 333). + * Surfaced-vs-opened counts from `rule_usage_events`. * Zero-filled by the list route, so a rule predating the table reads as * "never surfaced" rather than as a missing field — which for a while is * every rule on every install. @@ -238,7 +238,7 @@ export async function updateRule(id: number, data: Partial): Promise< } /** Give a rule a new home: a topic makes it global, a project makes it that - * project's. Keeps its id, history, areas and relations (milestone 414). */ + * project's. Keeps its id, history, areas and relations. */ export async function moveRule( id: number, to: { topic_id: number } | { project_id: number }, ): Promise { @@ -295,7 +295,7 @@ export async function getRuleVersion( return apiGet(`/api/rules/${ruleId}/versions/${versionId}`); } -// No restore FOR A RULE, deliberately (milestone 323). Putting an old wording +// No restore FOR A RULE, deliberately. Putting an old wording // back goes through updateRule, which snapshots what it replaces — so the // undo stays visible in the history like any other edit. // diff --git a/frontend/src/api/snippets.ts b/frontend/src/api/snippets.ts index 801f9d4c..a5a8daa3 100644 --- a/frontend/src/api/snippets.ts +++ b/frontend/src/api/snippets.ts @@ -57,7 +57,7 @@ export interface Snippet { /** Kept as a name because every consumer here says "snippet usage" — but it IS * the shared shape, since rules answer the same question off their own table - * (milestone 333). The reasoning lives on `RecordUsage`; duplicating the four + * The reasoning lives on `RecordUsage`; duplicating the four * fields here is how the two drift. */ export type SnippetUsage = RecordUsage; @@ -95,7 +95,7 @@ export interface SnippetListItem { * written, which is a shape to adapt rather than code to paste. */ language?: string; /** When to reach for it, projected from the `data` mirror. The title is the - * name alone since milestone 427, so this is where the situation lives. */ + * name alone, so this is where the situation lives. */ when_to_use?: string; /** Always present from the backend, zero-filled for records with no events. */ usage?: SnippetUsage; diff --git a/frontend/src/assets/moments-shared.css b/frontend/src/assets/moments-shared.css index 0bb072f0..c4c127dc 100644 --- a/frontend/src/assets/moments-shared.css +++ b/frontend/src/assets/moments-shared.css @@ -1,4 +1,4 @@ -/* Moments (milestone 458): the pieces the rule editor's picker and the +/* Moments: the pieces the rule editor's picker and the Settings section share, so a moment's name and a chip's remove control look the same wherever a person meets them. Loaded unscoped by both. */ diff --git a/frontend/src/assets/rules-shared.css b/frontend/src/assets/rules-shared.css index f5214394..8c6fab45 100644 --- a/frontend/src/assets/rules-shared.css +++ b/frontend/src/assets/rules-shared.css @@ -20,8 +20,8 @@ milestone (tier, then verification) and were byte-identical; a third would have drifted. The pane's italic serif title is inherited by anything inside it, so the chip resets family and style explicitly. */ -/* A rule with no trigger cannot be retrieved, and since milestone 394 - retrieval is the only delivery — so this marks a rule that will never +/* A rule with no trigger cannot be retrieved, and retrieval is the only + delivery — so this marks a rule that will never reach a session. Warning rather than error: the rule is not broken, it is unreachable, and the fix is one field away. */ .rule-chip-inert { diff --git a/frontend/src/assets/theme.css b/frontend/src/assets/theme.css index f1744439..9fa9ad2b 100644 --- a/frontend/src/assets/theme.css +++ b/frontend/src/assets/theme.css @@ -208,11 +208,8 @@ */ /* ========================================================================== - The compatibility-alias block that lived here is GONE (#2533). It let ~55 - components keep their historical --color-* names while theme.css was - repointed at the design system; the rename sweep it promised ran on - 2026-08-08 and every component now references --fs-* directly. Do not - reintroduce app-local alias names — the design system's tokens are the + Every component references the design system's --fs-* tokens directly. + Do not introduce app-local alias names — the design system's tokens are the vocabulary, and check_snippets_against_design_system can only see through names the system actually declares. ========================================================================== */ diff --git a/frontend/src/components/BackupScheduleSettings.vue b/frontend/src/components/BackupScheduleSettings.vue index 4a8f7248..bfca1fb1 100644 --- a/frontend/src/components/BackupScheduleSettings.vue +++ b/frontend/src/components/BackupScheduleSettings.vue @@ -11,7 +11,7 @@ import { fmtStamp } from "@/utils/dateFormat"; import { useToastStore } from "@/stores/toast"; /** - * Scheduled backups (milestone 523): one dated, uncompressed tar per run, + * Scheduled backups: one dated, uncompressed tar per run, * delivered to a folder or an S3 bucket. The page answers "is my data backed * up?" first — the verdict, then anything wrong — and the settings follow. */ @@ -50,7 +50,7 @@ async function load() { } } -// While a backup runs, follow it. Re-armed from load()'s finally (rule 157), +// While a backup runs, follow it. Re-armed from load()'s finally, never after the work, // so one failed read does not stop the page following the run. function schedulePoll() { if (pollTimer) clearTimeout(pollTimer); diff --git a/frontend/src/components/FamilyAdoptionMatrix.vue b/frontend/src/components/FamilyAdoptionMatrix.vue index 8adfd707..754a111e 100644 --- a/frontend/src/components/FamilyAdoptionMatrix.vue +++ b/frontend/src/components/FamilyAdoptionMatrix.vue @@ -1,6 +1,6 @@