/start

name: start
description: Begin the shift from the punch list without asking, so scheduled and headless runs behave like interactive ones.
license: MIT
metadata:
  internal: true

Start a Nightshift run in the host-opened project.

Resolve `$NIGHTSHIFT_PLUGIN_ROOT` to the copy this host installed, as an absolute path. On Claude Code that is `${CLAUDE_PLUGIN_ROOT}`, on Cursor `${CURSOR_PLUGIN_ROOT}`, and on Codex `$PLUGIN_ROOT` when set. A skill loaded from a copy another host installed is the wrong runtime — use the copy under this host's plugins directory. When none of those is set, use the absolute path this skill was attached from (`skills/start/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.

When a verdict names your host — permission modes, resume commands, the sandbox and identity rules that belong to it — open `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/hosts/<host>.md` for the host you are on, and no other. Not before a verdict names it.

1. Preflight — one helper, one verdict per line

**With work in the punch list, this command asks nothing.** It reads the list, arms the site and works — which is what lets cron run it at 04:00 and lets the watchman revive it after a crash. It promotes nothing on its own: what is in the punch list is the shift, exactly as the owner left it.

The one time it speaks is when the punch list is **empty**. Then there is no work to do silently, so it looks at waiting plans, staged drafts and pending Hunt orders and asks which to promote.

"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" start-preflight --host claude

Pass the host you are actually running on (`claude`, `codex`, or `cursor`). Every line it prints is one verdict, and it explains itself:

• **`ok <topic> <detail>`** — a resolved fact. Report it if the owner asked; otherwise continue.
• **`warn <topic> <detail>`** — say it once in plain English, then arm anyway. The choice stays the

owner's.

• **`refuse <topic> <detail>`** — do not arm. Print the `explain` and `repair` lines that follow it

verbatim and stop.

Exit status 0 means the shift may arm; non-zero is a refusal; 2 is a usage error in the call you just made. An `explain` line says what the verdict means and a `repair` line is the exact action — relay them, do not restate them, and never invent an explanation the helper did not print.

Two rules are policy rather than mechanics, so they are yours to hold whatever a verdict says: never kill a live watchman and never start a second shift beside one; and never clear `STOP` or invent a time budget for a paused shift whose deadline has passed.

2. The punch list is the shift

**Inspect capabilities in the skill.** Read manifests, lockfiles, and `## Gates` in the work target. `$NS/run/capabilities.json` is a cache the model may update after a successful tooling commit only; no detector is required.

**Permission gaps are parked, never asked.** Run `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" preflight-needs` against every item now in `## Items`. For each item with a gap, run `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" park-needs` to add its entry to `$NS/inbox/parking-lot.md` naming the missing category, then append one `$NS/run/shift-log.md` line listing every gapped item. Work everything else. If either helper exits because no JSON parser is installed, park the gaps in the skill and continue; neither is on the armed path.

If `$NS/punch-list.md` has at least one open `- [ ]` under `## Items`, that is the work — start it. Do not promote, cut, or add anything: parked orders and drafts stay exactly where the owner left them. An empty `## Items` section still keeps the Shift contract and Gates; they bind whatever Hunt or Start cuts next.

**Resume the active product cycle before rediscovery.** When the open item is product evolution, inspect `$NS/product/opportunity-map.md` for its single `Status: building` entry before doing new research or selecting work. Its `Next` action and `Verify remaining` are the continuation point. More than one building entry is inconsistent state: keep the earliest one active, mark the others `candidate`, record the repair in `$NS/run/shift-log.md`, and continue.

**Only when the punch list is empty, offer what is staged.** The `ok staged` verdict already counts the plans in `$NS/staging/plans/`, `$NS/staging/work-orders.md` and `$NS/staging/drafting-table.md`. Read them (a file that is not there holds nothing), show what they hold in one short list, plans first by name with their open items, and ask which to work now.

**A plan is cut whole.** A plan file is a complete punch list: its contract, gates, plan notes and items. When the owner picks one, it replaces `$NS/punch-list.md` and is removed from `$NS/staging/plans/`: move the file over the punch list, never copy it. If the punch list still holds ticked items that Archive has not filed, run Archive first so they are filed with their shift; nothing in the old list is dropped. The plan's title line, `# Punch List — <name>`, names the shift, and Archive files it under that name.

For a draft or an order, on the owner's choice, **cut it — move, never copy**: the item goes under `## Items` and is removed from the file it came from, so it never exists in two places. An imported draft (`Status: proposed` and a canonical `Source:` GitHub URL) is cut the same way in the skill — move the item under `## Item