/sanitize

name: sanitize
description: Sanitization - Provenance-aware sanitization of raw specs for independent separation
arguments:
  - name: workspace_path
    description: Path to the analysis workspace directory
    required: true
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Bash
  - Task
  - TodoWrite

/sanitize - Spec Sanitization (Sanitization)

Workspace: $ARGUMENTS

YOUR MISSION

**Remove ALL implementation contamination from analysis specs while preserving provenance metadata.**

The sanitization pass turns raw analysis into specs an implementer can build from. Source-code references have no place in the output. But provenance metadata (confidence levels, source types, agent names) must be preserved — only raw file paths are stripped.

PHASE 1: Initial Assessment

First, verify the workspace and assess scope:

# Verify workspace structure
[ -d "$ARGUMENTS/raw/specs/" ] || { echo "ERROR: No raw specs found at $ARGUMENTS/raw/specs/"; exit 2; }

# Count files to sanitize
echo "=== Sanitization Scope ==="
echo "Raw specs files: $(find $ARGUMENTS/raw/specs/ -name '*.md' -type f | wc -l)"
echo "Public artifacts: $(find $ARGUMENTS/public/ -name '*.md' -type f 2>/dev/null | wc -l)"

PHASE 2: Public Source Pass-Through

Public artifacts contain no implementation details and pass through without modification:

# Copy public artifacts directly (no sanitization needed)
if [ -d "$ARGUMENTS/public/" ]; then
  mkdir -p $ARGUMENTS/output/public/
  cp -r $ARGUMENTS/public/* $ARGUMENTS/output/public/
  echo "Public artifacts copied: $(find $ARGUMENTS/output/public/ -name '*.md' | wc -l) files"
fi

PHASE 3: Agent-Based Sanitization

**For EACH spec file in the raw tree, invoke the sanitizer worker.**

# List all spec files
find $ARGUMENTS/raw/specs/ -name '*.md' -type f

For each file (or batch of related files), dispatch `greenfield:sanitizer`:

• Prompt: "Follow the **spec-sanitization skill** for the full transformation methodology. Read `$ARGUMENTS/raw/specs/<file-path>`. Understand the behavioral intent. Rewrite without source references. Transform provenance citations (strip raw refs, preserve confidence). Write to `$ARGUMENTS/output/specs/<relative-path>`. For module specs, merge into behavioral domain files in `$ARGUMENTS/output/specs/domains/`."

Provenance Citation Transformation

During sanitization, provenance citations are transformed:

**Raw citations** (source=source-code, source=runtime-observation, source=binary-analysis):

• Strip the `ref` field (contains raw file paths)
• Preserve `source`, `confidence`, `agent`, and `corroborated_by` fields

**Public citations** (source=official-docs, source=sdk-analysis, source=public-api):

• Pass through without modification (ref fields point to public URLs or workspace/public/ paths)

**Before (raw):**

<!-- cite: source=source-code, ref=workspace/raw/source/analysis/chunk-0013.md:42, confidence=confirmed, agent=deep-dive-analyzer, corroborated_by=runtime-observation -->

**After (clean):**

<!-- cite: source=source-code, confidence=confirmed, agent=deep-dive-analyzer, corroborated_by=runtime-observation -->

PHASE 4: Validation Artifact Sanitization

Acceptance criteria and test vectors also need sanitization:

# Sanitize acceptance criteria
find $ARGUMENTS/raw/specs/validation/ -name '*.md' -type f

For each validation artifact:

• Strip raw `ref` paths from provenance citations
• Preserve Given/When/Then structure
• Preserve AC IDs (AC-{MODULE}-{NNN})
• Write to `$ARGUMENTS/output/validation/`

PHASE 5: Verification

After all agents complete, verify the output specs using LLM judgment.

**For EACH file in `$ARGUMENTS/output/specs/`**, read the file end-to-end and evaluate against these criteria:

Verification Criteria

1. **No implementation details** — The spec must not contain source file paths, line numbers, function/class names from source code, minified identifiers, IPC channel names, state management library references, CSS class names, or database migration identifiers. External contract files (`contracts/`) may reference technical formats (SQL types, API endpoints) since those describe the external system's interface, not the app's implementation.

2. **External contracts preserved** — Any behavioral contracts with external systems (databases, APIs, CLIs, file formats) must still fully describe the interface the app depends on. These are requirements, not implementation details.

3. **Behavioral completeness** — Decision trees, state machines, error conditions, edge cases, and acceptance criteria from the raw original must all be present in the output version. Sanitization removes *how the source code did it*, not *what the system must do*.

4. **No raw provenance leaks** — Provenance citations must not contain `ref=` fields pointing to `workspace/raw/` paths. The `source`, `confidence`, `agent`, and `corroborated_by` fields should be preserved.

5. **No structural contamination** — No "Part N:" headers from source chunking, no module IDs (MOD-NNN), no module counts, no cross-module/inter-module references, no domain-to-module mapping language.

The Reimplementor Test

For each spec, ask: *"Could a competent engineer who has never seen the original source code read this spec and build a correct implementation from scratch?"* If the answer is no because implementation details are missing, the spec FAILS. If the answer is no because behavioral requirements were lost during sanitization, the spec also FAILS.

Verification Report

Produce a verification report listing each file with PASS or FAIL and a brief reason for any failure:

=== Verification Report ===
output/specs/domains/process-lifecycle.md  PASS
output/specs/domains/data-management.md    PASS
output/specs/contracts/database.md         PASS
output/specs/journeys/first-run.md         FAIL  — contains reference to src/init.ts:42
...
RESULT: PASS (all