refactor(comments): exempt TSDoc tags, drop test carve-outs, strip obvious comments

GEN-004 was measuring the wrong thing: a flat prose bound made TSDoc tags
compete with the summary for budget, so an earlier sweep dissolved 8 @param
tags and an @example into prose. Three changes fix that.

1. Structured documentation is exempt. A structural TSDoc tag (@param,
   @returns, @throws, @example, @see, @typeparam, ...) opens a section that
   does not count toward the 5-line bound — its length tracks the API
   surface, not narrative. Prose containers (@remarks, @description,
   @notes, @todo, @fixme) still count, so relabelling narrative cannot buy
   budget. Implemented identically in both layers.

2. No directory-level carve-outs. The tests/** size exemption and the
   tests/fixtures/** full exemption are gone from .oxlintrc.json and the
   companion rules file; the ADR now records that any future exemption
   belongs in the ADR, not in lint config. Removing them surfaced only 10
   blocks and zero narration, because the tag exemption covers the reason
   test comments legitimately grow.

3. Obvious comments removed. A 12-agent sweep over 238 files deleted 248
   comments that restate the code they sit above, keeping every comment
   carrying a why, an invariant, a footgun, a security property, or a
   pointer. Verified by diffing ADR references, issue links, and TSDoc tags
   per file: no net loss anywhere except duplicate copies of one upstream
   bug link.

Also restores the tags the earlier sweep dissolved, syncs rules-shim.ts
(the user-facing rules.d.ts) with formats/rules.ts, and rescues the CLI
perf baselines into agent memory.

Signed-off-by: Rhuan Barreto <rhuan@barreto.work>

Author: rhuanbarreto

.archgate/adrs/ARCH-005-testing-standards.rules.ts

@@ -9,7 +9,6 @@ export default {
       description: "Test directory structure should mirror src/ structure",
       severity: "error",
       async check(ctx) {
-        // Get all src modules (non-index, non-cli.ts)
         const srcFiles = await ctx.glob("src/**/*.ts");
         const testFiles = await ctx.glob("tests/**/*.test.ts");
 

.archgate/adrs/ARCH-007-cross-platform-subprocess-execution.rules.ts

@@ -10,7 +10,6 @@ export default {
           (f) => !f.includes("tests/") && !f.includes(".archgate/")
         );
 
-        // Check for Bun.$ template literal usage
         const bunShellMatches = await Promise.all(
           files.map((file) => ctx.grep(file, /Bun\.\$`/u))
         );
@@ -26,7 +25,6 @@ export default {
           }
         }
 
-        // Check for $ import from "bun" (the shell API)
         const dollarImportMatches = await Promise.all(
           files.map((file) =>
             ctx.grep(file, /import\s*\{[^}]*\$[^}]*\}\s*from\s*["']bun["']/u)
@@ -44,7 +42,6 @@ export default {
           }
         }
 
-        // Check for await $` pattern (destructured $ usage)
         const destructuredMatches = await Promise.all(
           files.map((file) => ctx.grep(file, /await\s+\$`/u))
         );

.archgate/adrs/ARCH-008-typed-command-options.rules.ts

@@ -11,8 +11,7 @@
  * Description strings that enumerate a fixed set of values, e.g.
  * "editor integration to configure (claude, cursor, vscode, copilot)" or
  * "ADR domain: backend, frontend, data, architecture, general".
- * Same heuristic as the previous regex rule, but applied to the parsed
- * Literal VALUE rather than raw source text.
+ * Matched against the parsed Literal VALUE, not raw source text.
  */
 const CHOICE_ENUMERATION = /(?:claude.*cursor|backend.*frontend)/u;
 

.archgate/adrs/ARCH-012-command-error-boundaries.rules.ts

@@ -147,7 +147,6 @@ export default {
         "Async command actions must include try-catch error boundaries",
       severity: "warning",
       async check(ctx) {
-        // Only check non-index command files
         const files = ctx.scopedFiles.filter(
           (f) => f.includes("commands/") && !f.endsWith("index.ts")
         );
@@ -229,15 +228,13 @@ export default {
       description:
         "Catch blocks in async command actions must re-throw ExitPromptError for proper Ctrl+C handling (exit 130)",
       async check(ctx) {
-        // Only check non-index command files that have async actions
         const files = ctx.scopedFiles.filter(
           (f) => f.includes("commands/") && !f.endsWith("index.ts")
         );
 
         const checks = files.map(async (file) => {
           const content = await ctx.readFile(file);
 
-          // Only check files with async actions that have try-catch
           const hasAsyncActionWithTryCatch =
             /\.action\(\s*async\s[\s\S]*?\btry\s*\{/u.test(content);
           if (!hasAsyncActionWithTryCatch) return;

.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts

@@ -35,7 +35,6 @@ export default {
           commandNames.add(name);
         }
 
-        // Collect docs stems.
         const docFiles = await ctx.glob(`${DOCS_DIR}/*.mdx`);
         const docStems = new Set<string>();
         for (const file of docFiles) {

.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts

@@ -16,16 +16,13 @@ export default {
         // is checked: deeper files like adr/domain/add.ts are sub-subcommands
         // documented as a table in the parent's section, not as headings.
 
-        // Find all parent command groups (dirs with an index.ts).
         const groupIndexFiles = await ctx.glob(`${COMMANDS_DIR}/*/index.ts`);
 
-        // Extract parent names from index files.
         const parentNames = groupIndexFiles.map((indexFile) => {
           const rel = indexFile.slice(COMMANDS_DIR.length + 1);
           return rel.split("/")[0];
         });
 
-        // Discover subcommands for all parents in parallel.
         const subResults = await Promise.all(
           parentNames.map(async (parentName) => {
             const [subFiles, nestedGroupFiles] = await Promise.all([
@@ -35,7 +32,6 @@ export default {
 
             const subs = new Set<string>();
 
-            // Single-file subcommands
             for (const sf of subFiles) {
               const fileName = sf.slice(
                 `${COMMANDS_DIR}/${parentName}/`.length
@@ -44,7 +40,6 @@ export default {
               subs.add(fileName.slice(0, -".ts".length));
             }
 
-            // Nested command groups
             for (const ngf of nestedGroupFiles) {
               const nestedRel = ngf.slice(
                 `${COMMANDS_DIR}/${parentName}/`.length
@@ -68,7 +63,6 @@ export default {
         //                          ### archgate adr domain
         const headingPattern = /^#{1,4}\s+.*archgate\s+(\S+)\s+(\S+)/giu;
 
-        // Read all docs files in parallel.
         const docsResults = await Promise.all(
           [...subcommandsByParent.entries()].map(
             async ([parentName, subNames]) => {
@@ -85,7 +79,6 @@ export default {
           )
         );
 
-        // Report violations.
         for (const {
           parentName,
           subNames,
@@ -94,7 +87,6 @@ export default {
         } of docsResults) {
           if (docsContent === null) continue;
 
-          // Extract documented subcommand names from headings
           const documentedSubs = new Set<string>();
           let match;
           headingPattern.lastIndex = 0;

.archgate/adrs/ARCH-022-ast-aware-rule-context.rules.ts

@@ -72,8 +72,8 @@ export default {
             }
             return;
           }
-          // Fallback: inline `ast(path, language) { … }` object method, in
-          // case the implementation is ever moved back onto the object.
+          // Fallback: inline `ast(path, language) { … }` object method, for
+          // an implementation that lives directly on the returned object.
           if (n.type === "Property") {
             const key = n.key as (EsTreeNode & { name?: string }) | undefined;
             const value = n.value as EsTreeNode | undefined;

.archgate/adrs/CI-001-pin-github-actions-by-hash.rules.ts

@@ -42,7 +42,6 @@ export default {
         );
 
         for (const m of matches) {
-          // Extract the full `uses:` value from the matched line
           const usesMatch = m.content.match(
             /uses:\s+(?!\.\/|docker:\/\/)(\S+@\S+)/u
           );

.archgate/adrs/GEN-002-docs-i18n.rules.ts

@@ -9,7 +9,6 @@ const LOCALES = ["pt-br", "nb"];
 
 const CONTENT_ROOT = "docs/src/content/docs";
 
-/** Patterns that match locale-prefixed internal links in MDX files. */
 const LOCALE_LINK_PATTERNS = LOCALES.map(
   (locale) => new RegExp(`(?:href="|\\]\\()/${locale}/`, "gu")
 );
@@ -53,7 +52,6 @@ export default {
       async check(ctx) {
         const allMdxFiles = await ctx.glob(`${CONTENT_ROOT}/**/*.mdx`);
 
-        // Separate root files from locale files
         const rootFiles: string[] = [];
         const localeFiles = new Map<string, string[]>();
 
@@ -128,7 +126,6 @@ export default {
 
         if (changedRootFiles.length === 0) return;
 
-        // Pre-build a set of all existing locale files for fast lookup
         const localeFileArrays = await Promise.all(
           LOCALES.map((locale) =>
             ctx.glob(`${CONTENT_ROOT}/${locale}/**/*.mdx`)

.archgate/adrs/GEN-003-tool-invocation-via-scripts.rules.ts

@@ -13,7 +13,6 @@ export default {
         "Lint/format tools must be invoked via package.json scripts, not bunx/npx",
       severity: "error",
       async check(ctx) {
-        // Build an alternation like (prettier|oxfmt|oxlint|eslint|biome).
         const toolGroup = LINT_FORMAT_TOOLS.join("|");
         // Match `bunx <tool>` or `npx <tool>`, allowing flags between the
         // runner and the tool name (e.g. `bunx --bun oxfmt`).