@wildorder/nightshift 0.11.1 → 0.13.0

package/skills/backlog-capture/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: backlog-capture
+description: Capture a discovered-but-deferred feature or larger piece of work as a durable backlog item, written now from the current session's context, so a future planning session starts warm. Use the moment you hit something bigger than the task at hand and want to remember why — in an interactive session with a human present. Do not use during an unattended or automated agent run.
+argument-hint: "[what you discovered]"
+---
+
+# Capture a backlog item
+
+A coding session routinely stumbles on something that is really a larger
+feature: too big to absorb into the task at hand, valuable enough to become
+future work. The expensive part of that moment is the context — which files
+constrain the design, which approach was already tried and rejected and why,
+what the naive version breaks. That context is gone by tomorrow. This skill
+gives it a durable, repo-tracked home, written while you still hold it.
+
+## When this fires
+
+Fire this yourself, the moment you recognize the discovery, without waiting
+for a human to ask for it. If capture waits until someone notices and
+requests it, the context has already started to fade — the entire point is
+to record it while it is still live.
+
+Use this only in an interactive session with a human present to see what
+gets written. Decline to use it during an unattended or automated agent
+run — there is nobody there to review the capture, and this skill is not a
+substitute for whatever that run already does with its own findings. If you
+cannot tell whether a human is present for this session, do not use this
+skill.
+
+## The item format
+
+This is the one canonical definition of a backlog item. Nowhere else in this
+project restates it — if you find another description of the item format
+elsewhere, this one wins.
+
+An item is one file at `docs/backlog/{slug}.md`. One item per file, never
+several discoveries folded into one file. The slug is the item's title,
+lowercased and converted to kebab-case; do not invent a separate slug that
+diverges from the title.
+
+### Frontmatter
+
+Frontmatter carries only the facts a later reader needs to act on
+mechanically. Everything else belongs in the body as prose.
+
+```yaml
+---
+status: captured
+captured: 2026-09-03
+---
+```
+
+- `status` — one of `captured | planned | done | declined`. A fresh capture
+  is always `captured`.
+- `captured` — the date of capture, as `YYYY-MM-DD`.
+- `planned-into` — the id of the program (the future piece of work) that
+  absorbed this item. **Absent until planned.** Do not write this field when
+  you capture an item; it is added later, by whatever later reads this
+  backlog as planning input, only at the moment this item's status becomes
+  `planned`.
+
+Do not add a `title` or `slug` field. The title lives in the H1 heading and
+the slug in the filename; duplicating either into frontmatter would give the
+same fact two homes that can drift apart.
+
+### Body — narrative sections
+
+Write the body as prose, for a human reading it cold, months from now, with
+none of this session's context. Use these named sections. Each one earns its
+keep for a specific reason — fill it from what you actually know right now,
+not from what you imagine you might discover later:
+
+- **What the session hit and where** — the concrete trigger: file paths, the
+  task the session was actually doing, the symptom or realization that
+  surfaced this.
+- **Why it is bigger than this session** — what makes this a future piece of
+  work rather than something to fold into the current task.
+- **Constraints discovered** — the expensive knowledge: what a design here
+  must respect, what the existing code already forces, anything that would
+  otherwise have to be rediscovered the hard way.
+- **Approaches considered or rejected, and why** — so whoever picks this up
+  does not re-walk a dead end you already ruled out.
+- **Pointers** — branches, commits, related items (link them by slug or
+  path), anything else that helps someone orient.
+
+This is prose in, prose out. Nothing grades or validates what you write here
+— a thin capture with only one or two sections filled in is still worth far
+more than no capture at all. Write what you actually know; do not pad
+sections with speculation to look complete.
+
+## Capture behavior
+
+- **Write it now, in full, from this session's live context.** Do not leave
+  a one-line stub or a TODO to flesh out later — by the time anyone returns
+  to flesh it out, the context this skill exists to preserve is already
+  gone. This is the central instruction; everything else here supports it.
+- **Check `docs/backlog/` first for an item that already covers this
+  ground.** If one exists, enrich it with what this session adds instead of
+  creating a near-duplicate file.
+- **Create `docs/backlog/` if it does not exist yet.** Nothing scaffolds
+  this directory in advance; the first real capture creates it.
+- **Never modify anything outside `docs/backlog/`.** This skill is strictly
+  additive and scoped to that one directory.
+- **Never overwrite an unrelated file already in `docs/backlog/`.** If a
+  file there was not written by this skill and does not cover the same
+  discovery, leave it alone and create a new item instead.
+- **Say nothing about how any particular tool or program consumes this
+  backlog later.** This skill only describes the item and how to write it;
+  it does not depend on, and must not reference, any specific downstream
+  tooling or process. It works the same way in any repository that has it
+  installed.
+- **Capture `HEAD` before committing.** Before staging anything, record the
+  pre-commit baseline with `git rev-parse HEAD`. In a brand-new repository
+  with no commits yet, `HEAD` is unborn and this fails — that failure is
+  itself the baseline (it means "no commit exists yet"); treat it as a
+  sentinel rather than an error, and do not let it block the commit attempt
+  below. This captured value (or the unborn sentinel) is what the
+  post-commit confirmation below compares against — without it, "confirm
+  `HEAD` moved" has nothing to move *from*.
+- **Commit the item the moment it is written, in a repository that uses
+  git.** Immediately after writing `docs/backlog/{slug}.md`, make one commit
+  that contains only that file — stage exactly it and commit only it, so
+  nothing else already sitting in the tree rides along. Use the kebab-case
+  `{slug}` in the commit message, not the human title: the slug is
+  constrained to `[a-z0-9-]`, so it is safe to interpolate into the command,
+  while a title can carry a quote, backtick, `$(...)`, or other shell
+  metacharacter that could truncate, alter, or execute the command on common
+  shells.
+
+  ```sh
+  git add -- docs/backlog/{slug}.md
+  git commit -m "backlog: capture {slug}" -- docs/backlog/{slug}.md
+  ```
+
+- **Confirm the commit actually landed before reporting anything about
+  it, by comparing against the `HEAD` you captured before committing.** A
+  commit can fail for reasons beyond "no git repository" — unset git
+  identity, a failing pre-commit hook, a signing failure, no write
+  permission, or nothing new to commit. After committing, run
+  `git rev-parse HEAD` again and confirm it differs from the pre-commit
+  value you captured above (or, if the pre-commit capture was the unborn
+  sentinel, confirm `HEAD` now resolves at all — either case is "a new
+  commit now exists that did not before"), and that this new commit's one
+  changed file is `docs/backlog/{slug}.md`, before reading any branch or SHA
+  from it. Checking only "the current commit's diff is exactly this file"
+  without that prior-`HEAD` comparison is not sufficient: a bare
+  `git rev-parse HEAD` run after a *failed* commit still resolves and names
+  an older, unrelated commit, and reporting that as the landing SHA hands
+  the human a false rescue command; the captured pre-commit value is what
+  lets you tell that older commit apart from a genuinely new one. If the
+  commit did not land, do the opposite of reporting: say plainly that the
+  item could not be committed and why (surface git's message), note that
+  the item file is written to disk regardless — the durable capture is the
+  point and stands whether or not the commit succeeded — and leave
+  committing to the human. **Do not name a branch, a SHA, or a
+  cherry-pick/rescue command on this path** — there is no confirmed commit
+  for any of those to describe, and offering one anyway (even one built
+  from the pre-commit `HEAD`) hands the human a rescue command for a commit
+  that does not exist.
+- **Report which branch the confirmed commit landed on.** Read the current
+  branch with plain git (for example `git branch --show-current`) and tell
+  the human; do not switch branches to check.
+- **Flag a branch unlikely to reach the trunk, and hand over the exact
+  rescue command.** If the confirmed landing branch looks like a scratch or
+  experiment branch — a throwaway unlikely ever to be merged into the
+  repository's default branch — say so plainly, so the human can decide
+  whether to re-home the item. When you raise that flag, include the exact
+  rescue command with the real, confirmed commit SHA — `git cherry-pick
+  <sha>` (read via `git rev-parse HEAD` only after confirming the commit
+  landed above), run from the default branch — so re-homing is one paste,
+  not a later investigation. The only-the-item-file staging boundary above
+  **isolates** that cherry-pick from unrelated files, because the commit
+  touches only the one new item file — it does **not** guarantee a clean
+  apply in every case (the default branch may already carry the same path
+  or a divergent version of it), so present cherry-pick as the convenience
+  and tell the human to fall back to merging the branch if it conflicts.
+  Never switch branches, cherry-pick, or move the item yourself; commit
+  where the session already stands, name the branch, flag the risk, hand
+  over the command, and leave relocation to the human.
+- **When there is no git repository, the commit simply cannot happen.**
+  Write the item and say so; the durable file on disk is still the point,
+  whether or not this repository uses git.

package/skills/plan-program/SKILL.md

@@ -26,12 +26,80 @@ Read:
   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
+  findings, recorded decisions, and **unmet human prerequisites** are
+  planning input, not noise. A prior run's workstreams left `awaiting_human`,
+  and the `prerequisites` entries still `pending` that they reference, name
+  work a human has not yet done. Preserve every prerequisite record that any
+  incomplete workstream still references — verbatim, with its stored
+  `status` unchanged, including a `satisfied` record a live workstream still
+  points at; do not drop it merely because it is satisfied, or the workstream
+  would reference an id the manifest no longer defines. Only a record whose
+  stored status is already `satisfied` may be treated as settled
+  infrastructure, and only because a prior run's preflight flipped it — never
+  because the planner judged the human's work done. A record still marked
+  `pending` stays `pending` even when the human reports having done the
+  action: the planner never flips a prerequisite's status; only the
+  deterministic preflight satisfies one, on the next run. 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.
+- `docs/backlog/`, when it exists. Treat its `captured` items as planning
+  input on equal footing with the vision and as-built, and surface the ones
+  relevant to the phase being planned before decomposing work in the next
+  step — a backlog item is prior context someone already paid for, not a
+  file to skim past. If `docs/backlog/` does not exist, proceed without
+  comment; an absent or empty backlog changes nothing about how this skill
+  runs.
+
+  Also look past the working tree: because captures commit where the
+  session stands, an item can sit on an unmerged branch and be entirely
+  invisible to this listing. In a git repository, enumerate ref tips,
+  read-only: list the candidate refs (`git for-each-ref --format='%(refname)'
+  refs/heads refs/remotes`), and for each one list the `docs/backlog/*.md`
+  paths present **at that ref's tip tree**
+  (`git ls-tree -r --name-only <ref> -- docs/backlog/`) — not a history
+  scan; a bare `git log --diff-filter=A -- docs/backlog/` or
+  `git branch --contains` proves only that a commit was once added or is an
+  ancestor somewhere, not that the file still exists at any ref's tip today,
+  and would misreport an item deleted from every branch as awaiting-merge.
+  Union the tip-tree paths across refs and subtract this working tree's own
+  `docs/backlog/` listing; what remains are candidates.
+
+  A candidate is not automatically "not yet merged": a branch can have been
+  fully merged and kept around while the item was later deleted here on
+  purpose, and tip-tree subtraction alone cannot tell the two apart. So for
+  each candidate, resolve the commit that most recently added it on its ref
+  (`git log -1 --diff-filter=A --format=%H <ref> -- <path>`) and check
+  whether that commit is already reachable from `HEAD`
+  (`git merge-base --is-ancestor <commit> HEAD`). A reachable add-commit
+  means this content already made it into the current branch's history at
+  some point and its absence now is a deliberate removal, not unmerged
+  work — drop that candidate rather than resurrecting it as planning input.
+  Only an unreachable add-commit is genuinely **awaiting-merge** input; name
+  it to the human as living on that branch, not yet merged. When no single
+  add-commit can be resolved at all (for example, the path arrived on that
+  ref by a rename), do not assert unmerged with confidence — still name the
+  item, but say its provenance could not be confirmed and ask the human to
+  check it is not already-handled content before treating it as new work.
+
+  Before naming the cherry-pick option, inspect the resolved add-commit's
+  complete changed-path set. Offer `git cherry-pick` of that commit only
+  when the set is exactly the one backlog item path — that is what makes
+  the only-the-item-file boundary actually isolate the cherry-pick from
+  unrelated files; a multi-file add-commit (a legacy, manually captured, or
+  renamed item) breaks that isolation despite looking like a single-item
+  capture. In every other case — a multi-file add-commit, an unresolved
+  add-commit, or an item later modified on its ref (which makes the
+  add-commit alone stale) — recommend merging the branch instead, the safer
+  default regardless. Either way, the item can only be **absorbed** — its
+  frontmatter flipped in §4.5 — once its file is actually present on the
+  planning branch, so this step only surfaces the candidate and explains how
+  to bring it over; it never merges, cherry-picks, or edits an off-tree item
+  itself. Outside a git repository, or when no other ref carries an item
+  this working tree lacks, say nothing — the same proceed-without-comment
+  tolerance as an absent backlog.
 
 If no vision document exists at the resolved path, stop. Explain that it
 should contain the product description, architecture, target users, API
@@ -88,6 +156,88 @@ npx --yes @wildorder/nightshift branch "{program-id}"
 This skill composes no git of its own — the command above owns branch
 selection, and the packaged runner owns every commit that follows.
 
+## 2.7. Run the actor audit
+
+Before drafting either artifact, walk the phase's work and ask one question of
+each unit: *what credential or access does this step consume, and does the
+crew hold it?* This audit **discovers** human-only steps; it never blocks the
+plan. A phase with no human-only actions produces an empty audit, and the
+skill proceeds exactly as it does today — no `prerequisites` entries, no Human
+Prerequisites section, no friction. There is no rule that a plan must declare
+a prerequisite; there is only a question worth asking before the work is
+scheduled.
+
+The roster does not exist yet at this point — §3 and §4 haven't drafted it —
+so audit a **provisional decomposition**: the candidate units of work the
+phase breaks into, the same decomposition §3 and §4 will formalize into
+workstreams. If drafting the final roster later **adds, removes, splits, or
+moves a workstream**, re-check the hoist-and-batch assignment below against
+the new roster, so every eventual unit of work has been audited and every
+prerequisite lands on the workstream that actually consumes it.
+
+**The enumerable tells** — the concrete signals a unit of work needs a human:
+
+- cloud or organisation **admin credentials** the crew is not given;
+- **console-only actions** with no API the agent can call;
+- **trust anchors** — OIDC providers, state backends, signing keys — that a
+  human must establish before anything can authenticate against them;
+- **secrets the agent may not set** (a repository or environment secret the
+  crew must never hold);
+- **third-party account creation**;
+- **DNS** records and delegations.
+
+**A prerequisite is an action the crew *cannot* perform — never one that is
+merely hard, slow, or annoying.** The audit's test is "does the crew hold
+this?", never "is this unpleasant?" Work an agent can do, even tediously, is
+not a prerequisite; declaring it as one manufactures an intermission and hands
+the human work the run could have done itself.
+
+**Convert each hit into a prerequisite** with:
+
+- a stable **id**, conventionally `HP-01`, `HP-02`, …;
+- a human-facing **description** of the action only a human can perform;
+- a **remediation** written as the exact commands or console steps the human
+  runs — a runbook, not a hint (for example, a repository-settings change like
+  configuring branch protection in the hosting provider's settings, described
+  as console steps, not as a version-control command);
+- a **verifyCommand**: a shell command that exits zero iff the action is done,
+  which the runner executes itself as a deterministic subprocess — never a
+  model's judgment. The observable must be one the headless runner can
+  actually query: non-interactive, reading no stdin, emitting no prompt, and
+  using only credentials the *runner* holds. This is the trap turned back on
+  itself — the prerequisite exists because the crew lacks a credential, and
+  the obvious way to verify the action often needs that same missing
+  privilege. Distinguish permission to **perform** the action (which the crew
+  lacks — that is why it is a prerequisite) from permission to **observe**
+  its completion (which the runner must have). If the only observable needs
+  the human-only privilege, pick a different observable the runner can reach
+  — a downstream effect, a read-only or verification-scoped credential
+  provisioned for the purpose — rather than shipping a command the runner
+  cannot execute. The `verifyCommand` is executed verbatim by the runner, the
+  same trust class as the verify commands in `nightshift.config.json` — it is
+  reviewed at planning time precisely because it will be run.
+
+**Hoist and batch.** Human actions are expensive handoffs. Hoist each human
+action to a workstream boundary rather than burying it mid-workstream, batch
+independent human actions into the fewest handoffs (ideally one), and
+sequence agent-doable work ahead of the first unmet prerequisite so a run
+gets as far as it can before it must wait. A workstream that consumes a
+prerequisite lists it in that workstream's `prerequisites`.
+
+An empty audit is the normal outcome for a program that touches no
+infrastructure — write no `prerequisites`, add no Human Prerequisites
+section, and move on. But an infrastructure-touching program that emerges
+from the audit with an empty prerequisites list is worth re-checking during
+review: it usually means a human seam was missed, not that none exists. This
+is guidance for a second look, not a rule the plan must pass.
+
+**What this step does not do.** The audit produces manifest entries and
+program-document prose. It never runs a `verifyCommand`, never verifies
+whether a human has acted, and never changes a workstream's or a
+prerequisite's `status` — that is the runner's job, at run time. It never
+makes prerequisite declaration mandatory, never blocks a plan, and never adds
+a step the plan must pass. An empty result is a complete, valid plan.
+
 ## 3. Draft the program document
 
 Inspect `docs/programs/` for an existing `*-program.md`. Match its structure
@@ -110,6 +260,13 @@ when one exists. Otherwise use:
 ## Architecture Changes
 [Changes from the system in as-built.md. For the first program, describe the full architecture.]
 
+## Human Prerequisites
+[Only when the actor audit found human-only actions. One short paragraph or a
+few bullets naming each prerequisite by id (HP-xx) and what it unblocks — which
+workstreams wait on it and why the crew cannot perform it. Reference ids only;
+the remediation, verifyCommand, and status live in the manifest, never here.
+Omit this section entirely when the audit found no prerequisites.]
+
 ## Technology Choices
 [Only new choices. If none: "No new technology — uses existing stack."]
 
@@ -133,10 +290,13 @@ 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.
+are manifest data — do not reproduce them here. Human Prerequisites follows
+the same rule: reference HP ids only, never their description, remediation,
+verifyCommand, or status, all of which are manifest data. 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 —
@@ -162,6 +322,15 @@ exactly. Otherwise use:
   "successCriteria": [
     { "id": "SC-01", "description": "{verifiable outcome}" }
   ],
+  "prerequisites": [
+    {
+      "id": "HP-01",
+      "description": "{the action only a human can perform}",
+      "remediation": "{the exact commands or console steps the human runs}",
+      "verifyCommand": "{a shell command that exits zero iff the action is done}",
+      "status": "pending"
+    }
+  ],
   "packages": [
     {
       "name": "{package-name}",
@@ -182,6 +351,7 @@ exactly. Otherwise use:
         "excludes": ["{specific thing it deliberately does not cover}"]
       },
       "dependencies": [],
+      "prerequisites": [],
       "packages": []
     }
   ],
@@ -189,6 +359,11 @@ exactly. Otherwise use:
 }
 ```
 
+The root `prerequisites` array and each workstream's `prerequisites` id list
+come from the actor audit (§2.7). Omit the root array, or leave it empty, when
+the audit found nothing — the schema defaults it to `[]`, so a
+prerequisite-free manifest is byte-for-byte what the skill emits today.
+
 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
@@ -248,6 +423,47 @@ For a shared contract migration, prefer an explicit sequence:
 The destructive cleanup depends on every migration workstream. Do not place
 foundational deletion first merely because it is conceptually central.
 
+## 4.5. Absorb backlog items
+
+When any part of this program's scope came from an item captured under
+`docs/backlog/`, close the loop before handing off:
+
+- Flip that item's `status` to `planned` and write this program's id into
+  its `planned-into` field. Edit only those two fields — do not restate or
+  reshape the rest of the item.
+- Carry that item's captured constraints into both the program document
+  narrative and the manifest's `planningInput`, instead of re-deriving
+  them — the reason to read the backlog in step 1 is so this plan starts
+  from knowledge a prior session already paid for, not to re-research it.
+- Leave every item this program does not draw on untouched at `captured`.
+
+This is the planner exercising judgment interactively, in the moment a
+program is being shaped — not an automated transition. Statuses beyond
+`planned` (`done`, `declined`) are closed out separately, by a human editing
+the item file directly; no skill advances them.
+
+## 4.6. Commit the plan
+
+The plan is committed now, on this program's branch, so it never sits
+untracked where a different program's run could sweep it up. Run exactly
+this command and nothing else:
+
+```sh
+npx --yes @wildorder/nightshift commit-plan "{program-id}"
+```
+
+This skill composes no git of its own — the command above owns staging and
+committing the plan (the program document, the manifest, and any backlog
+items absorbed in the previous step), and the packaged runner owns every
+commit that follows. If the command exits nonzero — no git repository, or
+HEAD is not this program's branch — surface its message to the human as a
+warning and proceed to the handoff below anyway; do not treat it as a hard
+stop. The artifacts already exist on disk regardless, and every refusal the
+command can raise is a "could not commit here" a human can resolve (init a
+repository, or run the branch step). A clean no-op — the plan is already
+committed and unchanged — ends this step the same way a fresh commit does:
+move on.
+
 ## 5. Hand off for review
 
 Both files now exist on disk. Reply with a short summary only — program