# Package Checklist

Use this reference when deciding what to include and how to verify the final package.

For Chinese-first wording and ready-to-adapt page / README examples, pair this checklist with `references/chinese-workflow-templates.md`.

## 1. Standard directory structure

Minimum recommended structure:

```text
<package-dir>/
  index.html
  README.md
  <report-1>.html
  <report-2>.html
  analysis_code/
    README.md
    <entrypoint>
    <config>
    <stage-script>
  analysis_data/
    README.md
    <input-data-1>
    <input-data-2>
  assets/
    <figures and shared media>
  <key-table-1>.csv
  <key-table-2>.csv
```

## 2. What belongs in `analysis_code/`

Include the smallest complete set of files needed to explain or reproduce the included pages and tables.

Usually include:
- main pipeline entrypoint
- active configuration file
- stage-specific analysis script
- figure-generation script used by included figures
- any helper that generated included CSV summaries

Usually exclude:
- abandoned exploratory scripts
- unrelated utility folders
- environment caches
- notebook checkpoints
- unsanitized config copies that still expose local absolute paths unless those paths are intentionally replaced with safe placeholders

## 3. What belongs in `analysis_data/`

Include the smallest approved data set that directly supports the package.

Usually include:
- cleaned clinical or metadata table used by the analysis
- processed assay / omics table used by the report
- grouping, label, mapping, or split-definition file
- data README or manifest

When raw or cleaned inputs cannot be shared, include:
- a manifest listing expected source files
- provenance notes describing how the analysis data were derived
- a short restriction note in `analysis_data/README.md`

## 4. Required labels and sections

Check that the package contains:
- requester / demand-side label
- analysis provider label
- reading order
- package contents overview
- code and data note
- explicit claim boundary

At least one HTML page and the README should make these easy to find.

## 5. ZIP workflow

From the parent directory of the package:

```bash
zip -rqX <package-name>.zip <package-dir-name>
unzip -l <package-name>.zip | sed -n '1,120p'
```

Good naming pattern:
- `<YYYYMMDD>_<project>_formal_delivery_package.zip`
- `<YYYYMMDD>_<topic>_formal_report_package.zip`

## 6. Acceptance checklist

Before delivery, verify all of the following:

- [ ] `index.html` exists and is the default entry page
- [ ] `README.md` exists
- [ ] `analysis_code/README.md` exists
- [ ] `analysis_data/README.md` exists
- [ ] requester / provider labels are present
- [ ] HTML titles and H1 headings are populated
- [ ] forbidden internal phrases are absent
- [ ] recipient-facing正文不含 OCR / 脱敏 / 素材清洗 / 截图整理 / 已移除作者名等过程说明
- [ ] local absolute paths are absent
- [ ] code/data folders match the included results
- [ ] ZIP has been rebuilt after the latest edits
- [ ] ZIP contents were checked, not assumed

## 7. Suggested audit command

```bash
python3 ~/.codex/skills/formal-delivery-package/scripts/audit_formal_package.py <package_dir> \
  --required index.html \
  --required README.md \
  --required analysis_code/README.md \
  --required analysis_data/README.md \
  --required-text 'README.md::需求方' \
  --required-text 'README.md::分析提供方' \
  --forbidden '对外正式交接' \
  --forbidden 'teacher package' \
  --forbidden 'handoff' \
  --forbidden 'OCR 脱敏整理' \
  --forbidden '素材清洗后' \
  --forbidden '已移除作者名'
```

If the package is English-first, swap required text checks to the English labels.

## 8. Decision rule: patch vs rebuild

Patch locally when:
- one figure changed
- one HTML page changed
- one CSV changed
- the directory structure is already correct

Rebuild the package directory when:
- page naming changes
- role labels are missing everywhere
- code/data folders need to be added
- multiple pages share stale tone or stale links
- the old package was built for a different audience or different framing
