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:

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:

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:

review-bundle-zip-packager

Alternative names:

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:

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:

the-mindscape-of-bro-tsong

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

cards/card_index.md

4.3 Output Zip Path

Absolute or cwd-relative path for the destination zip.

Example:

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:

{
  "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:

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.