deepseek-harness/examples/desktop/tools/comment-sweep-rules.md

# comment-sweep — classification rules

Owner: `lane-fresh-eyes-p0`  Status: DRAFT for team-lead review before baseline
lands.  Scope: `src/main/**`, `src/preload/**`, `src/renderer/**` (`.js` only;
tests intentionally out — test names carry ticket anchors used for the
regression audit trail).

## Bucket contract

Every scan hit lands in one of three buckets:

- **keep-stripped** — the surrounding comment carries a real constraint (why
  this order matters, what state exists, which wire contract is honored).
  Only the *artifact-reference prefix* is removed.  The sentence that follows
  is preserved verbatim, minus grammatical stitching (leading colon, spaces,
  connective particles).
- **delete-line** — the entire comment line is a process narrative that
  carries no invariant.  Remove the line, close the gap.
- **delete-block** — a multi-line comment whose SOLE purpose is process
  narrative (e.g. a header repeating "this file was refactored per §X.Y").
  Remove the whole `/* … */` or contiguous `// … // …` run.
- **skip** — do not touch.  See §Skip below.

## Family → default action

The scanner emits 18 families.  Defaults, each overridable per-hit during
review:

| family              | default action  | notes |
|---------------------|-----------------|-------|
| fresh-eyes-p0       | keep-stripped   | strip `Fresh-eyes P0 (date, review-fresh-eyes.md #N):` |
| fresh-eyes-plain    | keep-stripped   | strip `Fresh-eyes P0:` prefix |
| review-md-ref       | keep-stripped   | strip `(review-*.md #N)` parenthetical |
| ticket-letter       | keep-stripped   | strip `Ticket A/B/…:` — retain the constraint |
| ticket-num          | keep-stripped   | strip `Ticket #NNN:` — retain the constraint |
| task-num            | keep-stripped   | strip `task #NNN` mentions — retain the constraint |
| bare-hash-num       | context-dependent | if it's the only anchor a reader has for context (e.g. `#93` names a *design tension* explained elsewhere), keep the hash but note "kernel ticket #93" style — otherwise strip |
| round-shot          | keep-stripped   | drop `(QA round-N shot NN)` parenthetical |
| shot-num            | keep-stripped   | drop `shot NN` |
| rec-num             | keep-stripped   | strip `rec 22-bis` etc. |
| team-lead-ref       | keep-stripped   | strip `team-lead §X.Y` prefix — retain the described rule |
| boss-delta          | keep-stripped   | strip `老板实测 delta` / `205-Δ3` |
| date-prefix         | keep-stripped   | strip leading `YYYY-MM-DD` on comments whose body still makes sense without the date; delete-line if the date IS the whole comment |
| internal-doc-ref    | keep-stripped   | all internal-doc refs are stripped: `density-spec §N`, `style-guide §N`, `pi-agent-ui-study.md`, `LangSmith study §N rec M`, `trace-parity batch`, `trace-viz §N` — the OSS release pipeline excludes docs/design-refs/, so references would 404 for readers (team-lead 2026-07-18) |
| finding-letter      | keep-stripped   | `F-1 / F-2 / F-3 / F-4` are audit-round codes, strip |
| upstream-path       | keep-stripped   | `packages/foo/bar.ts:33-52` → replace with a concept name ("wire protocol v2 (`session/interrupt`)") — reader has no access to that path |
| phase-of-rec        | keep-stripped   | strip `phase N (pi/rec/task)` |
| port-audit          | keep-stripped   | strip `port 9224 wire audit` — the constraint isn't tied to a port number |
| e2e-audit           | keep-stripped   | strip `e2e audit` marker |
| audit-batch         | keep-stripped   | strip `Clickability audit D3` / `hygiene batch task 3` |

## Skip

Do not touch:

1. Any file NOT under `src/main/`, `src/preload/`, `src/renderer/`.
2. Test files (already excluded from the scan by SCAN_DIRS).
3. Any comment whose text is inside a string literal (`extractComments`
   already guards this).
4. Any hit where the artifact reference IS the identifier ("kernel `#218`"
   naming a specific PR whose numeric identity is the meaningful concept
   the reader needs — mark `bare-hash-num` skip per-case).
5. Any header banner comment at line 1 that documents the file's PUBLIC
   contract (imports, exported functions, module role) — even if it mentions
   a ticket, the reader wanted the file overview.  Strip only the ticket
   reference from within, don't touch the banner shape.

## Stripping recipe (mechanical)

The stripper reads a keep-stripped line and applies the following in order.
Each step is a pure text transform on the comment text (not the leading
`//` / ` * ` prefix — those are preserved to keep the block-comment shape).

```
1. Drop leading parenthetical  ^\s*\(([\w §.,#/-]+?)\)\s*[:—-]?\s*
   IF the parenthetical is composed entirely of family patterns.
2. Drop leading artifact-prefix + delimiter:
     ^\s*(Fresh-eyes P0[^:]*:\s*)
     ^\s*(Ticket #?\w+[^:]*:\s*)
     ^\s*(task #\d+[^:]*:\s*)
     ^\s*(F-\d+ \([^)]+\):\s*)
     ^\s*(20\d{2}-\d{2}-\d{2}\s*[·—-]?\s*)
     ^\s*(rec \d+[- ]?bis[^:]*:\s*)
     ^\s*(team[- ]lead §[\d.]+[^:]*:\s*)
3. Drop trailing artifact suffix:
     \s*\((?:round-\d+ ?shot ?\d+|QA round-\d+|review-[a-z-]+\.md #\d+|Ticket [A-Z#\d]+|task #\d+|Fresh-eyes P0)[^)]*\)\s*$
4. Collapse remaining "(task #N):"/"(#NNN)"/"(§X)" fragments in the middle
   of the sentence by dropping the parenthetical only, keeping the rest.
5. Normalise whitespace: trim, collapse multi-space, ensure one trailing
   line-ending style match.
6. If the remaining text is empty → mark for delete-line.
7. If the remaining text is a fragment (starts with lowercase and lacks a
   verb) → prepend a period-and-capital shim ONLY when the original had a
   sentence-starting shape; otherwise keep the fragment as-is (many are
   header labels like `-- forkChildLabel readability fix ----`).
```

Steps 1-4 are the load-bearing ones.  Step 5-7 are conservative — if in
doubt, leave the line to the human bucket pass.

## Two-commit split (per team-lead brief)

- **Commit A** — `src/main/*.js` + `src/preload/*.js` only.  ~13 files.
  Explicit `git add src/main/... src/preload/preload.js` per file.
  Message: `chore(comment-sweep): main+preload artifact-reference strip`
  followed by the per-family counters and total lines touched.
- **Commit B** — `src/renderer/*.js` only.  ~50 files.  Explicit git add.
  Message: `chore(comment-sweep): renderer artifact-reference strip`
  followed by the per-family counters and total lines touched.

## Acceptance for each commit

1. `node --check` passes on every changed `.js` file.
2. `node --test 'test/*.test.js' 2>&1 | tail -5` shows the same pass count
   as baseline (regression: 0 tests changed).
3. `git diff -w --stat` line count == count of stripped comment lines +
   count of deleted comment lines.  `git diff -w` output contains NO source
   lines (only lines starting with `-` or `+` inside a comment context).
4. Per-file `git show --stat` audit line: no file gains code or loses code;
   the sole shape of any diff hunk is comment-line change.
5. Commit message carries the per-family stats produced by
   `node tools/comment-sweep-scan.js --stats` before → after.

## Machine-readable classification

The classification bucket for every hit is stored in
`tools/comment-sweep-plan.jsonl` (one JSON object per line, keys:
`file`, `line`, `family`, `bucket`, `action`, `note`).  The mechanical
executor reads this and applies the strip recipe or deletion.  Any hit
whose bucket is `skip` or `human-review` is not touched.

## Reconciliation with test-real HEAD

The scan output above is against my worktree HEAD `6a44b8c` (branch
`fix/fresh-eyes-p0`).  The final baseline for this batch is test-real HEAD
AFTER `fix/oss-prep` + `fix/oss-clean` merge in.  Team-lead notifies when
that HEAD is ready.  Between now and then, the classification rules
themselves don't move; only the row set and line numbers do.  The
mechanical pass re-runs the scan on the new baseline and applies the
per-family rules; per-hit `human-review` decisions are re-matched by
(family, file, approximate line context).