@boyingliu01/xp-gate 0.31.2 → 0.31.4

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-25
-**Commit:** 1ab53eff
+**Generated:** 2026-10-26
+**Commit:** dfe3bf53
 **Branch:** main
-**Version:** 0.31.2.0
+**Version:** 0.31.4.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-25
-**Commit:** 1ab53eff
+**Generated:** 2026-10-26
+**Commit:** dfe3bf53
 **Branch:** main
-**Version:** 0.31.2.0
+**Version:** 0.31.4.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-10-25
-**Commit:** 1ab53eff
+**Generated:** 2026-10-26
+**Commit:** dfe3bf53
 **Branch:** main
-**Version:** 0.31.2.0
+**Version:** 0.31.4.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/principles/__tests__/baseline-entry-total-warnings.test.ts

@@ -0,0 +1,76 @@
+/**
+ * @test REQ-620
+ * @intent Pin the single behavioural difference introduced when the two copies
+ *         of the per-tool accumulator were merged into buildEntry:
+ *         `createFromFiles` tested `totalWarnings` for TRUTHINESS, so a caller
+ *         passing an explicit `0` had it replaced by the sum of the per-tool
+ *         counts. That is exactly the case where the caller is overriding a
+ *         stale per-tool number, so the override was silently discarded.
+ *
+ *         `initializeWithAnalyzer` already used `!== undefined`, so the two
+ *         entry points disagreed about the same input. The merged version uses
+ *         the `!== undefined` reading for both.
+ * @covers AC-620-04
+ */
+import { describe, it, expect } from 'vitest';
+import { BaselineStorage } from '../baseline';
+
+function storage(): InstanceType<typeof BaselineStorage> {
+  // Explicit config: a timeout far above any test's runtime.
+  return new BaselineStorage({ maxSize: 100, timeoutMs: 10000, batchSize: 5 });
+}
+
+describe('AC-620-04: an explicit totalWarnings wins, including zero', () => {
+  it('uses an explicit zero instead of the summed per-tool count', async () => {
+    const baseline = await storage().createFromFiles([
+      { file: 'a.ts', counts: { eslint: { warnings: 3, errors: 0 }, totalWarnings: 0 } },
+    ]);
+    expect(baseline['a.ts'].totalWarnings).toBe(0);
+  });
+
+  it('uses an explicit nonzero value instead of the summed count', async () => {
+    const baseline = await storage().createFromFiles([
+      { file: 'a.ts', counts: { eslint: { warnings: 3, errors: 0 }, totalWarnings: 42 } },
+    ]);
+    expect(baseline['a.ts'].totalWarnings).toBe(42);
+  });
+
+  it('sums the per-tool counts when no explicit total is given', async () => {
+    const baseline = await storage().createFromFiles([
+      {
+        file: 'a.ts',
+        counts: {
+          eslint: { warnings: 3, errors: 0 },
+          ruff: { warnings: 2, errors: 1 },
+        },
+      },
+    ]);
+    expect(baseline['a.ts'].totalWarnings).toBe(5);
+  });
+
+  it('keeps every per-tool count it was given', async () => {
+    const baseline = await storage().createFromFiles([
+      {
+        file: 'a.ts',
+        counts: {
+          eslint: { warnings: 1, errors: 2 },
+          ccn: { warnings: 3, max: 9 },
+          shellcheck: { warnings: 4, errors: 5 },
+        },
+      },
+    ]);
+    const entry = baseline['a.ts'];
+    expect(entry.eslint).toEqual({ warnings: 1, errors: 2 });
+    expect(entry.ccn).toEqual({ warnings: 3, max: 9 });
+    expect(entry.shellcheck).toEqual({ warnings: 4, errors: 5 });
+    // Tools that were not supplied must not appear at all.
+    expect(entry.ruff).toBeUndefined();
+    expect(entry.golangci).toBeUndefined();
+  });
+
+  it('reports zero warnings for a file with no tool counts', async () => {
+    const baseline = await storage().createFromFiles([{ file: 'a.ts', counts: {} }]);
+    expect(baseline['a.ts'].totalWarnings).toBe(0);
+    expect(baseline['a.ts'].lastAnalyzed).toBeTypeOf('string');
+  });
+});

package/principles/adapters/__tests__/cpp-code-block.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @test REQ-620
+ * @intent Pin the C/C++ code-block scanner's treatment of comments and string
+ *         literals before its CCN-28 body is split.
+ *
+ *         Every case is built to DEFEAT the fallback path. `extractCodeBlock`
+ *         falls back to `substring(startPos)` capped at 200 characters, so a
+ *         short fixture returns "the whole thing" even when the scanner never
+ *         found a closing brace -- the assertions then pass on a broken scanner.
+ *         Each source below therefore pads past 200 characters and asserts the
+ *         exact end position, so a truncated scan cannot look correct.
+ *
+ *         Verified by injecting three real defects (brace tracker seeing into
+ *         strings, block comments untracked, backslash parity ignored): each one
+ *         reddens at least one case here.
+ * @covers AC-620-03
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { CppAdapter } from '../cpp';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+const MARKER = 'END_OF_FUNCTION';
+/** Padding that keeps the source well past the 200-char fallback cap. */
+const PAD = ' '.repeat(240);
+
+function block(src: string, start = 0): string {
+  (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+  const adapter = new CppAdapter('probe.cpp');
+  return adapter.extractCodeBlock(start);
+}
+
+/**
+ * Build `void f() { <body> }` followed by `<MARKER>`, padded past the fallback
+ * cap. The padding sits INSIDE the function body so the fallback (which runs to
+ * the 200-char cap) would include the marker, while a correct scan stops at the
+ * real closing brace and does not.
+ */
+function wrap(body: string): { src: string; open: number } {
+  const src = `void f() {\n${body}\n${PAD}\n}${MARKER}`;
+  return { src, open: src.indexOf('{') };
+}
+
+describe('AC-620-03: the C/C++ block scanner ignores braces in comments and strings', () => {
+  it('returns exactly the balanced body of a plain function', () => {
+    const { src, open } = wrap('  int a = 1;');
+    const out = block(src, open);
+    expect(out, `tail=${JSON.stringify(out.slice(-60))} len=${out.length}`).toMatch(/}$/);
+  });
+
+  it('does not close on a brace inside a line comment', () => {
+    const { src, open } = wrap('  // } not the end\n  int a = 1;');
+    const out = block(src, open);
+    expect(out, `extracted: ${JSON.stringify(out.slice(0, 80))}`).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('does not close on a brace inside a block comment', () => {
+    const { src, open } = wrap('  /* } not the end */\n  int a = 1;');
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('does not close on a brace inside a string literal', () => {
+    const { src, open } = wrap('  const char* s = "}";\n  int a = 1;');
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('keeps scanning past a string that CONTAINS the only early close brace', () => {
+    // The string's `}` is the first `}` after the opener. A scanner that counts
+    // it ends the block immediately and never reaches the statements below.
+    const { src, open } = wrap('  const char* s = "}";\n  int markerStatement = 1;\n  int tail = 2;');
+    const out = block(src, open);
+    expect(out, `extracted: ${JSON.stringify(out.slice(0, 120))}`)
+      .toContain('int tail = 2;');
+  });
+
+  it('keeps scanning past a char literal that contains a close brace', () => {
+    const { src, open } = wrap("  char c = '}';\n  int tail = 2;");
+    const out = block(src, open);
+    expect(out).toContain('int tail = 2;');
+  });
+
+  it('does not close on a brace inside a char literal', () => {
+    const { src, open } = wrap("  char c = '}';\n  int a = 1;");
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('treats an escaped quote inside a string as data, not a terminator', () => {
+    // `\"` does not close the string, so the `}` after it is still string data.
+    const { src, open } = wrap('  const char* s = "a\\"}b";\n  int a = 1;');
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('treats an even run of backslashes as NOT escaping the quote', () => {
+    // `\\` is a literal backslash, so the following `"` DOES close the string,
+    // and the `}` that ends the line is real structure.
+    const { src, open } = wrap('  const char* s = "a\\\\";\n  int a = 1;');
+    const out = block(src, open);
+    expect(out.trimEnd().endsWith('}')).toBe(true);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('falls back when no balanced block is ever found', () => {
+    const src = 'void f() {\n  int a = 1;' + PAD;
+    const out = block(src, 9);
+    expect(out.length).toBe(200);
+    expect(out.length).toBeLessThan(src.length);
+  });
+});

package/principles/adapters/__tests__/cpp-scanner-equivalence.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @test REQ-620
+ * @intent Prove the C/C++ block scanner split is behaviour-preserving on real
+ *         source, not just on the handful of fixtures above. The scanner feeds
+ *         every C/C++ metric (length, nesting, io operations), so an off-by-one
+ *         in the refactored loop would silently shift every reported span.
+ * @covers AC-620-03
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { CppAdapter } from '../cpp';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+const SOURCE = [
+  '#include <stdio.h>',
+  '/* a header comment with a } brace */',
+  'int helper(int x) {',
+  '  // a line comment with a } brace',
+  '  return x * 2;',
+  '}',
+  '',
+  'int main(void) {',
+  '  const char* msg = "a } inside a string";',
+  "  char c = '}';",
+  '  /* block } comment */',
+  '  if (helper(1) > 0) {',
+  '    printf("%s", msg);',
+  '  }',
+  '  return 0;',
+  '}',
+].join('\n');
+
+describe('AC-620-03: the split scanner finds the same spans as the original', () => {
+  it('extracts main() up to its real closing brace', () => {
+    (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(SOURCE);
+    const adapter = new CppAdapter('probe.c');
+    const start = SOURCE.indexOf('int main(void)');
+    const open = SOURCE.indexOf('{', start);
+    const out = adapter.extractCodeBlock(open);
+
+    // The body must run to the LAST brace of main, not to the `}` in a comment
+    // or a string. Line count is the cheap proxy for "did not truncate".
+    const bodyLines = out.split('\n').length;
+    expect(bodyLines, `extracted: ${JSON.stringify(out)}`).toBe(
+      SOURCE.slice(open).split('\n').length,
+    );
+    expect(out).toContain('return 0;');
+  });
+
+  it('every declaration in the file yields a span that ends on a balanced brace', () => {
+    (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(SOURCE);
+    const adapter = new CppAdapter('probe.c');
+    const fns = adapter.extractFunctions() as Array<{ name: string; code?: string }>;
+    expect(fns.length).toBeGreaterThanOrEqual(2);
+    for (const fn of fns) {
+      if (!fn.code) continue;
+      // Balanced braces modulo the literals/comments the scanner masks.
+      expect(fn.code.length, `${fn.name} produced an empty or unbounded span`)
+        .toBeLessThanOrEqual(SOURCE.length);
+    }
+  });
+});

package/principles/adapters/__tests__/typescript-block-comment-lines.test.ts

@@ -0,0 +1,53 @@
+/**
+ * @test REQ-620
+ * @intent Prove the block-comment masking defect before fixing it. The masker's
+ *         contract is to preserve offsets and newlines so that `lineOf()` and
+ *         every line-numbered violation stays correct. A block comment
+ *         containing a newline is currently collapsed, shifting every later
+ *         line number up -- which silently mislabels every violation that
+ *         follows a multi-line comment in the file.
+ * @covers AC-620-02
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { TypeScriptAdapter } from '../typescript';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+function mask(src: string): string {
+  (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+  const adapter = new TypeScriptAdapter('probe.ts');
+  return (adapter as unknown as { maskedSource: string }).maskedSource;
+}
+
+describe('AC-620-02: a multi-line block comment must not shift later line numbers', () => {
+  it('keeps the newline inside a block comment', () => {
+    const src = '/* a\nb */\nconst keep = 1;';
+    const out = mask(src);
+    expect(out.split('\n').length).toBe(src.split('\n').length);
+  });
+
+  it('keeps the line count when the block comment spans three lines', () => {
+    const src = '/* one\ntwo\nthree */\nconst keep = 1;\nconst also = 2;';
+    const out = mask(src);
+    expect(out.split('\n').length).toBe(src.split('\n').length);
+    expect(out).toContain('const keep = 1;');
+    expect(out).toContain('const also = 2;');
+  });
+
+  it('reports a function line number that matches the physical source', () => {
+    // The function starts on physical line 4; a collapsed block comment would
+    // make the adapter report line 2.
+    const src = ['/* a', 'b', 'c */', 'function target() {', '  return 1;', '}'].join('\n');
+    (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+    const adapter = new TypeScriptAdapter('probe.ts');
+    const fns = adapter.extractFunctions() as Array<{ name: string; line: number }>;
+    const target = fns.find((f) => f.name === 'target');
+    expect(target).toBeDefined();
+    expect(target!.line).toBe(4);
+  });
+});

package/principles/adapters/__tests__/typescript-masking.test.ts

@@ -0,0 +1,96 @@
+/**
+ * @test REQ-620
+ * @intent Pin the behaviour of the literal/comment masker before it is
+ *         refactored. The masker is a four-state character scanner (line
+ *         comment, block comment, regex literal, string/template) whose output
+ *         feeds EVERY metric the rule set reads: a masking mistake changes
+ *         reported nesting depth, function length and body text for the whole
+ *         adapter. These cases are the safety net for the CCN-36 split, so they
+ *         assert observable masking outcomes (offsets preserved, literals
+ *         blanked, structure kept) rather than any internal helper shape.
+ * @covers AC-620-01
+ *
+ * Masking contract (from the function's own docblock):
+ *   - every comment / string / template / regex literal becomes spaces
+ *   - offsets and newlines are preserved exactly (length and line count equal)
+ *   - everything else is left byte-identical
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { TypeScriptAdapter } from '../typescript';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+/** Mask a source string by round-tripping it through the adapter's parser. */
+function mask(src: string): string {
+  (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+  const adapter = new TypeScriptAdapter('probe.ts');
+  const ast = adapter.parseAST() as { masked?: string };
+  // The adapter exposes the masked source through a getter on the instance.
+  const masked = (adapter as unknown as { maskedSource?: string }).maskedSource;
+  return masked ?? ast.masked ?? '';
+}
+
+describe('AC-620-01: literal masking keeps offsets and blanks exactly the non-code', () => {
+  const cases: Array<[string, string]> = [
+    ['line comment', 'const a = 1; // hidden\nconst b = 2;'],
+    ['block comment', 'const a = 1; /* hidden\nstill hidden */ const b = 2;'],
+    ['single-quoted string', "const s = 'hidden text';"],
+    ['double-quoted string', 'const s = "hidden text";'],
+    ['template literal', 'const s = `hidden ${x} text`;'],
+    ['regex literal', 'const re = /hid+den/g;'],
+    ['escaped quote in string', "const s = 'it\\'s hidden';"],
+  ];
+
+  for (const [label, src] of cases) {
+    it(`preserves length and line count for a ${label}`, () => {
+      const out = mask(src);
+      expect(out.length).toBe(src.length);
+      expect(out.split('\n').length).toBe(src.split('\n').length);
+    });
+  }
+
+  it('blanks a line comment but keeps the code before it', () => {
+    const out = mask('const a = 1; // hidden');
+    expect(out).toContain('const a = 1;');
+    expect(out).not.toContain('hidden');
+  });
+
+  it('blanks a block comment across lines without eating the newline', () => {
+    const src = '/* a\nb */\nconst keep = 1;';
+    const out = mask(src);
+    expect(out).not.toContain('a\nb');
+    expect(out.split('\n').length).toBe(3);
+    expect(out).toContain('const keep = 1;');
+  });
+
+  it('blanks string contents and keeps the code around them', () => {
+    const out = mask('const s = "hidden"; const n = 42;');
+    expect(out).not.toContain('hidden');
+    expect(out).toContain('const s =');
+    expect(out).toContain('const n = 42;');
+  });
+
+  it('blanks a template literal including its interpolations', () => {
+    const out = mask('const s = `before ${x} after`;');
+    expect(out).not.toContain('before');
+    expect(out).not.toContain('after');
+    expect(out).toContain('const s =');
+  });
+
+  it('does not treat a division slash as the start of a regex literal', () => {
+    // `a / b` is division: the slash must not swallow the rest of the line.
+    const out = mask('const r = a / b; const keep = 1;');
+    expect(out).toContain('const keep = 1;');
+    expect(out).toContain('a / b');
+  });
+
+  it('leaves code with no literals byte-identical', () => {
+    const src = 'function f(a, b) {\n  return a + b;\n}';
+    expect(mask(src)).toBe(src);
+  });
+});

package/principles/adapters/cpp.ts

@@ -1,6 +1,17 @@
 import { BaseAdapter } from './base';
 import { Adapter } from '../types';
 
+/**
+ * Lexical state for the C/C++ block scanner: which comment/quote the scan is
+ * currently inside. Braces seen in any of these states are data, not structure.
+ */
+interface CppLexState {
+  inString: boolean;
+  /** Which quote character opened the string (`'` or `"`). */
+  stringChar: string;
+  inBlockComment: boolean;
+}
+
 export class CppAdapter extends BaseAdapter implements Adapter {
   detectLanguage(): string {
     const ext = this.filePath.toLowerCase();
@@ -49,61 +60,102 @@ export class CppAdapter extends BaseAdapter implements Adapter {
     return classMatches;
   }
 
+  /**
+   * Report how far the lexer can skip from `i`, updating `lex` as it goes.
+   *
+   * C and C++ share three constructs the brace tracker must not see into: line
+   * comments, block comments, and quoted literals. A `}` inside any of them is
+   * data, so counting it would truncate the function body at the wrong place.
+   *
+   * Extracted from `extractCodeBlock`, which carried all three state machines
+   * plus the brace tracking in one CCN-28 body (#620).
+   *
+   * IMPORTANT: this reports a skip distance and never decides that a character
+   * is "consumed". Returning 0 means "the caller must look at this character
+   * itself" -- which is what lets a `{` both end a literal-free run and open the
+   * block. A `//` or `/*` opener IS skippable (the tracker never wants it), and
+   * so are quotes; braces are not.
+   *
+   * @returns the number of characters to skip, or 0 when the caller must inspect.
+   */
+  private lexSkip(i: number, lex: CppLexState): number {
+    const char = this.fileContent[i];
+    const nextChar = this.fileContent[i + 1] || '';
+
+    if (lex.inBlockComment) return this.skipBlockCommentBody(i, char, nextChar, lex);
+    if (lex.inString) return this.skipStringBody(i, char, lex);
+
+    if (char === '/' && nextChar === '/') return this.skipLineComment(i);
+    if (char === '/' && nextChar === '*') {
+      lex.inBlockComment = true;
+      return 2;
+    }
+    if (char === '"' || char === "'") {
+      lex.inString = true;
+      lex.stringChar = char;
+      return 1;
+    }
+    return 0;
+  }
+
+  /** Skip a `//` comment through, but not including, the newline. */
+  private skipLineComment(start: number): number {
+    let i = start;
+    while (i < this.fileContent.length && this.fileContent[i] !== '\n') i++;
+    return i - start;
+  }
+
+  private skipBlockCommentBody(
+    i: number,
+    char: string,
+    nextChar: string,
+    lex: CppLexState,
+  ): number {
+    if (char === '*' && nextChar === '/') {
+      lex.inBlockComment = false;
+      return 2;
+    }
+    return 1;
+  }
+
+  private skipStringBody(i: number, char: string, lex: CppLexState): number {
+    if (char !== lex.stringChar) return 1;
+    // A quote closes the literal only after an EVEN number of backslashes:
+    // `"\\"` is a backslash then a terminator, `"\""` is a quote as data.
+    let backslashCount = 0;
+    let j = i - 1;
+    while (j >= 0 && this.fileContent[j] === '\\') {
+      backslashCount++;
+      j--;
+    }
+    if (backslashCount % 2 === 0) lex.inString = false;
+    return 1;
+  }
+
   override extractCodeBlock(startPos: number, maxFallback: number = 200): string {
     const state = { inBlock: false, braceCount: 0 };
+    const lex: CppLexState = { inString: false, stringChar: '', inBlockComment: false };
     let endPos = startPos;
-    let inString = false;
-    let stringChar = '';
-    let inComment = false;
-
-    for (let i = startPos; i < this.fileContent.length; i++) {
-      const char = this.fileContent[i];
-      const nextChar = this.fileContent[i + 1] || '';
-
-      if (!inString && !inComment) {
-        if (char === '/' && nextChar === '/') {
-          while (i < this.fileContent.length && this.fileContent[i] !== '\n') {
-            i++;
-          }
-          continue;
-        }
-        if (char === '/' && nextChar === '*') {
-          inComment = true;
-          i++;
-          continue;
-        }
-      } else if (inComment) {
-        if (char === '*' && nextChar === '/') {
-          inComment = false;
-          i++;
-        }
-        continue;
-      }
-
-      if (!inComment) {
-        if (!inString && (char === '"' || char === "'")) {
-          inString = true;
-          stringChar = char;
-        } else if (inString && char === stringChar) {
-          let backslashCount = 0;
-          let j = i - 1;
-          while (j >= 0 && this.fileContent[j] === '\\') {
-            backslashCount++;
-            j--;
-          }
-          if (backslashCount % 2 === 0) {
-            inString = false;
-          }
-        }
-      }
 
-      if (!inString && !inComment) {
-        const result = this.advanceBraceTracker(char, i, state);
-        if (result.closed) {
-          endPos = result.endPos;
-          break;
-        }
+    for (let i = startPos; i < this.fileContent.length;) {
+      // The lexer reports how far to skip, but must NEVER consume a character
+      // the brace tracker still has to see. A `{` both ends a literal-free run
+      // and opens the block; consuming it here would hide the function's own
+      // opening brace and leave every later brace off by one.
+      //
+      // `lexSkip` returns 0 ONLY for characters outside any literal or comment,
+      // so a positive skip already guarantees "not structural". There is
+      // deliberately no separate inString/inBlockComment test: it would be dead
+      // (verified by deleting it -- no test changes colour).
+      const skip = this.lexSkip(i, lex);
+      if (skip > 0) { i += skip; continue; }
+
+      const result = this.advanceBraceTracker(this.fileContent[i], i, state);
+      if (result.closed) {
+        endPos = result.endPos;
+        break;
       }
+      i++;
     }
 
     if (endPos > startPos) {