/archive

name: archive
description: File a finished shift into its own archive folder, laid out like the live site, so the live files keep only open work.
license: MIT
metadata:
  internal: true

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. Each `$NS/...` path below is where the current layout keeps that file; `ns path <key>` prints where this workspace keeps it, and `ns path --list` names every key.

Read `$NS/state-version` first. Legacy (missing), `1` and the current `2` 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/run/.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/run/.ended` names the shift that finished and where it files, in `shiftId=`, `archiveRoot=`, `archiveLayout=`, `shiftName=` and `archiveFolder=` lines. Clock-out claimed that folder for the shift, and every later Archive of it returns there, whatever day it runs.

**Only what is closed is filed.** Each record lives in one place: filed once it is closed, live while it is open. Filing is a copy: nothing leaves live storage until its filed copy reads back. 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: they stay live and are not filed. 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

Each shift has one folder under the archive root (`archive.root` in the resolved policy), named by `archive.layout`:

• `date` (the default): `<YYYY-MM-DD>/`, and a later shift that day `<YYYY-MM-DD>-shift-2/`,

`-shift-3/` and so on.

• `shift`: `shift-<id>/`.
• `name`: the name on the punch list's title line, as in `# Punch List — Archive follow-ups`, so

`archive-follow-ups/`.

• `date-name`: both, `<YYYY-MM-DD>-archive-follow-ups/`.

A shift with no name files by date under `name` and `date-name`, and a second shift under the same name takes `-shift-2`. The folder records its shift in `.shift-id`; another shift never writes into it, and filing the same shift again returns to it. `archive-receipts` prints the folder; receipts land in its `receipts/`, which is `archive/<YYYY-MM-DD>/receipts/` by default. A shift that never reached clock-out has no claimed folder yet and files by today's date: `date +%Y-%m-%d` on POSIX, or `Get-Date -Format yyyy-MM-dd` on native Windows.

**The folder is laid out like the live site.** Every record sits at the path it has under `$NS/`:

archive/<folder>/
├── .shift-id
├── punch-list.md            the contract and the ticked items
├── receipts/                the receipts of ticked items, the morning page, and an index of this folder
├── inbox/
│   ├── parking-lot.md       the answered decisions
│   └── snag-log.md          the findings with a disposition
└── run/
    ├── shift-policy.json    filed by clock-out
    ├── shift-log.md
    ├── usage/               the shift's usage readings
    └── evidence/findings.jsonl   filed by clock-out, when the shift used it

Links between those records keep working as written. A link to a record that stayed live — the drafting table, a receipt of an open