Spec Sanitization

Spec Sanitization

The sanitization pass turns raw analysis into specs an implementer can build from.

Why This Exists

Analysts read source code, binaries, and runtime behavior. Even with good intentions, they leak implementation details:

• Function names from source (minified or not)
• Variable and class names from source
• Code structure ("function X calls Y which calls Z")
• Line numbers and file locations
• Raw file paths (workspace/raw/source/analysis/chunk-42.md:67)

These have no place in the output specs. Your job: READ each spec, UNDERSTAND the behavior, REWRITE without source references, TRANSFORM provenance citations.

The Rewrite Rule

You must not copy text from raw specs into output specs. Not sentences, not paragraphs, not sections. Read the raw specs to understand the behavior, then write a fresh output spec from your understanding.

Why? Raw specs have source code identifiers woven into every sentence — minified names (k0, Wq, z1), internal function signatures (Pn(a, b, c)), and numeric implementation constants. Find-and-replace cannot catch them all; many internal identifiers read like plain English (shouldRetryOnTimeout, evict_stale_connections). A paraphrase that preserves the original's structure is still leaking the original's design. The only reliable approach is to never copy the text at all.

Process per file:

1. Read the raw spec end-to-end
2. Close it (do not refer back to it while writing)
3. Write the output spec from your understanding of the behavior
4. Use only: behavioral descriptions, user-facing identifiers (env vars, CLI flags, config keys, protocol fields), and numeric constants (timeouts, limits, sizes)
5. For any concept you could not translate into behavioral language — because you don't understand what it does — add: [UNCERTAINTY: U-{DOMAIN}-{NNN}] {what the raw spec said, in behavioral terms as best you can} — behavioral purpose could not be determined from available analysis.

Never preserve implementation jargon in slightly-reworded form. "validator.Exists() is called" rewritten as "the exists check runs" is still jargon — neither you nor the implementer knows what it means. Either translate it to behavior ("verifies the value exists in the constrained list") or flag it as uncertain.

If you find yourself copying a sentence and then editing out identifiers — STOP. You are doing it wrong. Rewrite the sentence from scratch.

Caveat on the "close the file" step: this is a behavioral instruction, not an enforced mechanism. Closing a file does not evict its content from the agent's context window; the raw text remains readable until the session ends. The Layer 6 second-pass review, which runs in a fresh session with access only to workspace/output/, is the practical check on verbatim leakage. Treat this process as discipline, not guarantee.

The Core Principle

For every identifier in a spec, ask: "Would an implementor encounter this exact string?"

• DATABASE_URL → YES: it's in official docs, users type it. KEEP.
• --format → YES: it's in CLI help output. KEEP.
• plugins → YES: it's a config file key users write. KEEP.
• Retry-After → YES: it's an HTTP header defined by RFC 9110. KEEP.
• routeRequest → NO: this is an internal function name the developer chose. A different developer would name it differently. GENERALIZE to "the request routing operation."
• ff_batch_commit_v2 → NO: this is an internal feature flag. No user ever types this. GENERALIZE to "the batch commit feature gate."
• q9 → NO: this is a minified identifier with zero semantic content. REMOVE.

No set of regex patterns will catch every internal identifier because many look like legitimate English (e.g., shouldRetryOnTimeout, evict_stale_connections). You must read every line and apply the principle above.

Implementation Detail vs. External Contract

Every identifier in a raw spec is either an implementation detail that must be abstracted or an external contract that must be preserved. This distinction is language-agnostic — it applies whether the source is TypeScript, Python, Rust, Go, Java, C++, or anything else.

Implementation Details (MUST be abstracted)

These are choices the original developers made that a reimplementor would reasonably make differently. Abstract them to behavioral descriptions or remove them entirely.

Internal names — function, method, class, module, and variable names chosen by the original developers:

• Python: _drain_write_queue(), RecordParser, should_retry_on_timeout
• Go: routeRequest(), evictStaleConnections, indexBuilder
• Rust: fn decode_packet(), struct ProtocolFrame
• Java: parseRecord(), validateRecord(), AbstractMessageProcessor
• Any language: camelCase, snake_case, PascalCase internal identifiers

Internal architecture — how the codebase is organized into files, modules, packages, or namespaces:

• "defined in the auth handler module"
• "the session manager class calls the config loader"
• "located in pkg/internal/transport/"

Framework-specific patterns — references to libraries, state management, UI frameworks, or runtime internals:

• State stores: useStore, getState(), @observable, store.get()
• UI frameworks: className=, styled., @Component, #[derive(Template)]
• ORM details: Model.objects.filter(), has_many :sessions, @Entity
• DI containers: @Inject, container.resolve(), wire.Build()

Build and deployment artifacts — paths, chunk IDs, minified identifiers, line numbers:

• Source paths: src/, lib/, pkg/, internal/, dist/, target/, build/
• Source filenames: auth-handler.ts, record_parser.py, transport.go, Main.java
• Minified/obfuscated identifiers: Ab2, q9, a$b, __webpack_require__
• Line numbers: "at line 234", ":45:", "L187"
• Module IDs: MOD-023, chunk-NNNN

Internal feature gates — feature flag names, experiment keys, and vendor-specific telemetry identifiers:

• ff_batch_commit_v2, FF_NEW_INDEX_FORMAT, ff_dark_mode
• exp_async_cache_v2, exp_beta_user
• Internal telemetry event names: cli_parse_completed, worker_started

Code structure language — descriptions that mirror source code control flow rather than observable behavior:

• "function X calls Y which calls Z"
• "the method iterates over the list and invokes the callback"
• "the constructor initializes three private fields"

External Contracts (MUST be preserved)

These are constraints imposed by the outside world that a reimplementor cannot redesign. Preserve them exactly.

User-facing identifiers — anything a user types, reads in docs, or sees in output:

• Environment variables: DATABASE_URL, DEBUG, RUST_LOG
• CLI flags: --format, --workers, -h, --verbose
• Config file keys: upstreams, log_level, timeout_seconds
• User-visible error messages: "Error: Invalid API key"
• Deep link protocols: vscode://, myapp://

Wire protocol fields — names that appear in network traffic, file formats, or IPC contracts:

• API fields: request_id, batch_size, stream
• HTTP headers and status codes: Authorization, 200, 401
• Serialization keys in documented formats

External system schemas — databases, APIs, CLIs, and file formats the application does not own:

• Database: table names, column names, constraints, cardinalities
• Third-party APIs: endpoint paths, request/response field names, auth flows, rate limits
• CLI tools the app shells out to: command names, flag names, output formats, exit codes
• Imposed file formats: field names, encoding rules, version headers

Published constants and standard names — values defined by specifications or public documentation:

• Protocol versions, standard error codes, well-known ports
• Names from RFCs, language specs, or platform documentation

The Test

For any identifier, ask: "Could the reimplementor reasonably redesign this?"

• YES → implementation detail. Abstract it to behavioral language or remove it.
• NO → external contract. Preserve it exactly.

Gray Area Heuristics

When the test isn't clear-cut, apply these secondary questions:

1. Would a user encounter it? If the string appears in CLI help, config files, error messages, or API responses visible to users → external contract.
2. Would two independent developers choose the same name? If both would write --verbose → external contract. If one might write parseArgs and another parse_arguments → implementation detail.
3. Is it imposed by a dependency the app doesn't control? Database column names in a shared schema, field names in a third-party API → external contract.
4. Does the spec make sense without it? If removing the identifier and describing the behavior instead loses no information → implementation detail. If the exact string is needed for interoperability → external contract.

The Descriptive-Name Trap (CRITICAL)

Internal identifiers like routeRequest, should_retry_on_timeout, FlushConnectionPool, strict_schema_validation look legitimate because they're descriptive English words in some casing convention. But they are implementation details — an implementor would choose different names for the same concepts. This applies equally to camelCase, snake_case, PascalCase, and kebab-case identifiers.

The test: Does this exact string appear in official documentation, a config file schema, a CLI --help output, or an API response? If not, it's an internal identifier and MUST be generalized, even if it's descriptive.

Examples that STAY (user-facing): upstreams, rate_limit, --workers, DATABASE_URL Examples that GO (internal): routeRequest → "the request routing operation", should_retry_on_timeout → "the retry-on-timeout check", FlushConnectionPool → "the connection pool flush"

External System Exception

When the target depends on external systems it does not own — shared databases, third-party APIs, CLI tools it shells out to, imposed file formats — the details of those systems are behavioral constraints, NOT implementation details. The contract-extractor should have produced dedicated contract files in workspace/raw/specs/contracts/ for each external system.

Do NOT strip from external system contracts:

• Database: table names, column names, cardinalities, naming collisions, derivation relationships, query-correctness constraints
• APIs: endpoint paths, request/response field names, pagination schemes, auth flows, rate limits
• CLI tools: command names, flag names, output formats the app parses, exit codes the app checks
• File formats: field names, encoding rules, version headers, structural layout

External contract files flow to implementation: workspace/raw/specs/contracts/{database,api-*,cli-*,format-*}.md → workspace/output/specs/contracts/.

Rewrite Patterns

Concrete before/after examples for the sanitizer to follow.

RP-1: Minified Identifiers

Before: The Ab2() function is the application entry point After: The application entry point is invoked on startup

RP-2: Module Names in Headers

Before: ## Part 3: RecordParser Module After: ## Session Lifecycle Management

RP-3: Module Counts

Before: The application consists of 52 modules organized into 8 domains After: (remove entirely — this is analysis organizational metadata)

RP-4: Cross-Module Dependency Tables

Before:

| Module | Depends On |
|--------|-----------|
| RecordParser | IndexBuilder, ConfigLoader |

After: (remove entirely — replaced by behavioral integration requirements in BIR format)

RP-5: IPC Channel Names

Before: Sends a message on the task-completed IPC channel After: Notifies listeners when the order status changes via internal messaging

RP-6: Store Property Names

Before: Reads store.activeDocument.content to get the document body After: Retrieves the current document body from application state

RP-7: Feature Flag Names

Before: When FF_NEW_INDEX_FORMAT is enabled, the feature activates After: When the batch commit feature gate is active, the feature activates

RP-8: Internal Filenames

Before: Defined in the auth handler source file alongside the token refresh logic After: The authentication handling component also manages token refresh