the-mindscape-of-bro-tsong/requirements/skills-vault/2026-06-18-review-bundle-zip-packager.md

# Skills-Vault Request: Review Bundle Zip Packager

Date: 2026-06-18

Client repository: `C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong`

Requested supplier repository:

```text
C:\Users\wangq\Documents\Codex\skills-vault
```

## 1. Product Context

The Mindscape of Bro Tsong repeatedly prepares CCRA / GPT review bundles under directories such as:

```text
ccra_review_bundle/round-04_2026-06-18_blind-input-routing-evaluation/
```

Each bundle often includes an optional raw changed-files zip. The zip must preserve source-relative paths so GPT / CCRA can inspect exact files in their repository context.

This is reusable automation, not product behavior. It belongs in `skills-vault`, not in this repository.

## 2. Repeated Action / Friction Point

Manual zip creation has repeatedly failed or required retries because of:

- PowerShell `Compress-Archive` flattening paths when given a flat file list.
- Windows / .NET compression API differences.
- Existing destination zip overwrite behavior.
- Need to verify that zip entries preserve source-relative paths.
- Need to confirm every requested file exists before packaging.

This has happened during review bundle preparation and slows down otherwise deterministic handoff work.

## 3. Proposed Skill Name

Candidate name:

```text
review-bundle-zip-packager
```

Alternative names:

```text
source-relative-zip
review-zip-packager
```

## 4. Inputs

The Skill should accept:

### 4.1 File List

A newline-delimited list of files. Files may be absolute paths or paths resolvable from the current working directory.

Example:

```text
C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\cards\card_index.md
C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\cards\intellectual_archaeology.md
```

### 4.2 Relative Root Marker

A repository or path segment used to calculate source-relative zip entries.

Example:

```text
the-mindscape-of-bro-tsong
```

For the first example file above, the zip entry should be:

```text
cards/card_index.md
```

### 4.3 Output Zip Path

Absolute or cwd-relative path for the destination zip.

Example:

```text
C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\ccra_review_bundle\round-04_2026-06-18_blind-input-routing-evaluation\optional_raw_changed_files_04.zip
```

## 5. Expected Outputs

The Skill should produce:

- The output zip file.
- A validation summary printed to stdout.
- Optional machine-readable validation JSON next to the zip or printed to stdout when requested.

Recommended validation summary fields:

```json
{
  "status": "PASS",
  "output_zip": "absolute path",
  "source_file_count": 2,
  "zip_entry_count": 2,
  "entries": [
    "cards/card_index.md",
    "cards/intellectual_archaeology.md"
  ],
  "warnings": []
}
```

## 6. Required Behavior

- Preserve source-relative paths inside the zip.
- Use forward slashes in zip entry names.
- Fail fast if any listed file does not exist.
- Fail if any file cannot be made relative to the requested root marker.
- Fail if duplicate zip entry names would be produced.
- Overwrite the destination zip only after inputs validate.
- Verify the written zip by reading it back and comparing actual entries to expected entries.
- Print a clear PASS / FAIL result.

## 7. Safety Boundaries

- The Skill may create or overwrite only the requested output zip path.
- It must not delete source files.
- It must not modify source files.
- It must not recursively package directories unless a future explicit option is added.
- It must not silently ignore missing files.
- It must not flatten paths.
- It should reject output paths that are the same as one of the source files.

## 8. File Edits Allowed

Inside the client repository, this Skill should not edit files other than the requested output zip and optional validation sidecar.

Inside `skills-vault`, implementation may add normal Skill source files, tests, README updates, and install metadata.

## 9. Validation Expectations

Minimum validation cases for `skills-vault`:

- Two absolute files under the same root marker produce two source-relative entries.
- Mixed absolute and cwd-relative files produce correct entries.
- Existing destination zip is replaced safely.
- Missing source file fails before writing output.
- File outside the root marker fails.
- Duplicate relative entry names fail.
- Zip readback verifies exact entry list.
- Windows paths with backslashes are normalized to forward slashes in zip entries.

Suggested command shape:

```powershell
review-bundle-zip-packager `
  --file-list files.txt `
  --relative-root-marker the-mindscape-of-bro-tsong `
  --output C:\path\to\optional_raw_changed_files_04.zip `
  --verify
```

Exact CLI naming can be decided in `skills-vault`.

## 10. Why This Should Become A Reusable Skill

This is a deterministic file transformation and validation task that recurs across CCRA / GPT review workflows. It is not specific to QPI, Intellectual Archaeology, or this product's model library logic.

Moving it to `skills-vault` will:

- Reduce repeated manual zip failures.
- Preserve review bundle path correctness.
- Provide a reusable Windows-safe packaging command.
- Keep automation tooling out of the product repository.

## 11. Current Blocked / Affected Task

No current model extraction task is blocked. The need surfaced during Round 04 review bundle preparation, where manual zip creation required retries before source-relative paths were correct.

This request should be treated as a reusable workflow improvement before future review bundle rounds.