clean-room-skill 0.1.0

package/skills/clean-room/examples/minimal-spec-package/evidence-ledger.json

@@ -0,0 +1,17 @@
+{
+  "ledger_id": "evidence-ledger-example",
+  "task_id": "task-example",
+  "domain": "contaminated",
+  "entries": [
+    {
+      "evidence_id": "item-001",
+      "source_unit_ref": "unit-example-flow",
+      "evidence_type": "source-observation",
+      "description": "Neutral note that a behavior exists; no source text included.",
+      "evidence_location_ref": "contaminated-only:unit-example-flow:item-001",
+      "source_hash": "not-recorded-in-example",
+      "sensitivity": "medium",
+      "retained_in_contaminated_domain": true
+    }
+  ]
+}

package/skills/clean-room/examples/minimal-spec-package/handoff-package.json

@@ -0,0 +1,26 @@
+{
+  "package_id": "handoff-example",
+  "task_id": "task-example",
+  "from_domain": "contaminated",
+  "to_domain": "clean",
+  "created_by_role": "contaminated-source-analyst",
+  "artifacts": [
+    {
+      "artifact_id": "spec-example-flow",
+      "artifact_type": "behavior-spec",
+      "path": "clean-artifacts/behavior-spec.json",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  ],
+  "excluded_material": [
+    "source_excerpt",
+    "raw_diff",
+    "private_identifier",
+    "source_shaped_pseudocode"
+  ],
+  "leakage_review": {
+    "status": "passed",
+    "reviewer_role": "contaminated-source-analyst",
+    "notes": "Example package contains only schema-shaped data."
+  }
+}

package/skills/clean-room/examples/minimal-spec-package/qc-report.json

@@ -0,0 +1,25 @@
+{
+  "report_id": "qc-example",
+  "reviewer_role": "clean-qa-editor",
+  "reviewed_at": "2000-01-01T00:00:00Z",
+  "reviewed_artifacts": [
+    "behavior-spec.json",
+    "skeleton-manifest.json"
+  ],
+  "artifact_hashes": [
+    {
+      "artifact": "behavior-spec.json",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  ],
+  "schema_validator_version": "manual-example",
+  "schema_status": "passed",
+  "leakage_status": "passed",
+  "leakage_scan_summary": "No blocked markers in example.",
+  "coverage_status": "complete",
+  "required_rerun": false,
+  "contamination_incidents": [],
+  "findings": [],
+  "abstract_delta_tickets": [],
+  "final_status": "passed"
+}

package/skills/clean-room/examples/minimal-spec-package/skeleton-manifest.json

@@ -0,0 +1,45 @@
+{
+  "manifest_id": "skeleton-example",
+  "target_language": "unspecified",
+  "area_id_naming_policy": "Use neutral clean ids that do not mirror source layout.",
+  "target_constraints": [],
+  "areas": [
+    {
+      "area_id": "area-example-flow",
+      "purpose": "Own the example behavior.",
+      "spec_ids": [
+        "spec-example-flow"
+      ],
+      "public_contract_refs": [],
+      "target_constraints": [],
+      "dependency_constraints": [],
+      "test_obligations": [
+        "test-001"
+      ],
+      "open_decisions": []
+    }
+  ],
+  "public_contracts": [],
+  "dependency_constraints": [],
+  "implementation_forbidden_material": [
+    "source_excerpt",
+    "raw_diff",
+    "private_identifier",
+    "source_shaped_pseudocode"
+  ],
+  "test_mapping": [
+    {
+      "test_id": "test-001",
+      "spec_ids": [
+        "spec-example-flow"
+      ],
+      "scenario_refs": [
+        "test-001"
+      ]
+    }
+  ],
+  "test_obligations": [
+    "test-001"
+  ],
+  "open_decisions": []
+}

package/skills/clean-room/examples/minimal-spec-package/source-index.json

@@ -0,0 +1,156 @@
+{
+  "index_id": "source-index-task-example",
+  "task_id": "task-example",
+  "created_at": "2026-05-20T00:00:00Z",
+  "created_by_role": "controller-preflight",
+  "domain": "contaminated",
+  "generator": {
+    "name": "build_source_index.py",
+    "version": "1",
+    "python_version": "3.x",
+    "scanner_modes": [
+      "python-ast",
+      "javascript-typescript-scanner",
+      "text-metrics"
+    ]
+  },
+  "limits": {
+    "max_files": 2000,
+    "max_file_bytes": 1000000,
+    "max_total_bytes": 50000000,
+    "max_batch_tokens": 20000,
+    "ignore_dirs": [
+      ".git",
+      ".next",
+      ".venv",
+      "__pycache__",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "target",
+      "venv"
+    ]
+  },
+  "source_roots": [
+    {
+      "root_id": "root-001",
+      "path": "source-workspace"
+    }
+  ],
+  "files": [
+    {
+      "file_id": "file-000001",
+      "root_id": "root-001",
+      "path": "flow/controller.py",
+      "language": "python",
+      "scanner": "python-ast",
+      "metrics": {
+        "bytes": 120,
+        "lines": 6,
+        "words": 14,
+        "characters": 120,
+        "estimated_tokens": 30
+      },
+      "imports": [
+        {
+          "specifier": ".state",
+          "kind": "python-from-import",
+          "is_relative": true,
+          "names": [
+            "State"
+          ],
+          "resolved_file_id": "file-000002"
+        }
+      ],
+      "exports": [
+        {
+          "name": "Controller",
+          "kind": "top-level-class"
+        }
+      ]
+    },
+    {
+      "file_id": "file-000002",
+      "root_id": "root-001",
+      "path": "flow/state.py",
+      "language": "python",
+      "scanner": "python-ast",
+      "metrics": {
+        "bytes": 80,
+        "lines": 4,
+        "words": 9,
+        "characters": 80,
+        "estimated_tokens": 20
+      },
+      "imports": [],
+      "exports": [
+        {
+          "name": "State",
+          "kind": "top-level-class"
+        }
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "from_file_id": "file-000001",
+      "to_file_id": "file-000002",
+      "specifier": ".state",
+      "kind": "python-from-import"
+    }
+  ],
+  "groups": [
+    {
+      "group_id": "group-0001",
+      "reason": "dependency-component",
+      "file_ids": [
+        "file-000001",
+        "file-000002"
+      ],
+      "metrics": {
+        "bytes": 200,
+        "lines": 10,
+        "words": 23,
+        "characters": 200,
+        "estimated_tokens": 50
+      },
+      "notes": "Files connected by resolved local imports."
+    }
+  ],
+  "recommended_batches": [
+    {
+      "batch_id": "batch-0001",
+      "group_ids": [
+        "group-0001"
+      ],
+      "file_ids": [
+        "file-000001",
+        "file-000002"
+      ],
+      "metrics": {
+        "bytes": 200,
+        "lines": 10,
+        "words": 23,
+        "characters": 200,
+        "estimated_tokens": 50
+      },
+      "notes": "Example Agent 0 unit source batch."
+    }
+  ],
+  "skipped_entries": [],
+  "aggregate_metrics": {
+    "bytes": 200,
+    "lines": 10,
+    "words": 23,
+    "characters": 200,
+    "estimated_tokens": 50,
+    "file_count": 2,
+    "skipped_count": 0,
+    "skipped_entries_truncated": false,
+    "relationship_count": 1,
+    "resolved_relationship_count": 1,
+    "group_count": 1,
+    "batch_count": 1
+  }
+}

package/skills/clean-room/examples/minimal-spec-package/task-manifest.json

@@ -0,0 +1,220 @@
+{
+  "task_id": "task-example",
+  "target_identifier": "example-system",
+  "authorization": {
+    "requester": "example-requester",
+    "scope_statement": "Authorized example clean-room source-to-spec task.",
+    "allowed_actions": [
+      "read authorized source",
+      "produce spec-only artifacts"
+    ],
+    "prohibited_actions": [
+      "generate replacement implementation code",
+      "move source excerpts into clean artifacts"
+    ],
+    "evidence_handling": "Retain source evidence only in the contaminated workspace."
+  },
+  "source_acquisition_basis": "Authorized local source access.",
+  "license_contract_notes": "No legal conclusion recorded.",
+  "source_index_ref": "contaminated-artifacts/source-index.json",
+  "source_scope": {
+    "workspace_id": "source-workspace",
+    "description": "Authorized source workspace.",
+    "path_policy": "Clean roles must not read this workspace."
+  },
+  "clean_scope": {
+    "workspace_id": "clean-workspace",
+    "description": "Clean spec workspace.",
+    "path_policy": "Contaminated roles must not write here."
+  },
+  "trust_boundary": {
+    "contaminated_domain": "source-workspace",
+    "clean_domain": "clean-workspace",
+    "separation_controls": [
+      "separate workspace paths",
+      "separate profiles",
+      "schema validation",
+      "leakage review"
+    ]
+  },
+  "controller_policy": {
+    "mode": "attended",
+    "stop_conditions": [
+      "authorization-missing",
+      "scope-change",
+      "contamination-suspected",
+      "schema-validation-failed",
+      "leakage-scan-failed",
+      "unit-blocked",
+      "coverage-complete"
+    ],
+    "notes": "Missing controller policy defaults to attended mode."
+  },
+  "format_selection": {
+    "mode": "canonical-plus-target",
+    "selection_basis": "user-choice",
+    "target_profile": "speckit-feature-folder",
+    "native_artifacts": [
+      ".specify/memory/constitution.md - shared project constitution",
+      "specs/<feature-id>/spec.md - feature specification",
+      "specs/<feature-id>/plan.md - technical plan",
+      "specs/<feature-id>/tasks.md - executable work items"
+    ],
+    "formatting_rules": [
+      "Render a numbered feature folder under specs/<feature-id>/.",
+      "Use prioritized user stories with Given/When/Then acceptance scenarios in spec.md.",
+      "Use plan.md and tasks.md for technical plan and executable work items."
+    ]
+  },
+  "agent_pipeline": {
+    "agent_0": {
+      "role": "contaminated-manager-verifier",
+      "responsibility": "Manage scope, assign agents, verify coverage, and receive Agent 3 final report.",
+      "trust_domain": "contaminated"
+    },
+    "agent_1": {
+      "role": "contaminated-source-analyst",
+      "responsibility": "Read authorized source and generate neutral source units, task slices, and behavior specs.",
+      "trust_domain": "contaminated"
+    },
+    "agent_2": {
+      "role": "clean-architect",
+      "responsibility": "Merge approved handoff artifacts into the selected clean schema base and skeleton manifest without reading source or contaminated ledgers.",
+      "trust_domain": "clean"
+    },
+    "agent_3": {
+      "role": "clean-qa-editor",
+      "responsibility": "Run final schema, leakage, and coverage QC and report abstract findings to Agent 0.",
+      "trust_domain": "clean"
+    },
+    "handoff_rules": {
+      "allowed_inputs": [
+        "task-manifest.json",
+        "approved behavior-spec.json",
+        "handoff-package.json",
+        "abstract coverage summaries",
+        "abstract delta tickets"
+      ],
+      "allowed_outputs": [
+        "behavior-spec.json",
+        "skeleton-manifest.json",
+        "qc-report.json",
+        "abstract-delta-ticket"
+      ],
+      "blocked_material": [
+        "source excerpts",
+        "raw diffs",
+        "private identifiers",
+        "source-shaped pseudocode",
+        "contaminated ledgers in clean inputs"
+      ],
+      "report_back_to": "agent_0"
+    }
+  },
+  "required_profiles": [
+    {
+      "role": "contaminated-manager-verifier",
+      "profile_id": "contaminated-manager-profile",
+      "workspace_id": "source-workspace"
+    },
+    {
+      "role": "contaminated-source-analyst",
+      "profile_id": "contaminated-analyst-profile",
+      "workspace_id": "source-workspace"
+    },
+    {
+      "role": "clean-architect",
+      "profile_id": "clean-architect-profile",
+      "workspace_id": "clean-workspace"
+    },
+    {
+      "role": "clean-qa-editor",
+      "profile_id": "clean-qa-profile",
+      "workspace_id": "clean-workspace"
+    }
+  ],
+  "artifact_paths": {
+    "contaminated_artifacts": "contaminated-artifacts/",
+    "contaminated_artifact_roots": [
+      "contaminated-artifacts/"
+    ],
+    "clean_artifacts": "clean-artifacts/",
+    "quarantine": "quarantine/"
+  },
+  "handoff_policy": {
+    "allowed_artifacts": [
+      "behavior-spec",
+      "handoff-package",
+      "abstract-delta-ticket"
+    ],
+    "blocked_material": [
+      "source excerpts",
+      "raw diffs",
+      "private identifiers"
+    ],
+    "one_way_handoff": true,
+    "notes": "Only structured clean-approved artifacts cross the wall."
+  },
+  "tool_policy": [
+    "Run source indexing only as controller preflight before clean-room role sessions.",
+    "Use read-only source tools in contaminated roles.",
+    "Use write tools only in contaminated artifact roots for contaminated roles.",
+    "Use write tools only in clean spec workspace for clean roles."
+  ],
+  "model_policy": [
+    "Use separate profiles for contaminated and clean roles."
+  ],
+  "retention_policy": "Retain clean artifacts; keep contaminated evidence separate.",
+  "roles": [
+    {
+      "role": "contaminated-manager-verifier",
+      "trust_domain": "contaminated",
+      "allowed_access": [
+        "source-workspace",
+        "contaminated-artifacts"
+      ]
+    },
+    {
+      "role": "contaminated-source-analyst",
+      "trust_domain": "contaminated",
+      "allowed_access": [
+        "source-workspace",
+        "contaminated-artifacts"
+      ]
+    },
+    {
+      "role": "clean-architect",
+      "trust_domain": "clean",
+      "allowed_access": [
+        "clean-workspace"
+      ]
+    },
+    {
+      "role": "clean-qa-editor",
+      "trust_domain": "clean",
+      "allowed_access": [
+        "clean-workspace"
+      ]
+    }
+  ],
+  "units": [
+    {
+      "unit_id": "unit-example-flow",
+      "description": "Example observable flow.",
+      "status": "pending",
+      "source_index_refs": [
+        "source-index:batch-0001"
+      ],
+      "notes": "Neutral unit id."
+    }
+  ],
+  "expected_artifacts": [
+    "source-index.json",
+    "behavior-spec.json",
+    "skeleton-manifest.json",
+    "qc-report.json"
+  ],
+  "audit_log_refs": [
+    "audit-log:example"
+  ]
+}

package/skills/clean-room/references/LEAKAGE-RULES.md

@@ -0,0 +1,92 @@
+# Leakage Rules
+
+## Invariant
+
+Only unprotected functional behavior and compatibility requirements should cross into the clean workspace. Source expression, source-shaped design, and contaminated context must stay out.
+
+## Never Cross
+
+Block these from clean artifacts:
+
+- raw source files
+- copied source excerpts
+- raw diffs
+- copied comments
+- decompiled output
+- private package, module, class, helper, method, function, variable, constant, or field names
+- source-only file layout
+- distinctive internal identifiers
+- implementation-shaped pseudocode
+- stack traces containing source lines
+- unique log messages, UI copy, or strings not needed for compatibility
+- formatting, ordering, or naming that mirrors source without public-contract need
+
+## Allowed With Care
+
+Allow these only when needed for compatibility or testing:
+
+- public API names
+- command names and flags
+- documented config keys
+- public protocol fields
+- public file formats
+- externally visible error codes
+- interoperability-relevant strings
+
+When keeping a public name, record why it is compatibility-relevant.
+
+## Identifier Boundary
+
+Treat implementation identifiers as contaminated by default. Package names, namespace names, module paths, class names, method names, function names, variable names, constants, fields, and internal event names must not appear in clean specs unless they are public compatibility surface.
+
+Public compatibility surface means the name is externally documented, required by an existing integration, visible in a public protocol or file format, or explicitly required by the destination scope. If a name is retained, place it in `public_surface` or `public_contracts` with `name`, `kind`, `visibility`, and a concrete compatibility reason. Valid `visibility` values are `public`, `destination`, `protocol`, and `user-required`. Do not mention source-private names in summaries, claims, tests, open questions, skeleton areas, QC findings, or delta tickets.
+
+The contaminated side should maintain a private identifier denylist for guardrail scanning when practical. The denylist is line-oriented, ignores blank lines and `#` comments, and is bounded to 1,000,000 bytes per file, 20,000 total terms, and 512 characters per term. Keep that list out of clean-role readable roots and do not paste its contents into clean artifacts or model-visible reports.
+
+## Rewrite Pattern
+
+Convert source-adjacent observations into neutral requirements:
+
+- Bad: "Function `parseFooInternal` checks `if x == 7` then calls `retryLater`."
+- Good: "When input mode is unsupported, the component rejects the request before persistence and exposes a retryable error."
+- Bad: "Copy this loop structure."
+- Good: "Process entries in input order and stop after the first validation failure."
+
+## Review Checklist
+
+Before clean handoff, confirm:
+
+- No copied source text remains.
+- No source code block remains.
+- No private helper or file names remain unless justified as public compatibility.
+- No private package, module, class, function, method, variable, constant, or field names remain.
+- No algorithm description is more specific than required by observable behavior.
+- No formatting, ordering, or naming mirrors source by default.
+- Every claim has an evidence status.
+- Every retained public name has a compatibility reason.
+- Every uncertain behavior is marked as an open question.
+
+## Contamination Response
+
+If clean work receives blocked material:
+
+1. Stop clean processing for the affected artifact.
+2. Mark the artifact contaminated.
+3. Remove it from the clean workspace or quarantine it outside the clean artifact set.
+4. Regenerate a scrubbed artifact from the contaminated side.
+5. Record the incident in `qc-report.json` and, when useful, a standalone `contamination-incident.json`.
+
+Do not try to "forget" source material inside the same clean context and continue.
+
+## Guardrail Scripts
+
+Use hook scripts as audit and guardrail support, not as the only boundary:
+
+- `hooks/deny-clean-source-read.py`: denies clean-role reads from `CLEAN_ROOM_SOURCE_ROOTS` and any path outside `CLEAN_ROOM_CLEAN_ROOTS` plus `CLEAN_ROOM_ALLOWED_READ_ROOTS`.
+- `hooks/deny-contaminated-clean-write.py`: enforces write roots. Clean roles may write only under `CLEAN_ROOM_CLEAN_ROOTS`; contaminated roles may write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+- `hooks/check-artifact-leakage.py`: scans clean artifacts for high-risk leakage markers, obvious source-like identifiers, and terms from optional `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST` files.
+- `hooks/validate-json-schema.py`: checks JSON syntax and common bundled schema constraints, including the conditional and bounded fields used by these schemas. It is not a full JSON Schema 2020-12 validator.
+- `hooks/require-clean-room-env.py`: fails closed when the role, root, or schema environment block is missing.
+- `hooks/deny-clean-room-shell.py`: denies shell-style tools for clean-room role sessions because shell reads can bypass path-aware hooks.
+
+Set `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, and `CLEAN_ROOM_SCHEMA_DIR` explicitly before running hooks. Set `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST` when the contaminated side has produced a private identifier list for hook-only scanning.