@wildorder/nightshift 0.1.0 → 0.3.0

package/dist/skill-roots.js

@@ -0,0 +1,181 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const SPECS = [
+    {
+        target: "claude",
+        label: "Claude Code",
+        configDir: ".claude",
+        homeEnv: "CLAUDE_CONFIG_DIR",
+        userSkills: (configHome) => join(configHome, "skills"),
+        projectSkills: join(".claude", "skills"),
+        extraScan: ({ home, projectRoot }) => [
+            { kind: "command", scope: "project", root: join(projectRoot, ".claude", "commands") },
+            { kind: "command", scope: "user", root: join(home, ".claude", "commands") },
+        ],
+    },
+    {
+        target: "cursor",
+        label: "Cursor",
+        configDir: ".cursor",
+        userSkills: (configHome) => join(configHome, "skills"),
+        projectSkills: join(".cursor", "skills"),
+        // Cursor also reads the cross-tool .agents tree and Claude's skills dir,
+        // so a definition in either shadows what we install.
+        extraScan: ({ home, projectRoot }) => [
+            { kind: "command", scope: "project", root: join(projectRoot, ".cursor", "commands") },
+            { kind: "command", scope: "user", root: join(home, ".cursor", "commands") },
+            { kind: "skill", scope: "project", root: join(projectRoot, ".agents", "skills") },
+            { kind: "skill", scope: "project", root: join(projectRoot, ".claude", "skills") },
+            { kind: "skill", scope: "user", root: join(home, ".agents", "skills") },
+            { kind: "skill", scope: "user", root: join(home, ".claude", "skills") },
+        ],
+    },
+    {
+        target: "codex",
+        label: "Codex",
+        configDir: ".codex",
+        homeEnv: "CODEX_HOME",
+        // Codex discovers skills in the cross-tool .agents directory, which does
+        // not move with CODEX_HOME — so detection and the write root diverge here
+        // on purpose.
+        userSkills: (_configHome, home) => join(home, ".agents", "skills"),
+        projectSkills: join(".agents", "skills"),
+        extraScan: ({ configHome }) => [
+            { kind: "skill", scope: "user", root: join(configHome, "skills") },
+        ],
+    },
+    {
+        target: "gemini",
+        label: "Gemini CLI",
+        configDir: ".gemini",
+        userSkills: (configHome) => join(configHome, "skills"),
+        projectSkills: join(".gemini", "skills"),
+    },
+    {
+        target: "openclaw",
+        label: "OpenClaw",
+        configDir: ".openclaw",
+        userSkills: (configHome) => join(configHome, "skills"),
+        projectSkills: "skills",
+        extraScan: ({ configHome }) => [
+            { kind: "skill", scope: "user", root: join(configHome, "workspace", "skills") },
+        ],
+    },
+];
+export const ALL_TARGETS = SPECS.map((spec) => spec.target);
+export const DEFAULT_TARGETS = ALL_TARGETS.join(",");
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The escape hatch for a layout this package does not know about. */
+export function overrideEnvName(target) {
+    return `NIGHTSHIFT_SKILLS_ROOT_${target.toUpperCase()}`;
+}
+export function parseTargets(value) {
+    const values = value
+        .split(",")
+        .map((target) => target.trim().toLowerCase())
+        .filter(Boolean);
+    const invalid = values.filter((target) => !ALL_TARGETS.includes(target));
+    if (invalid.length > 0) {
+        throw new Error(`Unknown target(s): ${invalid.join(", ")}. Expected: ${ALL_TARGETS.join(", ")}.`);
+    }
+    return [...new Set(values)];
+}
+/** `--root claude=/path` entries into a per-target override map. */
+export function parseRootOverrides(entries) {
+    const overrides = {};
+    for (const entry of entries) {
+        const separator = entry.indexOf("=");
+        if (separator < 1) {
+            throw new Error(`Invalid --root "${entry}"; expected <target>=<path>, e.g. claude=/opt/claude/skills.`);
+        }
+        const [target] = parseTargets(entry.slice(0, separator));
+        const path = entry.slice(separator + 1).trim();
+        if (!target || !path) {
+            throw new Error(`Invalid --root "${entry}"; expected <target>=<path>, e.g. claude=/opt/claude/skills.`);
+        }
+        overrides[target] = resolve(path);
+    }
+    return overrides;
+}
+function configHomeFor(spec, home, env) {
+    const override = spec.homeEnv ? env[spec.homeEnv]?.trim() : undefined;
+    return override ? resolve(override) : join(home, spec.configDir);
+}
+/**
+ * Resolve every target's roots and report which tools are actually present.
+ * Detection is what keeps an install from creating config directories for
+ * tools the developer does not use.
+ */
+export async function detectTargets(context = {}) {
+    const env = context.env ?? process.env;
+    const home = resolve(context.home ?? homedir());
+    return Promise.all(SPECS.map(async (spec) => {
+        const configHome = configHomeFor(spec, home, env);
+        const flag = context.roots?.[spec.target];
+        const envOverride = env[overrideEnvName(spec.target)]?.trim();
+        let userRoot;
+        let source;
+        if (flag) {
+            userRoot = resolve(flag);
+            source = "flag";
+        }
+        else if (envOverride) {
+            userRoot = resolve(envOverride);
+            source = "env";
+        }
+        else {
+            userRoot = spec.userSkills(configHome, home);
+            // The tool's own home variable only counts as the source when it
+            // actually moved the skills root; for Codex it moves detection only.
+            const fromDefaultHome = spec.userSkills(join(home, spec.configDir), home);
+            source = userRoot === fromDefaultHome ? "default" : "env";
+        }
+        return {
+            target: spec.target,
+            label: spec.label,
+            userRoot,
+            projectRoot: spec.projectSkills,
+            configHome,
+            detected: await pathExists(configHome),
+            source,
+        };
+    }));
+}
+/**
+ * Every root worth scanning for a competing definition of a workflow: each
+ * target's own skills roots at both scopes, plus the command directories and
+ * cross-tool trees that shadow them.
+ */
+export function scanRoots(detected, projectRoot, home) {
+    const roots = [];
+    const byTarget = new Map(detected.map((entry) => [entry.target, entry]));
+    for (const spec of SPECS) {
+        const entry = byTarget.get(spec.target);
+        if (!entry)
+            continue;
+        roots.push({
+            target: spec.target,
+            kind: "skill",
+            scope: "project",
+            root: join(projectRoot, entry.projectRoot),
+        }, { target: spec.target, kind: "skill", scope: "user", root: entry.userRoot });
+        for (const extra of spec.extraScan?.({
+            home,
+            projectRoot,
+            configHome: entry.configHome,
+        }) ?? []) {
+            roots.push({ target: spec.target, ...extra });
+        }
+    }
+    return roots;
+}
+//# sourceMappingURL=skill-roots.js.map

package/dist/skill-roots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-roots.js","sourceRoot":"","sources":["../src/skill-roots.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildorder/nightshift",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The crew that builds while you're gone: walk-away, CI-dispatched engineering programs with a decision ledger instead of gates",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,8 @@
   },
   "files": [
     "dist",
+    "skills",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/skills/init-project/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: init-project
+description: Initialize a new repository or adopt an existing one into the nightshift structure, including deriving the vision and as-built docs from existing code. Use when a user asks to set up, initialize, or onboard a project for nightshift.
+argument-hint: "[project-root]"
+disable-model-invocation: true
+---
+
+# Initialize or adopt a project
+
+Use the supplied argument as the project root. When omitted, use the current
+working directory.
+
+## Step 1 — Detect project type
+
+Inspect the root. If it contains source code, a populated README, or other
+project documentation, treat this as a **brownfield adoption**. An empty or
+near-empty directory is a **greenfield initialization**.
+
+## Step 2 — Ask about version control upfront
+
+Check whether the root is inside a git repository
+(`git rev-parse --is-inside-work-tree`). Ask these questions now, alongside
+the project questions — never defer them to a suggested next step:
+
+1. If it is **not** a repository: "Initialize a git repository here?" If yes,
+   run `git init` before any scaffolding so everything that follows is
+   tracked from the start.
+2. In all cases: "Commit the nightshift setup when finished?" If yes, plan to
+   commit at the end of this workflow.
+3. Brownfield with uncommitted changes: point out the dirty tree and confirm
+   that the final commit should include only the files this setup created or
+   modified, keeping the user's in-progress work out of it.
+
+Record the answers and apply them in Step 6. Git is not optional decoration
+for nightshift: the decision ledger tags commits and replays roll back to
+them, so if the user declines a repository entirely, warn that decision
+replay, rollback, and per-workstream checkpoints will all be unavailable,
+then proceed.
+
+## Step 3 — Gather project information
+
+The initializer resolves defaults on its own: name and description from
+`package.json`, and the stack by scanning manifests (package.json,
+tsconfig.json, pyproject.toml, go.mod, Cargo.toml).
+
+- Greenfield: ask for the project name, stack, and one-line description, and
+  wait for the response.
+- Brownfield: state the values you expect detection to produce and ask only
+  about gaps or corrections. Do not re-ask for what the repository already
+  declares.
+
+### Agent roles
+
+Also ask which agent CLI (and model) fills each of nightshift's roles. Never
+leave this implicit — it is the most consequential configuration in the
+project. Each block in `nightshift.config.json` declares a command, args, and
+prompt mode, spelled in that CLI's own vocabulary:
+
+1. **Implementer** (`agent`) — executes each workstream. A cheaper model is
+   usually the right call, for example
+   `{ "command": "claude", "args": ["-p", "--model", "sonnet"], "promptMode": "stdin" }`.
+2. **Decider** (`deciderAgent`) — makes, ratifies, or escalates the decisions
+   agents surface during a run, and composes the human notification when one
+   is warranted. Decisions are the highest-leverage, lowest-token work in a
+   run, so recommend the most capable model available here — and a
+   **different provider than the implementer**, because ratifying the
+   implementer's own choices with the implementer's own model re-creates the
+   self-grading conflict this role exists to remove. If the user picks the
+   same provider anyway, note the tradeoff and respect the choice.
+3. **Reviewer** (`reviewerAgent`) — the independent second opinion: spec
+   critique before build, test critique after each workstream, whole-program
+   review at the end. Recommend a different provider than the implementer.
+   Leave the model flag out of its args and let the external CLI run its own
+   default — the role wants an uncorrelated second opinion, which that
+   default already is, and a named model is one more thing to go stale.
+4. **Recovery** (`recoveryAgent`, optional) — retries failed workstreams. A
+   distinct provider also lets a run survive a primary quota, token, or
+   session failure. Skip it if the user has no second implementer available.
+
+An absent `deciderAgent` does not break runs — implementer defaults simply
+stand unratified, and the run report says so — but recommend configuring it:
+it is the difference between "decisions were made" and "decisions were
+reviewed". An absent `reviewerAgent` disables the review passes entirely and
+is reported, never silently substituted.
+
+If the user has no preference, record the host's current model for the
+implementer and recommend a distinct decider and reviewer. Roles can be
+filled in later, but say so explicitly in the report — a run started before
+`agent` is set aborts immediately.
+
+Ask the Step 2 and Step 3 questions together in one message when possible.
+
+## Step 4 — Run the deterministic initializer
+
+```sh
+npx --yes @wildorder/nightshift init --cwd "{project-root}"
+```
+
+Always invoke the CLI by its full package name. The executable is named
+`nightshift`, but the package is `@wildorder/nightshift` — a bare
+`npm exec nightshift` only resolves when the *shell's* working directory
+already has the package installed, and otherwise queries the registry for the
+unscoped name, which is not this package. That is the common case here,
+because `init` usually targets a project root that has no `node_modules` yet.
+
+Add `--name`, `--stack`, or `--description` only for values the user supplied
+or detection cannot provide. Do not manually reproduce the templates; the CLI
+is the canonical write path. It:
+
+- creates the standard directories and any missing starter files without
+  overwriting existing ones;
+- merges the universal directives into an existing `AGENTS.md` by adding or
+  refreshing only the marked `BEGIN/END UNIVERSAL` block, leaving all other
+  content untouched;
+- prefills `verify` commands from `package.json` scripts and records existing
+  markdown documentation as `contextDocs` in `nightshift.config.json`.
+
+The universal directives come from the packaged template by default; a user
+override is honored from `~/.nightshift/universal-directives.md`, or pass
+`--directives <path>` when the user names a directives file.
+
+After the initializer runs, write the role decisions from Step 3 into
+`nightshift.config.json`, for example:
+
+```json
+"agent": { "command": "claude", "args": ["-p", "--model", "sonnet"], "promptMode": "stdin" },
+"deciderAgent": { "command": "codex", "args": ["exec", "--model", "gpt-5.4"], "promptMode": "stdin" },
+"reviewerAgent": { "command": "codex", "args": ["exec"] }
+```
+
+Before moving on, re-read the file and confirm the blocks the user chose are
+all present. When adopting a project whose `nightshift.config.json` already
+existed, check it for the same blocks and add whichever the user asked for.
+
+## Step 5 — Confirm workflow skills are present
+
+Check whether the project already contains installed nightshift skills
+(`.cursor/skills/`, `.claude/skills/`, `skills/`, `.agents/skills/`, or
+`.gemini/skills/`). If any target is present, the team has already chosen
+its targets — do not install more, and do not re-run the installer.
+
+Only when no target is installed at all (for example, when initializing a
+different project root than the one this skill is running from), ask the
+user which targets they want and run:
+
+```sh
+npx --yes @wildorder/nightshift install --cwd "{project-root}" --targets {chosen}
+```
+
+Never use `--force` unless the user explicitly approves replacing a reported
+skill conflict.
+
+## Step 6 — Brownfield enrichment
+
+Skip this step for greenfield projects.
+
+1. **Snapshot reality.** Scan the codebase — entry points, schema files,
+   route registrations, shared contracts, infrastructure config — and write
+   `docs/as-built.md`, noting it as the initial adoption snapshot. This
+   grounds all later planning in what actually exists.
+2. **Author the vision.** The CLI scaffolded `docs/vision.md` as a template.
+   Draft its real content from the as-built snapshot plus a short interview:
+   what the product is for, target users, where it is heading, and what is
+   explicitly out of scope. Write the draft directly to `docs/vision.md` —
+   the file is the review surface; do not paste the content into the
+   conversation for approval. Summarize briefly and invite edits, applying
+   them to the file in place.
+3. **Complete `AGENTS.md`.** Fill the project Conventions section from
+   observed practice — lint and formatter configs, test layout, naming
+   patterns — and confirm the generated dependency table reflects the
+   packages that matter.
+4. **Curate `contextDocs`.** Review the detected list in
+   `nightshift.config.json`: remove documents that are stale or irrelevant
+   and add any the user names. Planning reads every listed document, so the
+   list should be signal, not bulk.
+
+## Step 7 — Apply the version-control decisions
+
+Execute what the user approved in Step 2:
+
+- If a commit was approved, stage exactly the files this setup created or
+  modified and commit with a message like `chore: adopt nightshift`.
+  Do not stage unrelated in-progress changes.
+- If the user declined, leave the working tree as is.
+
+## Step 8 — Report
+
+Report:
+
+1. Files created, updated, and skipped.
+2. Skill conflicts, if any.
+3. Warnings from the initializer.
+4. The configured agent roles, and which roles were deferred.
+5. Brownfield: the as-built and vision drafts produced and any assumptions.
+6. Git actions taken (repository initialized, setup committed) or declined.
+7. Next step: invoke `/plan-program` for the first program.

package/skills/plan-program/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: plan-program
+description: Plan a new engineering program or product phase, define architecture changes and workstreams, and produce the canonical program document and manifest. Use when turning a feature set into an executable program plan.
+argument-hint: "[program-id] [feature-set-or-phase]"
+disable-model-invocation: true
+---
+
+# Plan a program
+
+Plan a new feature set or phase for the current project. This is one of the
+two places a human exercises judgment in nightshift; everything downstream is
+a walk-away run, so the plan you produce here is the last routine chance to
+shape the work interactively. Write every artifact for a human reader first —
+the run's trust surface is its artifacts.
+
+## 1. Load project context
+
+Read:
+
+- The vision document at `visionPath` from `nightshift.config.json`, the
+  anchor product vision. Use `docs/vision.md` only when no configuration
+  exists.
+- `docs/as-built.md`, when present, for current system state.
+- `AGENTS.md` for repository directives and conventions.
+- Every document listed in `contextDocs` from `nightshift.config.json`, when
+  present.
+- When re-planning after a run, the program's run report and decision ledger
+  under `docs/programs/` — a prior run's parked workstreams, risk-accepted
+  findings, and recorded decisions are planning input, not noise. Plan from
+  the repository state that exists now, not from the original pre-program
+  design; treat work a prior run verified and committed as current
+  architecture rather than scheduling it again, and give replacement work new
+  workstream IDs and task-file paths so nothing overwrites the historical
+  record.
+
+If no vision document exists at the resolved path, stop. Explain that it
+should contain the product description, architecture, target users, API
+surface, data model, phase scope, and technology stack. For a new repository,
+suggest the `init-project` skill.
+
+If `docs/as-built.md` is absent, note that this is likely the first program
+and proceed.
+
+## 2. Gather requirements
+
+Resolve these values from the arguments or ask for anything missing:
+
+1. The feature set or phase to build.
+2. A lowercase, hyphenated program ID, such as `phase-2-durable`.
+
+Wait for the user's response when questions are required.
+
+### Select the execution mode
+
+Choose the mode before decomposing the work and record the decision in both
+artifacts. Default to `atomic` unless there is positive causal evidence that
+orchestration is necessary.
+
+- **`atomic`** — one cohesive agent working set, one implementation brief,
+  and one green commit. Choose this when a capable coding agent can own the
+  whole change coherently and intermediate checkpoints add no material safety
+  or parallelism.
+- **`orchestrated`** — multiple independently-green workstreams executed as a
+  dependency graph. Choose this when the minimum static context physically
+  cannot fit one agent session, independent work provides material
+  parallelism, independently deployable service boundaries matter, or a
+  shared-contract migration requires expand → migrate consumers →
+  contract/delete ordering.
+
+Do not choose orchestrated merely because the feature is important, spans
+many files, or has a high estimated token count. State the concrete evidence
+in `program.executionModeReason`. In atomic mode create exactly one
+workstream covering the entire program, with no dependencies and task file
+`tasks/{program-id}/implementation.md`. In orchestrated mode use the
+decomposition and checkpoint rules below.
+
+## 3. Draft the program document
+
+Inspect `docs/programs/` for an existing `*-program.md`. Match its structure
+when one exists. Otherwise use:
+
+```markdown
+# {Project Name} — Program Plan ({Program Name})
+
+## Program Overview
+**Product:** [From the vision.]
+**Program scope:** [What this program delivers.]
+
+## Execution Mode
+**Mode:** atomic | orchestrated
+**Reason:** [Concrete causal evidence for the choice.]
+
+## Strategic Goals
+[Three to five outcome-focused bullets.]
+
+## Architecture Changes
+[Changes from the system in as-built.md. For the first program, describe the full architecture.]
+
+## Technology Choices
+[Only new choices. If none: "No new technology — uses existing stack."]
+
+## Anticipated Decisions
+[Choices you can already see the run will face — API shapes, data-model
+tradeoffs, library picks — with your leaning and why. The decider reads
+these; a decision anticipated here is a decision the run handles better.]
+
+## Risk Register
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+[Key risks.]
+
+## Success Criteria, Workstreams, and Scope
+Canonical in `docs/programs/{program-id}-manifest.json`: success-criteria
+text, the workstream roster, dependencies, sizes, scope, and exclusions live
+there and only there. This document refers to them by id (`SC-xx`, `WS-xx`)
+and never restates their text.
+```
+
+The program document carries only what the manifest cannot: narrative
+architecture, causal reasoning, anticipated decisions, and risks. Success
+criteria, the workstream table, the dependency graph, and scope in/out lists
+are manifest data — do not reproduce them here. Two copies of the same fact
+drift apart; one canonical home per fact is a founding rule of this system.
+When this section's rule and an older program document's structure conflict,
+this rule wins: delete the duplicated sections rather than matching them.
+
+Write the draft directly to `docs/programs/{program-id}-program.md`. Do not
+paste the document into the conversation or ask for approval before saving —
+the file is the review surface, not the chat window.
+
+## 4. Generate the manifest
+
+If `docs/programs/` contains an existing `*-manifest.json`, match its schema
+exactly. Otherwise use:
+
+```json
+{
+  "program": {
+    "id": "{program-id}",
+    "name": "{Program Name}",
+    "description": "{one-line description}",
+    "status": "planning",
+    "created": "{YYYY-MM-DD}",
+    "executionMode": "atomic|orchestrated",
+    "executionModeReason": "{concrete causal evidence}"
+  },
+  "technology": {},
+  "successCriteria": [
+    { "id": "SC-01", "description": "{verifiable outcome}" }
+  ],
+  "packages": [
+    {
+      "name": "{package-name}",
+      "path": "{relative-path}",
+      "description": "{purpose}"
+    }
+  ],
+  "workstreams": [
+    {
+      "id": "WS-01",
+      "name": "{Workstream Name}",
+      "taskFile": "tasks/{program-id}/{ws-id}-{slug}.md",
+      "status": "not_started",
+      "size": "S|M|L",
+      "scope": {
+        "summary": "{one line: what this workstream owns}",
+        "includes": ["{specific thing it covers}"],
+        "excludes": ["{specific thing it deliberately does not cover}"]
+      },
+      "dependencies": [],
+      "packages": []
+    }
+  ],
+  "outOfScope": []
+}
+```
+
+Save it directly to `docs/programs/{program-id}-manifest.json`.
+Keep the manifest, program document, and every referenced `taskFile`
+trackable by Git — nightshift tags decisions to commits and replays roll back
+to them, so a plan that exists only in an ignored working tree is neither
+reproducible nor replayable. If the repository ignores `tasks/` or
+`docs/programs/`, remove those ignore rules or explicitly force-add these
+canonical artifacts.
+
+For `atomic`, the `workstreams` array contains exactly one whole-program
+workstream (`WS-01`) whose `taskFile` is
+`tasks/{program-id}/implementation.md`. For `orchestrated`, it contains the
+dependency graph described in the program document.
+
+### Scope is load-bearing, not decoration
+
+`scope` is required on every workstream, and the reason is worth
+understanding before you write them.
+
+Authoring spawns one clean agent per workstream, and every one of those
+agents is handed the roster of the whole program — each workstream's id,
+name, and scope, and nothing else. That roster is how an author discovers
+that another workstream already owns something it was about to build, or
+produces something it needs. An author that cannot tell what `WS-12` covers
+will not merely omit a dependency; it will reimplement WS-12's work.
+
+So write these for a reader who has no other information about that
+workstream:
+
+- **`summary`** — one line naming what it owns. "Auth improvements" tells an
+  author nothing. "Issues, rotates, and validates auth tokens" tells it
+  everything it needs to decide whether to depend on this.
+- **`includes`** — the specific capabilities inside the boundary.
+- **`excludes`** — the specific capabilities deliberately outside it. These
+  carry more weight than they look. An exclusion tells every other author
+  that something is *not* covered here, which prevents both duplicated work
+  and a requirement that silently belongs to nobody. If a workstream's
+  neighbors might reasonably assume it handles something, say that it does
+  not.
+
+### Every orchestrated workstream is an independently green checkpoint
+
+Design the roster so that, starting from a green repository containing only
+its declared dependencies, each workstream can finish with every configured
+build, typecheck, test, and lint command still green. A later workstream must
+never be required to repair an earlier checkpoint — and in nightshift this
+matters doubly, because a failed workstream is parked while everything
+outside its downstream cone still builds; a roster whose checkpoints lean on
+later repair work turns one parked workstream into a broken partial build.
+
+For a shared contract migration, prefer an explicit sequence:
+
+1. **Expand** — introduce the new contract while preserving compatibility.
+2. **Migrate** — move bounded consumer groups in independently green batches.
+3. **Contract/delete** — remove the compatibility surface only after every
+   consumer migration is complete.
+
+The destructive cleanup depends on every migration workstream. Do not place
+foundational deletion first merely because it is conceptually central.
+
+## 5. Hand off for review
+
+Both files now exist on disk. Reply with a short summary only — program
+scope in a sentence, selected execution mode and reason, workstream count,
+critical path, and links to the two file paths — and invite the user to
+review the files and request changes. Apply any requested edits to the files
+in place.
+
+Do not create workstream specs in this workflow, and do not offer to. Specs
+are written by the packaged runner, one clean agent per workstream, as
+narrative documents a human can review. Point the user at the run command
+and stop:
+
+```sh
+npx --yes @wildorder/nightshift run "{program-id}"
+```
+
+Authoring a spec inside this session would write it in a context already
+carrying the whole planning conversation, compose its own instructions, and
+then grade its own output — which is what the command exists to prevent.
+
+## Rules
+
+- Describe only new behavior. Reference `docs/as-built.md` for unchanged
+  capabilities.
+- Keep each workstream completable in one agent session and independently
+  green; use causal boundaries instead of hard line-count or file-count
+  rules.
+- List every package or directory each workstream touches.
+- Use stable `SC-xx` success-criteria IDs for downstream traceability.
+- The manifest is the single source of truth for success criteria,
+  workstreams, dependencies, and scope. The program document references them
+  by id and never restates their text.
+- Give every workstream a `scope` with a specific `summary`, and state
+  `excludes` wherever a neighbor might reasonably assume coverage.
+- Record anticipated decisions in the program document — the decider reads
+  them, and a decision anticipated at planning time is handled better at run
+  time.