bugfix: surface --format markdown and --exclude glob filter

[stackbilt-admin]

Summary

• Closes bug: charter surface --format markdown unsupported, silently errors #236 — charter surface --format markdown now works; previously rejected with Invalid --format value: markdown. Added markdown as a valid format, routing to the existing formatSurfaceMarkdown export in @stackbilt/surface.
• Closes bug: charter surface scans scaffold template files, produces false-positive routes in charter repo itself #237 — charter surface --exclude <glob> now filters paths from the scan. Supports plain directory prefixes (packages/scaffold-core) and glob wildcards (**/codegen/**, src/templates/*). Prevents false-positive routes from scaffold template files when running charter surface inside the charter repo itself.

Changes

• packages/cli/src/index.ts — CLIOptions.format extended to 'text' | 'json' | 'markdown'; validation and help text updated
• packages/cli/src/commands/surface.ts — handles options.format === 'markdown'; collects multiple --exclude values
• packages/surface/src/index.ts — adds matchGlob() helper, updates walkFiles() to accept root + excludeGlobs, extends SurfaceInputSchema and ExtractOptions with excludeGlobs
• packages/surface/src/__tests__/surface.test.ts — 5 new regression tests covering schema default, plain path exclusion, and ** wildcard exclusion

Test plan

• charter surface --format markdown produces markdown output (no error)
• charter surface --format text and --format json unaffected
• charter surface --exclude packages/scaffold-core skips that directory
• charter surface --exclude "**/codegen/**" skips any nested codegen/ directory
• 760/760 tests pass (pnpm exec vitest run)

🤖 Generated with Claude Code

[stackbilt-admin]

CHANGES_REQUESTED

Reviewed against issues #236 (--format markdown rejected) and #237 (scaffold template false-positives). The markdown format fix and the glob filtering mechanism are both structurally correct. Three issues require changes before merge.

---

1. --exclude flag-value theft from adjacent positional flags (BLOCKING)

packages/cli/src/commands/surface.ts, lines 22–30

The --exclude collection loop and getFlag both operate on the same raw args array with no coordination. When --exclude immediately follows --root or --schema with no value between them, getFlag returns the string '--exclude' as the value for that flag.

Concrete failure:
```
charter surface --root --exclude src/gen
```

• getFlag(args, '--root') returns '--exclude' → rootArg = '--exclude' → resolves to /cwd/--exclude (non-existent)
• The exclude loop correctly collects 'src/gen'
• walkFiles catches the missing directory and returns empty; the command throws "No routes or schema tables detected" with no hint that flags were misparsed

Symmetric case: charter surface --schema --exclude src/gen → schemaFlag = '--exclude' → path.resolve('--exclude') passed as schema path → silently reads nothing.

Fix: validate that args[i+1] is not a flag string (does not start with --) before pushing it as a glob value. Alternatively, use getFlag-style multi-value parsing so all flag reads go through one consistent pass.

---

2. --format markdown falls through to text output on all commands except surface (BLOCKING)

packages/cli/src/index.ts, line 112 — CLIOptions.format is now 'text' | 'json' | 'markdown'

Every other command (score, doctor, validate, drift, audit, bootstrap, etc.) uses the pattern:
```typescript
if (options.format === 'json') { ... } else { /* text output */ }
```
--format markdown lands in the else arm and emits ANSI-styled text output. There is no markdown formatter for those commands (which is fine), but there is also no error. A user who runs:
```
charter validate --format markdown
```
gets plain text with no warning that markdown is not supported for this command.

The fix does not require implementing markdown formatters everywhere. The cleanest fix is to scope 'markdown' as a surface-only flag — either validate it in surfaceCommand (accept it there, reject it globally), or emit a warning in run() when rawFormat === 'markdown' and the command is not surface. At minimum, the help text for the global --format option should document which commands support markdown.

---

3. matchGlob regex construction for \x00/ (**/) replacement

packages/surface/src/index.ts, lines 139–142

The replacement string for **/ is '(?:[^/]+/)*' — confirmed correct with the * quantifier present. However, a subtle ordering issue exists: the \x00/ substitution replaces **/ (two stars then a slash), but a pattern like a/**/b first converts ** to \x00, yielding a/\x00/b. Then \x00/ (null + slash) matches and produces a/(?:[^/]+/)*b. This is correct.

The edge case worth documenting: ** appearing at the very end of a pattern without a following slash (e.g., packages/**) hits the trailing \x00 → .* branch, not the \x00/ branch. This produces packages/.* which is correct for excluding all files under packages/. Both tests in the PR exercise this path correctly ('**/codegen/**' and 'packages/codegen'), but there is no test for packages/** (trailing **). Please add a test case for this pattern to the matchGlob or excludeGlobs test block to lock in the behavior.

This is not a blocker but is the pattern most likely to be used in real --exclude invocations.

---

Checklist for the issues being fixed:

• --format markdown accepted and routes to formatSurfaceMarkdown() — surface.ts line 24 is correct
• options.format === 'markdown' correctly branches at line 51
• --exclude flag collected multi-value correctly (when not adjacent to another flag)
• excludeGlobs passed through SurfaceInputSchema → analyze() → extractSurface() — complete
• Both walkFiles call sites in extractSurface pass root correctly (lines 511, 533)
• SurfaceInputSchema.excludeGlobs default [] — analyze() at line 690 passes it
• Issue #1 above (flag-value theft)
• Issue #2 above (--format markdown silently degrades on other commands)
• Issue #3 above (test coverage for packages/** trailing-** pattern)