feat: comment-hygiene — constraints not narrative, rule + gate + sweep (goal 0038) (#55)

* feat: comment-hygiene standard + gate (goal 0038, 1/2)

Source comments state constraints, never decision provenance --
.claude/rules/comments.md is the standard; check-comment-hygiene.sh
enforces it from lefthook pre-commit and a required CI job (same
one-script-two-callers shape as check-loc.sh). Baseline: 65
violations, swept in the follow-up commit of this goal's PR.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJ8wStsHyu7XPLTspNjMnQ

* fix: sweep decision-provenance out of source comments (goal 0038, 2/2)

All 65 baseline violations resolved per .claude/rules/comments.md:
62 comment rewrites keeping constraints/regression properties and
docs citations while dropping owner quotes, session narrative, and
dates; plus 3 string literals rewritten as neutral product copy (a
Playwright test title, a capability-map StatusDetail, the
integration-http NodeType description -- no test pinned any of the
three). check-comment-hygiene.sh now exits 0.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJ8wStsHyu7XPLTspNjMnQ

* docs: archive goal 0038 — acceptance met, delivered 2026-08-13

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJ8wStsHyu7XPLTspNjMnQ

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alicoding

.claude/rules/comments.md

@@ -0,0 +1,32 @@
+# Comment discipline — constraints, not narrative
+
+No `paths` frontmatter deliberately — applies to every hand-written
+source file regardless of language, the same way architecture.md does.
+
+**A code comment states what the code cannot: an invariant, a
+non-obvious constraint, an external tool's gotcha, the property a
+regression test pins down. It never carries decision provenance** —
+who decided something, when, in which session, or a quote of the
+product owner. Phrases like "direct user decision", "owner-directed",
+"caught live", "this session", and calendar dates are history, not
+constraints; history lives in `docs/SPEC.md`, `docs/adr/`, and
+`docs/goals/`. A comment may cite one of those by id or section
+(delivery-discipline.md's existing pointer rule), and that pointer is
+where a reader goes for the why. The test: delete the sentence — if
+the next maintainer loses nothing they'd need to safely change the
+code, it was narrative.
+
+For regression tests specifically: name the failure property, not the
+discovery story. "Regression: the preview's nested canvas captured
+page scroll" says what must keep passing; "caught live while building
+the Runs UI" says nothing a maintainer can use.
+
+Enforced by `scripts/check-comment-hygiene.sh`, run by lefthook
+(pre-commit) and CI's `comment-hygiene` job — the same
+one-script-both-callers shape as `check-loc.sh`, so the two can't
+drift. It deny-lists the known provenance phrases everywhere in
+hand-written `.go`/`.ts`/`.tsx` files, and calendar dates on comment
+lines only (dates inside code/string literals — test fixtures — are
+legitimate). A genuine false positive (a real domain concept named
+"owner", say) may carry `comment-hygiene:allow` on the same line;
+never use the marker to smuggle actual provenance past the gate.

.github/workflows/ci.yml

@@ -88,6 +88,16 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - run: ./scripts/check-loc.sh
 
+  # Mirrors lefthook.yml's own comment-hygiene job -- same script
+  # (.claude/rules/comments.md is the standard it enforces). Grep-only,
+  # so like file-loc-limit it needs no build setup and no changes gate.
+  comment-hygiene:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - run: ./scripts/check-comment-hygiene.sh
+
   # Mirrors lefthook.yml's own rules-frontmatter job -- same script.
   # Catches a real bug class: a .claude/rules/*.md with an invalid
   # frontmatter key (e.g. a `globs:` typo instead of `paths:`) silently
@@ -402,6 +412,7 @@ jobs:
     needs:
       - changes
       - file-loc-limit
+      - comment-hygiene
       - rules-frontmatter
       - root-file-naming
       - frontend

docs/goals/BACKLOG.md

@@ -28,6 +28,15 @@ backlog section in the same commit: **work discovered mid-session that
 outlives the session gets a goal file and a queue position before the
 session ends — never left only in an ephemeral session task list.**
 
+**Group E — Public-repo hygiene (2026-08-13, owner-directed: source
+comments explain code per standard practice — business/product
+decisions and the owner's own words live in docs/, cited by id, never
+inline in source)**
+1. [x] [0038 — Comment hygiene: constraints, not narrative](archive/0038-comment-hygiene.md) — delivered 2026-08-13
+   — rule (`.claude/rules/comments.md`) + gate
+   (`check-comment-hygiene.sh`, lefthook + CI `comment-hygiene` job in
+   `ci-gate`) + one sweep of the 65 baseline narrative comments
+
 **Group D — Trust the substrate (2026-08-11, owner-mandated: "do it
 properly once"; ordered first because everything else ships through
 this pipeline and on this code)**

docs/goals/archive/0038-comment-hygiene.md

@@ -0,0 +1,34 @@
+# Goal 0038 — Comment hygiene: constraints, not narrative
+
+**Goal.** Source comments state technical constraints only. Decision
+provenance — owner quotes, "direct user decision", "caught live",
+"this session", calendar dates — moves out of `.go`/`.ts`/`.tsx`
+files entirely; the reasoning already lives in `docs/SPEC.md`,
+`docs/adr/`, and `docs/goals/`, and a comment cites those by id when
+the why matters. Owner-directed 2026-08-13, generalizing the earlier
+public-context scrub (`fix/public-context-scrub`) into a standing,
+enforced standard now that the repo is public.
+
+**Plan.**
+1. `.claude/rules/comments.md` — the standard (loads unconditionally,
+   no `paths` frontmatter).
+2. `scripts/check-comment-hygiene.sh` — deny-list gate over
+   hand-written source (provenance phrases anywhere; calendar dates on
+   comment lines only), wired into lefthook pre-commit AND a CI
+   `comment-hygiene` job required by `ci-gate`, in the same change
+   (CI-from-day-one constraint). Same one-script-two-callers shape as
+   `check-loc.sh`.
+3. One sweep of the 65 baseline violations: keep each comment's
+   technical constraint, drop the narrative, add a `docs/` citation
+   where the reasoning lives elsewhere. Regression-test comments name
+   the pinned property, not the discovery story.
+
+**Acceptance** (checkable predicates)
+- [x] `./scripts/check-comment-hygiene.sh` exits 0 on the full tree.
+- [x] `.claude/rules/comments.md` exists, frontmatter check passes.
+- [x] lefthook.yml and ci.yml both run the script; `ci-gate` lists the
+      CI job in `needs`.
+- [x] No technical information lost: every rewritten comment still
+      states the constraint or property the original did (review
+      check, not grep).
+- [x] Full local suite green; goal PR merged with `ci-gate` green.

frontend/e2e/authoring-validation.spec.ts

@@ -5,9 +5,9 @@ import { clickRowAction } from './inventoryRow'
 // (errors block save, warnings never do), driven through the real
 // canvas -- not just the Go-level ValidateGraph/ValidateGraphStrict
 // unit tests (internal/domain/composition/graph_test.go). Covers the
-// three acceptance scenarios named in goal 0008: (a) the owner's own
-// demonstrated repro (a workflow whose root isn't a Trigger) can no
-// longer save, with the error named in the issues panel; (b) a
+// three acceptance scenarios named in goal 0008: (a) a workflow whose
+// root isn't a Trigger can no longer save, with the error named in
+// the issues panel; (b) a
 // trigger-rooted workflow ending in a Process leaf saves anyway, with
 // a visible warning on both the toolbar badge and the node itself, and
 // clicking the panel row selects that node; (c) an existing seeded
@@ -108,7 +108,7 @@ async function connectNodes(page: import('@playwright/test').Page, sourceLabel:
 // debounce + a real RPC) needs real slack beyond the debounce itself.
 const VALIDATION_TIMEOUT = 5_000
 
-test('The owner\'s repro: a workflow whose root is not a Trigger cannot be saved, with the error named in the issues panel', async ({ page }) => {
+test('A workflow whose root is not a Trigger cannot be saved, with the error named in the issues panel', async ({ page }) => {
   await page.goto('/')
   await page.getByRole('link', { name: 'Workflows' }).click()
   await page.getByTestId('new-workflow').click()

frontend/e2e/composition-export-import.spec.ts

@@ -48,7 +48,7 @@ test('Importing a workflow file adds a new, independent workflow without touchin
     label: 'E2E imported workflow',
     description: 'Imported by an e2e test',
     // A Trigger root (docs/adr/0028) -- a lone Capture node alone is
-    // now the owner's own unsaveable repro.
+    // unsaveable.
     nodes: [
       { ID: 't', NodeTypeID: 'trigger-manual' },
       { ID: 'c', NodeTypeID: 'capture-clipboard-html' },

frontend/e2e/global-setup.ts

@@ -19,13 +19,13 @@ import { fileURLToPath } from 'node:url'
 const REPO_ROOT = path.resolve(fileURLToPath(new URL('.', import.meta.url)), '../..')
 
 // The output path lives under frontend/e2e/.build/, NOT the repo's
-// shared bin/ -- learned live 2026-08-11: bin/ is also where `task dev`
-// (and build/package's `clean` = rm -rf bin/) operate, so an e2e suite
-// and a dev loop running concurrently could destroy each other's
-// artifacts mid-flight (a suite lost its server binary mid-run: 91
-// spawn-ENOENT failures; a dev app lost its own .app bundle). A
-// dedicated, gitignored path removes the shared-artifact contention
-// structurally instead of trying to sequence the two loops.
+// shared bin/ -- bin/ is also where `task dev` (and build/package's
+// `clean` = rm -rf bin/) operate, so an e2e suite and a dev loop
+// running concurrently could destroy each other's artifacts mid-flight
+// (a suite losing its server binary mid-run means spawn-ENOENT
+// failures; a dev app losing its own .app bundle). A dedicated,
+// gitignored path removes the shared-artifact contention structurally
+// instead of trying to sequence the two loops.
 export default function globalSetup(): void {
   execFileSync('go', ['build', '-tags', 'server', '-o', 'frontend/e2e/.build/mill-server', '.'], {
     cwd: REPO_ROOT,

frontend/e2e/layout.spec.ts

@@ -83,11 +83,10 @@ test('the titlebar band\'s left segment tracks the sidebar column: it resizes an
   expect(sidebarBox).not.toBeNull()
   expect(Math.abs(sidebarBox!.width - collapsedLeftBox!.width)).toBeLessThan(2)
 
-  // (c) the toggle lives in the SIDEBAR's own top row, below the band
-  // (owner design 2026-08-11: the control sits next to the nav it
-  // controls; collapsed, the same slot is the Mill icon that swaps to
-  // this expand affordance on hover/focus). Its x stays inside the
-  // rail column.
+  // (c) the toggle lives in the SIDEBAR's own top row, below the band:
+  // the control sits next to the nav it controls; collapsed, the same
+  // slot is the Mill icon that swaps to this expand affordance on
+  // hover/focus. Its x stays inside the rail column.
   const toggleBox = await page.getByRole('button', { name: 'Expand navigation' }).boundingBox()
   expect(toggleBox).not.toBeNull()
   expect(toggleBox!.y).toBeGreaterThanOrEqual(collapsedLeftBox!.y + collapsedLeftBox!.height - 1)
@@ -154,10 +153,9 @@ test.describe('tab strip vs build badge', () => {
   test.use({ viewport: { width: 1000, height: 800 } })
 
   test('the tab-strip overflow button is clickable with the build badge present, and the badge lives inside the band', async ({ page }) => {
-  // Regression coverage for the live-caught overlay bug (2026-08-11):
-  // the build-identity badge was position:fixed at the window's
-  // top-right, exactly over the tab strip's pinned "All open tabs" ⌄
-  // button, and intercepted its clicks -- the same overlay-blocks-chrome
+  // Regression: a position:fixed build-identity badge at the window's
+  // top-right sat exactly over the tab strip's pinned "All open tabs" ⌄
+  // button and intercepted its clicks -- the same overlay-blocks-chrome
   // class the isolated-data ribbon already hit once with the sidebar
   // toggle. The fix makes the badge a flex participant in the band's
   // own right segment, so overlap is impossible by construction.

frontend/e2e/workflow-hover-preview.spec.ts

@@ -29,7 +29,7 @@ test('Hovering the child-workflow NODE previews the child without blanking the p
   // The child's real layout renders (its own React Flow instance with
   // its three nodes), not just a text summary.
   await expect(preview.locator('.react-flow__node')).toHaveCount(3)
-  // Regression (caught live): the preview's nested React Flow used to
+  // Regression: the preview's nested React Flow used to
   // join the parent canvas's store and EMPTY it -- the parent's two
   // nodes must still be on its canvas while the preview is open
   // (the overlay portals outside the tabpanel, so this scope only

frontend/playwright.config.ts

@@ -55,11 +55,10 @@ export default defineConfig({
   // Playwright's own default reporter (list locally, dot in CI) never
   // writes a report to disk -- ci.yml's e2e job already expects one at
   // frontend/playwright-report on failure (its own upload-artifact
-  // step), but with no reporter configured that path never existed,
-  // confirmed directly against a real failed CI run (2026-08-11's
-  // Linux-e2e investigation): "No files were found with the provided
-  // path" swallowed the one artifact that would have shown per-failure
-  // screenshots/traces instead of bare text logs. `open: 'never'` so a
+  // step), but with no reporter configured that path never existed:
+  // "No files were found with the provided path" swallowed the one
+  // artifact that would have shown per-failure screenshots/traces
+  // instead of bare text logs. `open: 'never'` so a
   // local `npx playwright test` run never pops a browser tab
   // mid-session.
   reporter: [['html', { open: 'never' }], ['list']],