/archive

name: archive
description: File finished shift state into a dated archive so the live files stay lean.
license: MIT

Archive the finished paperwork for the host-opened project. This files records — it never does shift work, never ticks a box, never touches the contract.

The four state files and what each holds are in `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/shift/state-map.md`. Archive each by its own lifecycle; never reclassify one as another.

Resolve the installed plugin root to an absolute `$NIGHTSHIFT_PLUGIN_ROOT` — `${CLAUDE_PLUGIN_ROOT}` on Claude Code, `$PLUGIN_ROOT` on Codex when set, otherwise the absolute path this skill was attached from (`skills/archive/SKILL.md`). Run every command below through `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns"` — native Windows: `& "$NIGHTSHIFT_PLUGIN_ROOT\runtime\windows\ns.ps1"` in the PowerShell tool, same verbs — which resolves the host and the workspace; `ns help` lists the verbs, and `ns bind` prints the six resolved facts (`TASK_ROOT`, `NIGHTSHIFT_WORKSPACE`, `NS`, `NIGHTSHIFT_PLUGIN_ROOT`, `HOST`, `SOURCE`); `$NS` below is that `NS`. Never a bare relative path: the working directory persists between calls.

Read `$NS/state-version` first. Legacy (missing) and current (`1`) may be archived. A newer or malformed marker fails closed — file nothing, rewrite nothing, and never migrate. `state-version` itself stays live; it is not an archive record.

In artifact mode the work target is a persistent folder, not a Git repository. File the same Nightshift records; do not require a work-target commit that cannot exist. Copy live receipts with `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" archive-receipts`, and pass `--retire <receipt-name>` once per ticked item (native Windows: `-Retire` with those names as one comma-separated list). Missing or empty receipts create no dated receipts folder. A receipts path that is not a usable directory is a refuse, not an empty skip.

If `$NS/.pending-filing` exists, a shift asked for filing at clock-out. It carries `date=` and `shiftId=` lines naming that shift — use them — and an `asked=1` line once the gate has held the session to ask for it. Delete the marker once filing is done, and only then. Nothing else about it is special: file the same way you would on any explicit Archive.

`$NS/.ended` names the shift that finished and where it files, in `shiftId=`, `archiveRoot=` and `archiveLayout=` lines. Those are what a later Archive follows: clock-out has already archived the policy that carried them.

**Filing is a copy.** A ticked item's receipt leaving live storage is a separate step, and the agent running Archive takes it from `$NS/punch-list.md` — not later, not the owner, and not by guessing. `--retire` with one record name, repeated once per ticked item on POSIX; on native Windows, `-Retire` takes those names as a single comma-separated list. Receipts of open items are never named. The morning receipt is named only when that shift has ended and no open item still needs it. Once the shift has ended, the helper also retires every ticked item's receipt it filed, even if a name was missed. It will not retire an open item's receipt.

Before naming anything, read `$NS/punch-list.md` and the records themselves. A shift can end with items still open — `STOP` and the deadline both do that — so `.ended` is not a reason to leave a ticked receipt live, and it is not a reason to pull an open one. Keep a record live when an open item, an unanswered parking decision or work carried into the next shift still needs it, and when you cannot tell who owns it. Rejected work is filed with its rejection, never erased. A name the helper did not file is refused and told back to you.

Where it goes

Everything lands under the archive root, which is `archive.root` in the resolved policy, in `<YYYY-MM-DD>/` or `shift-<id>/` according to `archive.layout`. Left alone those give the default `$NS/archive/<YYYY-MM-DD>/`, and receipts land in `archive/<YYYY-MM-DD>/receipts/` under it. Today's date is `date +%Y-%m-%d` on POSIX, or `Get-Date -Format yyyy-MM-dd` on native Windows. One folder per archive run; create parents, and re-running on the same day appends to that day's files.

**The receipts keep working from where they land.** The helper repoints their links: a record that travelled with them stays a sibling, a record that stayed live is reached back through the archive. That rewriting changes bytes, so the untouched original is preserved beside each rewritten file, under the same name with an "original" suffix. Do not hand-edit either one.

What moves, what stays

• **Punch list → `shipped.md`.** Move every ticked `- [x]` line under `## Items` in

`$NS/punch-list.md` into the archive's `shipped.md` under a `## Shipped <date>` heading — that file reads as the plain record of what actually landed. Open `- [ ]` items and everything above `## Items` (the contract, the gates) stay exactly where they are. When that move leaves zero open boxes, append one reminder under `## Notes` (create the heading below `## Items` if it is missing): leftover Shift contract and Gates still bind the next Hunt or Start cut; review them before composing a new campaign; Archive does not reset them. Skip the note when open work remains, when the same sentence is already present, or if adding it would require an open checkbox. Never write `- [ ]` here and never edit above `## Items`.

• **Receipts — the ticked ones.** For each ticked item, pass `--retire <receipt-name>`; receipts

of open items are never named. `archive-receipts` rebuilds `receipts/README.md` on both sides of the move so each index lists only the receipts in its own folder.

• **Shift log → the archive, whole.** Move `$NS/shift-log.md` into

the folder and start a fresh one with the same one-line header. The journal is mechanical; its lines belong to the dates they happened.

• **Snag log — only what's handled.** `archive-receipts` moves entries that carry a disposition