From 9984ba10d1bbc96d0e91a68cf41863ab6def7b14 Mon Sep 17 00:00:00 2001 From: Sedge Date: Thu, 14 May 2026 10:34:07 -0500 Subject: [PATCH 1/2] docs: add comment marker preview --- README.md | 6 +++ site/assets/comment-marker-preview.svg | 53 +++++++++++++++++++++++ templates/README.md.tmpl | 6 +++ tools/build.py | 58 ++++++++++++++++++++++++++ 4 files changed, 123 insertions(+) create mode 100644 site/assets/comment-marker-preview.svg diff --git a/README.md b/README.md index 4d53be0..843eb86 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,12 @@ Use punctuation markers in comments to flag human judgment: | `??` | TODO, HACK | I'm uncertain | Purple (base0E) | | `>>` | NOTE, NB | See reference | Cyan (base0C) | +The VS Code/Cursor extension highlights the whole comment line as a rounded badge. Legacy keywords use the same colors as their punctuation marker, so `FIXME`/`BUG`/`XXX` look like `!!`, `TODO`/`HACK` look like `??`, and `NOTE`/`NB` look like `>>`. + +

+ Human++ comment marker preview showing FIXME, TODO, HACK, NOTE, NB, and explicit punctuation badges +

+ ```js // Regular comment stays calm (base03) diff --git a/site/assets/comment-marker-preview.svg b/site/assets/comment-marker-preview.svg new file mode 100644 index 0000000..16cbb59 --- /dev/null +++ b/site/assets/comment-marker-preview.svg @@ -0,0 +1,53 @@ + + Human++ comment marker preview + Preview of Human++ comment marker badges for explicit punctuation and legacy keyword aliases. + + + + + + + + marker-aliases.ts + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + + // Regular comment stays calm and low-contrast + + + // FIXME: payment retry can double-submit + !! + + + // BUG: cache invalidation skips deleted users + !! + + + // TODO: choose a better empty-state copy + ?? + + + // HACK: keep legacy slug routing alive for now + ?? + + + // NOTE: this mirrors the server-side validator + >> + + + // NB: redirects intentionally preserve the query string + >> + + + // !! Explicit punctuation always works too + !! + + Aliases are case-insensitive; strongest marker wins when multiple keywords appear. + diff --git a/templates/README.md.tmpl b/templates/README.md.tmpl index d703308..f412fe0 100644 --- a/templates/README.md.tmpl +++ b/templates/README.md.tmpl @@ -105,6 +105,12 @@ Use punctuation markers in comments to flag human judgment: | `??` | TODO, HACK | I'm uncertain | Purple (base0E) | | `>>` | NOTE, NB | See reference | Cyan (base0C) | +The VS Code/Cursor extension highlights the whole comment line as a rounded badge. Legacy keywords use the same colors as their punctuation marker, so `FIXME`/`BUG`/`XXX` look like `!!`, `TODO`/`HACK` look like `??`, and `NOTE`/`NB` look like `>>`. + +

+ Human++ comment marker preview showing FIXME, TODO, HACK, NOTE, NB, and explicit punctuation badges +

+ ```js // Regular comment stays calm (base03) diff --git a/tools/build.py b/tools/build.py index 9a68950..0349e20 100755 --- a/tools/build.py +++ b/tools/build.py @@ -1644,6 +1644,64 @@ def generate_svgs(colors, meta): (assets_dir / "preview-light.svg").write_text(preview_light) print(" ✓ site/assets/preview-dark.svg, preview-light.svg") + # Comment marker alias preview for issue triage / README clarity. + marker_preview = f''' + Human++ comment marker preview + Preview of Human++ comment marker badges for explicit punctuation and legacy keyword aliases. + + + + + + + + marker-aliases.ts + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + + // Regular comment stays calm and low-contrast + + + // FIXME: payment retry can double-submit + !! + + + // BUG: cache invalidation skips deleted users + !! + + + // TODO: choose a better empty-state copy + ?? + + + // HACK: keep legacy slug routing alive for now + ?? + + + // NOTE: this mirrors the server-side validator + >> + + + // NB: redirects intentionally preserve the query string + >> + + + // !! Explicit punctuation always works too + !! + + Aliases are case-insensitive; strongest marker wins when multiple keywords appear. + +''' + (assets_dir / "comment-marker-preview.svg").write_text(marker_preview) + print(" ✓ site/assets/comment-marker-preview.svg") + def generate_readme(colors, meta): From fa401e3291253c1e017713db37ecf58bab8edae6 Mon Sep 17 00:00:00 2001 From: Sedge Date: Thu, 14 May 2026 23:34:35 -0500 Subject: [PATCH 2/2] docs: complete comment marker preview coverage --- site/assets/comment-marker-preview.svg | 38 ++++++++++++++++---------- tools/build.py | 38 ++++++++++++++++---------- 2 files changed, 48 insertions(+), 28 deletions(-) diff --git a/site/assets/comment-marker-preview.svg b/site/assets/comment-marker-preview.svg index 16cbb59..8adb76a 100644 --- a/site/assets/comment-marker-preview.svg +++ b/site/assets/comment-marker-preview.svg @@ -1,7 +1,7 @@ - + Human++ comment marker preview Preview of Human++ comment marker badges for explicit punctuation and legacy keyword aliases. - + @@ -18,6 +18,8 @@ 6 7 8 + 9 + 10 // Regular comment stays calm and low-contrast @@ -29,25 +31,33 @@ // BUG: cache invalidation skips deleted users !! - - // TODO: choose a better empty-state copy - ?? + + // XXX: verify migration before rollout + !! - // HACK: keep legacy slug routing alive for now + // TODO: choose a better empty-state copy ?? - - // NOTE: this mirrors the server-side validator - >> + + // HACK: keep legacy slug routing alive for now + ?? - // NB: redirects intentionally preserve the query string + // NOTE: this mirrors the server-side validator >> - - // !! Explicit punctuation always works too - !! + + // NB: redirects intentionally preserve the query string + >> - Aliases are case-insensitive; strongest marker wins when multiple keywords appear. + + // !! Explicit punctuation always works too + !! + + + // >> Explicit context note stays visible + >> + + Aliases are case-insensitive; strongest marker wins when multiple keywords appear. diff --git a/tools/build.py b/tools/build.py index 0349e20..01e0fc2 100755 --- a/tools/build.py +++ b/tools/build.py @@ -1645,10 +1645,10 @@ def generate_svgs(colors, meta): print(" ✓ site/assets/preview-dark.svg, preview-light.svg") # Comment marker alias preview for issue triage / README clarity. - marker_preview = f''' + marker_preview = f''' Human++ comment marker preview Preview of Human++ comment marker badges for explicit punctuation and legacy keyword aliases. - + @@ -1665,6 +1665,8 @@ def generate_svgs(colors, meta): 6 7 8 + 9 + 10 // Regular comment stays calm and low-contrast @@ -1676,27 +1678,35 @@ def generate_svgs(colors, meta): // BUG: cache invalidation skips deleted users !! - - // TODO: choose a better empty-state copy - ?? + + // XXX: verify migration before rollout + !! - // HACK: keep legacy slug routing alive for now + // TODO: choose a better empty-state copy ?? - - // NOTE: this mirrors the server-side validator - >> + + // HACK: keep legacy slug routing alive for now + ?? - // NB: redirects intentionally preserve the query string + // NOTE: this mirrors the server-side validator >> - - // !! Explicit punctuation always works too - !! + + // NB: redirects intentionally preserve the query string + >> - Aliases are case-insensitive; strongest marker wins when multiple keywords appear. + + // !! Explicit punctuation always works too + !! + + + // >> Explicit context note stays visible + >> + + Aliases are case-insensitive; strongest marker wins when multiple keywords appear. ''' (assets_dir / "comment-marker-preview.svg").write_text(marker_preview)