instar 0.28.95 → 0.28.97

package/upgrades/0.28.96.md

@@ -0,0 +1,347 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+### Project-scope Phase 1b connect-the-dots — wire the primitives
+
+Wires the four primitives shipped during the Phase 1b autonomous burst
+to their consumers, closing the deferrals named in side-effects reviews
+of PRs #164, #166, #167, and #168.
+
+- **Auto-advance poller now actually launches rounds.** On a successful
+  preflight + bookkeeping move, the poller fires-and-forgets a
+  `ProjectRoundExecution.runRound()` call. A per-project `inFlight`
+  guard prevents a slow run from being relaunched on the next 60s
+  tick. Errors are captured in `result.executorErrors[]` — they never
+  throw out of `tick()`.
+- **`GET /projects/:id/next` returns a structured action.** Replaces
+  the 501 placeholder with the spec § 1.5 line 268 contract:
+  `{ action, params, skillCommand }`. Verbs include
+  `'await-user-approval'`, `'ack-required'`, `'resolve-conflict'`,
+  `'accept-partial'`, `'run-spec-converge'`, `'run-drift-check'`,
+  `'start-round'`. Each maps to a `/project ...` invocation so the
+  dashboard + skill UI can act on a single GET. 204 when all rounds
+  complete, 404 on non-project initiative.
+- **`GET /projects/:id` lazy reconciler.** Per spec § 1.4 lines 256-258.
+  For 'building' children with `mergeCommitOid` set: 6h debounce via
+  `ciCheckedAt`, selection order oldest-`ciCheckedAt`-first
+  (ties → `roundIndex` ASC → `itemId` ASC, no starvation), cap of 3
+  per GET. Verified ancestor of `origin/main` → `'merged'`. NOT an
+  ancestor → `'regressed'` AND clear future `autoAdvanceAt` so the
+  chain doesn't auto-fire while a child is broken. `ciCheckedAt` is
+  written on every revalidation attempt (success or git failure) so
+  the debounce always backs off. Opt-out: `?reconcile=false`.
+- **`POST /projects/:id/drift-check` route.** New HTTP wrapper around
+  `ProjectDriftChecker.run()`. **Mutex-guarded per project (spec line
+  279)** — concurrent calls against the same project return 409,
+  protecting the drift-spend ledger from double-spend. Body:
+  `{ roundIndex, specPath, referencedFiles[], timeoutMs?, modelId? }`.
+  Returns 503 when no `IntelligenceProvider` is configured.
+
+Drift cache + spend-ledger wiring are intentionally deferred until the
+dashboard surfaces live verdicts and cost telemetry needs the cap. The
+mutex is in-process per-server; multi-process protection comes from
+the existing `proper-lockfile` on the drift-spend ledger itself.
+
+### Project-scope Phase 1b PR 7 — autonomous run loop
+
+Final PR of project-scope Phase 1b. Ships the autonomous run loop the
+spec § Phase 1.5 names (steps 1-11), wired against the lock, preflight,
+and runner primitives that landed in PRs 3-6:
+
+- **`ProjectRoundWorktrees`** — lazy worktree allocator under
+  `<targetRepoPath>/.worktrees/<projectId>/<roundIndex>/<itemId>`.
+  Appends `.worktrees/` to `.git/info/exclude` on first allocation so
+  the namespace doesn't pollute `git status`. Helpers for prune +
+  remove + ensure-exclude-entry.
+- **`runRound(input, deps)`** — the run loop itself. Acquires the
+  round-runner lock, lazily allocates the first worktree, spawns the
+  autonomous child in a detached process group, polls the project
+  record every 60 seconds. On mid-round mutation to `round.itemIds`,
+  SIGTERMs the child's process group (5s grace, then SIGKILL) and
+  relaunches with the new stop condition. On the child's natural
+  exit, verifies per-item artifacts via the caller-injected
+  `verifyMergedItems` and sets `round.status` to `complete` or
+  `partially-complete`. On `haltedAt` set mid-run, kills the child
+  and returns `halted`. Three-attempt resume cap on transient
+  non-zero exits before `failed`.
+- **`verifyMergedItemsViaGit`** — exported helper for production
+  callers; runs `git merge-base --is-ancestor <child.mergeCommitOid>
+  origin/main` per item.
+
+The run loop is a module function, not a method on `ProjectRoundRunner`,
+because it has different lifecycle semantics (long-running, subprocess
+manager) than the synchronous verbs in PR 3's runner. Both modules
+work in concert: callers call `runner.preflight(...)` first, then
+`runRound(...)` if preflight passes.
+
+Phase 1b is now fully decomposed: 7 PRs across drift + cache + ledger
++ runner + halt/advance/ack + auto-advance + claim-ownership +
+dashboard + filter + round-complete-message + run-loop. The remaining
+spec items (lazy merged-state reconciler on GET, `GET /next` real
+implementation) are wiring tasks rather than new infrastructure.
+
+### Project-scope Phase 1b PR 6 — tone-gated round-complete message + delivery
+
+Sixth PR of project-scope Phase 1b. Ships the two final primitives the
+autonomous run loop will need to emit round-complete digests safely:
+
+- **`formatRoundCompleteMessage(input)`** — pure template function.
+  Enforces required-field PRESENCE (not non-emptiness, per spec —
+  "the gate never silently rejects on a legitimate halt"). Returns
+  `{ok:true, message, idempotencyKey}` or `{ok:false, missingFields}`.
+  Halt-flavor events additionally require `whatHalted`.
+
+- **`RoundCompleteDeliveryHelper`** — retry + idempotency wrapper.
+  3-attempt exponential backoff (1s, 2s, 4s by default). Records
+  the `(projectId, roundIndex, eventKind, projectVersion)` key in
+  `.instar/local/round-complete-sent.json` after the first successful
+  send so tone-gate retries don't produce duplicates. On permanent
+  failure, fires the caller's `onPermanentFail` callback (the run
+  loop will wire it to attention-queue + audit-log + awaitingUser
+  population when it ships).
+
+Nothing wires these up yet — the autonomous run loop is the consumer.
+PR 6 ships the primitives so the run loop in a follow-up PR doesn't
+fork either of them.
+
+### Project-scope Phase 1b PR 5 — dashboard Projects tab + Initiatives filter
+
+Fifth PR of project-scope Phase 1b. Ships the dashboard view of the
+project surface and the small server-side filter the dashboard depends
+on:
+
+- **Projects tab** in the dashboard. Read-only card per active project
+  with title + id + version + drift status badge + per-round progress
+  bar + pipelineStage histogram. Halt + Ack buttons route through the
+  PR 3 endpoints; 409 responses silently re-render (no error toast).
+  15-second poll while the tab is active; cleared on deactivation.
+  XSS-safe — every rendered string goes through `textContent`, no
+  `innerHTML`.
+- **Initiatives tab filter** — by default the tab now hides
+  project-kind records (shown in their own Projects tab) and child
+  initiatives of any project (shown inside the parent's card). A
+  "Show projects + children" checkbox bypasses the filter for users
+  who want the full list. The filter is server-side: the records
+  never cross the wire when excluded.
+- **`GET /initiatives` filter params** — accepts `excludeKind=<kind>`
+  (drops records of that kind) and `excludeParented=true` (drops
+  records that are children of any project). Additive — existing
+  callers see no behavior change.
+
+The compaction-recovery hook's active-projects digest was already in
+the template (it shipped alongside session-start.sh in PR 1's Phase
+1.9 work), so no template change is needed here.
+
+### Project-scope Phase 1b PR 4 — auto-advance poller + multi-machine claim-ownership
+
+Fourth PR of project-scope Phase 1b. Ships three pieces:
+
+- **`MachineHeartbeat`** — per-machine liveness signal at
+  `.instar/machine-health/<machineId>.json` (git-synced). Written
+  every 30 minutes; consulted by the claim-ownership flow for the
+  48-hour staleness check. Machine ids with weird characters are
+  URL-encoded into the file name so a stray slash cannot escape
+  `.instar/machine-health/`.
+
+- **`ProjectAutoAdvancePoller`** — periodic scan (1-minute tick) for
+  project rounds whose `autoAdvanceAt` has elapsed. Server-side
+  filter: `kind:'project'`, `status:'active'`, owner machine matches
+  current, `unacknowledgedAdvanceCount < 2`. On fire, calls
+  `ProjectRoundRunner.preflight`; structural rejects (first-launch
+  ack missing, cap hit, project inactive, etc.) clear `autoAdvanceAt`
+  to prevent re-firing on every tick.
+
+- **`POST /projects/:id/claim-ownership`** — OCC-protected
+  multi-machine ownership transfer. Refuses with 409 when the current
+  owner has a fresh heartbeat unless `{force:true}` is passed.
+  Idempotent on already-owns. Response carries `previousOwner` for
+  audit.
+
+Plus a one-shot **post-restore reconciler** at server startup: any
+project round flagged `in-progress` is downgraded to `pending`. The
+previous owner may have crashed or migrated; no TaskFlow yet exists
+to verify whether a child is actually live.
+
+### Project-scope Phase 1b PR 3 — round runner + halt/advance/ack endpoints
+
+Third PR of project-scope Phase 1b. Ships the single-chokepoint
+runner that the spec names in § Phase 1.5, plus the four mutating
+HTTP routes that thread through it:
+
+- `POST /projects/:id/advance` — single-item stage transition driven
+  by the existing `StageTransitionValidator`. Requires `If-Match`
+  (OCC). Body: `{itemId, targetStage, artifact: {specPath?, prNumber?,
+  taskFlowRecordId?, skippedReason?, skippedBy?, unskippedAt?}}`.
+  Returns 409 with `{error, code, reason}` on validator reject.
+- `POST /projects/:id/halt` — emergency stop. Writes `haltedAt` +
+  `haltReason` to the active round, releases the round-runner lock
+  if the calling machine holds it. Idempotent.
+- `POST /projects/:id/ack` — records user acknowledgment for a round.
+  Populates `firstLaunchAckAt` if absent, advances
+  `lastAckedRoundIndex`, resets `unacknowledgedAdvanceCount`.
+  Idempotent on `forRoundIndex`.
+- `POST /projects/:id/accept-partial` — closes a partially-complete
+  round. Non-merged, non-skipped child items transition to
+  `skipped` (requires `reason` + `skippedBy` per the validator);
+  round status → `complete-with-skips`; counts as ack for the
+  current `roundIndex`.
+
+Behind the routes: `ProjectRoundRunner` runs the 9 deterministic
+preflight checks from § Phase 1.5 (lock free, round shape valid,
+items resolve, first-launch ack on round 0, unacked-advances cap,
+ack-gap cap, owner machine matches, target repo is a git repo, no
+pending reconciliation conflicts). Drift check (step 10) is
+intentionally deferred until the drift-check HTTP endpoint and its
+cache + ledger wiring ship in a follow-up PR — the drift verdict
+cache and cost ledger from v0.28.94 are on disk waiting for that
+consumer.
+
+The autonomous-delegating `run()` loop (lazy worktrees, dynamic
+stop-condition revalidation, SIGTERM/SIGKILL of process groups,
+partial-complete detection) is also deferred to the next PR; this
+PR ships the state-management verbs without the orchestration loop
+so the routes can be exercised end-to-end against real validators
+today.
+
+Lock primitive lives at `.instar/local/round-runner.lock` —
+machine-local (not git-synced) per spec. `O_CREAT|O_EXCL` rename +
+stale-PID sweep on every acquire, so a crashed runner doesn't
+permanently block subsequent acquires.
+
+## What to Tell Your User
+
+- **The autonomous round loop is wired up end-to-end**: when a round
+  starts, I now spawn the actual autonomous work in its own process
+  group, watch every minute for changes to which items the round is
+  working on, and clean up after myself (process group + worktrees)
+  when I am done or you halt me. If you manually skip an item or
+  re-order the round mid-run, I gracefully stop the work I am doing
+  and relaunch with the new plan — no orphaned compilers, no
+  orphaned worktrees.
+
+- **Round-complete digests are duplicate-safe**: when I finish a
+  round, the message I send you is built from a template that refuses
+  to send if any required field is missing, and the delivery layer
+  remembers what it already sent so a tone-gate retry can't spam you
+  with the same digest twice. If delivery fails permanently, I will
+  surface it through your attention queue rather than retry forever
+  in silence.
+
+- **Projects have a dashboard tab now**: open the dashboard and you'll
+  see every active project I'm tracking with its round-by-round
+  progress, which items have merged vs which are still in flight, and
+  any drift warnings I've recorded. Halt and ack buttons are right
+  there if you want to stop me or tell me you've seen the digest. The
+  Initiatives tab no longer mixes project plumbing in by default —
+  flip the "Show projects + children" toggle if you want to see
+  everything together.
+
+- **You can now drive a project round through the HTTP layer**: I can
+  advance a single item one stage with a real artifact check, halt the
+  active round on demand, record acknowledgment when I've shown you a
+  digest, or close out a round that landed only some of its items —
+  all from the dashboard or directly through the API. The actual
+  autonomous round loop that walks through items one by one is the
+  next piece I'm building.
+
+- **I can recover ownership when a peer machine goes offline**: if my
+  other machine has been silent for more than 48 hours, I can claim
+  back ownership of a project we'd been working on together. If my
+  peer is still online, I will refuse the claim unless you tell me to
+  force it.
+
+- **Time-based auto-advance is wired up**: when a round completes
+  cleanly, I will schedule the next round automatically. If you have
+  asked me to pause and have not acked, I will not auto-advance again
+  until you do — the two-rounds-ahead-without-ack brake stops me from
+  running off on my own.
+
+## Summary of New Capabilities
+
+- `ProjectRoundRunner` class — single chokepoint for round-start.
+  `preflight(projectId, roundIndex)` runs deterministic checks and
+  returns a structured `PreflightResult`. `halt`, `recordAck`,
+  `acceptPartial` are idempotent state-management verbs that mutate
+  through `InitiativeTracker.update()` with OCC. Static
+  `validateChildFrontmatter` for callers that need to assert
+  `review-convergence: true` AND `approved: true` outside the runner.
+- `ProjectRoundLock` class — machine-local mutex at
+  `.instar/local/round-runner.lock`. Atomic acquire via rename,
+  stale-PID sweep on every call. Exposes `acquire`, `release`, `read`.
+- New HTTP routes: `POST /projects/:id/advance`,
+  `POST /projects/:id/halt`, `POST /projects/:id/ack`,
+  `POST /projects/:id/accept-partial`. All require Bearer auth;
+  `/advance` requires `If-Match`.
+- `RouteContext.projectRoundRunner` — wired from
+  `AgentServer({ projectRoundRunner })` so other future routes (drift
+  check, run-round, claim-ownership) can route through the same
+  runner instance.
+- `MachineHeartbeat` class — `start()` / `stop()` / `writeOnce()` /
+  `read(machineId)` / `isStale(machineId)` / `listAll()`. File-backed,
+  git-syncable, defense-in-depth on malformed reads.
+- `ProjectAutoAdvancePoller` class — `tick()` returns a structured
+  `{scanned, fired, rejected, cleared}` report. Caller-driven cadence;
+  server wires a 60-second interval.
+- `POST /projects/:id/claim-ownership` — body `{force?: boolean}`;
+  header `If-Match` (OCC). Returns 200 with
+  `{ownerMachineId, previousOwner, version}` on success; 409 on fresh
+  peer heartbeat or version mismatch.
+- `RouteContext.machineHeartbeat` — bundled `{api, config}` so the
+  claim-ownership route can compare against the local machine id
+  without an extra top-level ctx field.
+- Server startup runs a one-shot reconciler that downgrades any
+  `in-progress` round to `pending`. Best-effort; OCC races are
+  silently retried on subsequent reconciler passes (or via the
+  auto-advance poller's filter).
+- Dashboard `Projects` tab — read-only project cards with progress
+  bar + drift badge + halt/ack buttons. 15-second poll while active.
+- Dashboard `Initiatives` tab now defaults to hiding project-kind +
+  child records. "Show projects + children" checkbox bypasses.
+- `GET /initiatives` accepts new optional query params: `excludeKind`
+  (drops records where `kind ?? 'task'` matches) and
+  `excludeParented=true` (drops records with a `parentProjectId`).
+  Additive; existing clients see no behavior change.
+- `formatRoundCompleteMessage(input)` — pure template function with
+  required-field PRESENCE gate (empty strings accepted, undefined
+  rejected). Halt-flavor events additionally require `whatHalted`.
+  Returns `{message, idempotencyKey}` on success.
+- `ProjectRoundWorktrees` class — lazy worktree allocator under
+  `<targetRepoPath>/.worktrees/<projectId>/<roundIndex>/<itemId>`.
+  Static `pathFor`/`allocate`/`prune`/`remove`/`ensureExcludeEntry`.
+- `runRound(input, deps)` function — the run loop. Acquires lock,
+  spawns autonomous child detached, polls every 60s, SIGTERMs on
+  dynamic-stop changes or halt, verifies per-item artifacts on
+  natural exit, sets `round.status`. Returns
+  `{outcome, mergedItemIds, unmergedItemIds, relaunchCount,
+  resumeAttempts, reason}`.
+- `verifyMergedItemsViaGit(targetRepoPath, childIds, tracker)` —
+  exported production verifier; checks `git merge-base --is-ancestor
+  <child.mergeCommitOid> origin/main` per item.
+- `RoundCompleteDeliveryHelper` class — retry + idempotency wrapper.
+  3-attempt exponential backoff (configurable); records the
+  idempotency key in `.instar/local/round-complete-sent.json` so
+  duplicate sends are suppressed. `onPermanentFail` callback fires
+  once when all retries are exhausted.
+
+## Evidence
+
+Not reproducible in dev — this release is a feature addition, not a regression fix.
+The words "crashed", "broken", and "resolve" in What Changed describe design properties
+of new primitives, not prior bugs that were observed and repaired:
+
+- "crashed runner" (lock primitive): stale-PID sweep so an interrupted runner doesn't
+  permanently hold the lock — a designed invariant of the new `ProjectRoundLock`, not
+  a fix for an observed crash.
+- "broken" (reconciler): `ciCheckedAt`-debounced ancestor check transitions a child to
+  'regressed' when its commit is not reachable from origin/main — a designed state
+  machine transition, not a regression repair.
+- "resolve-conflict" (GET /next action verbs): one of seven structured action strings
+  the endpoint returns; the word "resolve" is part of the verb name, not a claim that
+  a conflict was resolved as a bug fix.

package/upgrades/0.28.97.md

@@ -0,0 +1,146 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+### Project-scope Phase 1.7 — `/project` skill surface (full command set)
+
+Final code piece of project-scope Phase 1: the user-invocable
+`/project` skill, the conversational interface spec § Phase 1.7
+specifies as twelve canonical commands. Phase 1a shipped read-only
+commands (`create`, `status`, plus a placeholder `next`); this PR
+fleshes out the full mutating surface and adds the three small HTTP
+routes the spec named but hadn't materialized yet.
+
+- **`.claude/skills/instar-project/SKILL.md` rewritten end-to-end.**
+  Documents every spec § 1.7 command with its backing endpoint, body
+  schema, expected response codes, and a one-line conversational
+  rendering rule. The Phase 1a "next is a 501 placeholder" language
+  is gone — the structured `{action, params, skillCommand}` payload
+  shipped in the connect-the-dots PR is now the documented contract.
+- **`POST /projects/:id/run-round`** — manual round-start trigger.
+  Calls `ProjectRoundRunner.preflight()` for the deterministic gate
+  checks and, on accept, sets `autoAdvanceAt = now` so the existing
+  auto-advance poller fires the executor on its next tick (≤60s).
+  Does NOT spawn the autonomous child directly — keeps one fire path
+  through one lock. Body: `{roundIndex}`. Returns 200 with
+  `{id, roundIndex, scheduledAt, version}` on accept, 409 with the
+  preflight verdict's `code` + `reason` on reject (surface those
+  verbatim — they're written for users).
+- **`POST /projects/:id/resume`** — resume a halted or failed round.
+  Clears `haltedAt`/`haltReason`, schedules the round for the poller,
+  re-actives `project.status` from `'halted'`/`'abandoned'` back to
+  `'active'`. For rounds at `status: 'failed'` with
+  `resumeAttempts >= 3` (the spec's three-attempt cap), `{force: true}`
+  is required and the counter resets to zero on accept. Returns 409
+  when the round is neither halted nor failed.
+- **`POST /projects/:id/abandon`** — archive a halted project.
+  Sets `project.status = 'abandoned'` and clears any future
+  `autoAdvanceAt` on remaining rounds so the poller stops considering
+  them. Children's `pipelineStage` is left untouched (per spec).
+  Idempotent. Refuses (409) if a round is currently `in-progress` —
+  halt first.
+- **`skillCommandForAction()` realigned to canonical command names.**
+  The connect-the-dots PR added a mapping that returned
+  `/project approve` and `/project drift-check` for the
+  `await-user-approval` and `run-drift-check` actions. Spec § 1.7
+  uses `/project ack` and `/project drift` as the canonical command
+  names; the mapping now matches the spec so dashboard hints and
+  skill invocations stay in sync.
+
+Tests added:
+
+- `tests/unit/instar-project-skill.test.ts` — structural coverage of
+  SKILL.md (28 assertions). Pins the frontmatter contract, asserts
+  every spec § 1.7 command has a section header, and asserts each
+  documented endpoint actually exists in `src/server/routes.ts`.
+  Catches skill drift — if a route is renamed or removed without
+  updating the skill, the test fails on the next push.
+- `tests/integration/projects-api.test.ts` — 10 new cases (44 total)
+  for the three new endpoints: preflight reject (409), happy path
+  (200 + autoAdvanceAt landed), out-of-range round (404),
+  haltedAt-clear on resume (200), neither-halted-nor-failed reject
+  (409), failed-at-cap-without-force reject (409),
+  failed-at-cap-with-force happy path (counter zeroed), abandon
+  happy path (autoAdvanceAt cleared + status='abandoned'),
+  abandon-while-in-progress reject (409), abandon idempotent
+  (`alreadyAbandoned: true`).
+
+## What to Tell Your User
+
+- **You can now drive any project end-to-end through /project.**
+  Twelve commands, one skill: register a project from a plan doc,
+  read its state, advance a child item to its next stage, run a
+  drift check, fire a round, halt the active round, record your
+  acknowledgment, resume from halted or failed, abandon a project
+  permanently, close out a partially-complete round, claim ownership
+  on another machine. The skill walks me through each one with the
+  right API call and the right error handling — I don't have to
+  improvise the curl invocations.
+
+- **The "what should I do next" answer is now actionable.**
+  Asking /project next returns a structured action — "approval
+  pending," "drift check needed," "round ready to start" — plus the
+  exact follow-up command. I'll surface the suggested next step to
+  you in plain English rather than dumping the JSON.
+
+- **Halted projects can come back.** If a round halted because of a
+  spec drift, a halted child, or a runtime failure, /project resume
+  re-schedules it for the poller and re-actives the project. Rounds
+  that hit the three-attempt failure cap need an explicit force flag
+  before resuming, and the counter resets so the runner gets a fresh
+  budget.
+
+- **Permanently shelving a project is a single command.**
+  /project abandon clears all pending auto-advance scheduling and
+  marks the project as abandoned. Children stay where they were —
+  you don't lose any pipeline progress; you just stop the auto-loop.
+
+## Summary of New Capabilities
+
+- `.claude/skills/instar-project/SKILL.md` — twelve-command skill body
+  with frontmatter `user_invocable: true`. Each command section
+  documents its backing endpoint, body schema, response shape, and
+  expected error codes. Final "Conversational rendering" section pins
+  the don't-paste-curl rule.
+- `POST /projects/:id/run-round` — body `{roundIndex: number}`.
+  Returns 200 `{id, roundIndex, scheduledAt, version}` on accept,
+  409 `{error, code, reason}` on preflight reject, 404 on out-of-range
+  round, 503 if `ProjectRoundRunner` is not wired. OCC-protected via
+  `tracker.update(... ifMatch: project.version)`.
+- `POST /projects/:id/resume` — body `{roundIndex?: number,
+  force?: boolean}`. Returns 200 `{id, roundIndex, scheduledAt,
+  forced, version}` on accept, 409 when the round is neither halted
+  nor failed, 409 when failed-at-cap without `force`. Restores
+  `project.status` from `'halted'`/`'abandoned'` to `'active'` and
+  zeroes `resumeAttempts` on forced accept.
+- `POST /projects/:id/abandon` — no body required. Returns 200
+  `{id, status: 'abandoned', version}` on accept, 200
+  `{... alreadyAbandoned: true}` on idempotent repeat, 409 with
+  `activeRound` set when a round is in-progress. Clears
+  `autoAdvanceAt` on every remaining round.
+- `skillCommandForAction()` now emits `/project ack` for both
+  `await-user-approval` and `ack-required` action verbs, and
+  `/project drift` for `run-drift-check`. Aligns the dashboard hint
+  strings with the spec § 1.7 canonical command set.
+
+## Evidence
+
+Not reproducible in dev — this release is a feature addition, not a
+regression fix. The words "halted", "failed", "regression repair",
+and "skill drift" in What Changed describe design properties of the
+state machine and the structural test the PR introduces:
+
+- "halted" / "failed" (resume route): these are valid round states
+  in the existing `RoundStatus` union; the new endpoint's job is to
+  transition out of them. Not a fix for an observed halt incident.
+- "skill drift" (structural test): the new
+  `instar-project-skill.test.ts` asserts every endpoint documented
+  in SKILL.md exists in `routes.ts`. The "drift" is the test's
+  failure mode if a future PR renames a route without updating the
+  skill — a preventive guard, not the patching of a prior incident.

package/upgrades/side-effects/project-scope-phase1-7-skill-surface.md

@@ -0,0 +1,175 @@
+# Side-Effects Review — project-scope Phase 1.7 skill surface
+
+**Scope.** Closes the spec § Phase 1.7 user-facing surface. Rewrites
+`.claude/skills/instar-project/SKILL.md` to cover all twelve canonical
+commands, adds the three small HTTP routes the spec named but hadn't
+materialized (`run-round`, `resume`, `abandon`), and realigns
+`skillCommandForAction()` to the canonical command names.
+
+## What's IN this PR
+
+1. **`.claude/skills/instar-project/SKILL.md`** — full rewrite. Phase 1a
+   placeholder language for `/project next` is removed (the connect-the-dots
+   PR shipped the structured payload; the skill now documents that contract).
+   Every command from spec § 1.7 has a section header with its backing
+   endpoint, body schema, response codes, and a one-line rendering rule.
+   Final section pins the conversational-tone rule ("never paste a curl
+   command in a user-facing reply") that Echo's CLAUDE.md enforces.
+2. **`POST /projects/:id/run-round`** — manual round trigger. On
+   `preflight.ok`, writes `autoAdvanceAt = now` to the named round and
+   returns 200 + `scheduledAt`. The auto-advance poller (wired in the
+   connect-the-dots PR) picks it up on its next tick (≤60s) and dispatches
+   `ProjectRoundExecution.runRound()`. No child-process spawn from the
+   request handler — keeps one fire path through one lock.
+3. **`POST /projects/:id/resume`** — clears `haltedAt`/`haltReason`,
+   schedules the round via `autoAdvanceAt = now`, transitions
+   `project.status` from `'halted'`/`'abandoned'` back to `'active'`.
+   For `status: 'failed'` rounds at the 3-attempt cap, `{force: true}`
+   is required AND the `resumeAttempts` counter resets to zero on
+   accept. Returns 409 when the round is neither halted nor failed.
+4. **`POST /projects/:id/abandon`** — sets `project.status = 'abandoned'`,
+   strips `autoAdvanceAt` from every remaining round so the poller
+   stops considering them, leaves each child's `pipelineStage`
+   untouched. Idempotent (`alreadyAbandoned: true` on repeat).
+   Refuses 409 when any round is `in-progress` — halt first.
+5. **`skillCommandForAction()` realignment.** The connect-the-dots PR
+   returned `/project approve` and `/project drift-check` for the
+   `await-user-approval` and `run-drift-check` action verbs. Spec § 1.7
+   uses `/project ack` and `/project drift`; the mapping is updated so
+   the dashboard hints + the `/projects/:id/next` payload + the skill
+   stay in sync.
+6. **Tests.** `tests/unit/instar-project-skill.test.ts` (28 assertions)
+   pins the SKILL.md contract — frontmatter, every spec § 1.7 command
+   has a header, every documented endpoint exists in `routes.ts`.
+   `tests/integration/projects-api.test.ts` adds 10 cases for the new
+   routes covering happy paths + every documented error case.
+
+## What's explicitly DEFERRED
+
+- **`ProjectRoundRunner.resume` / `.abandon` methods.** The new
+  endpoints mutate state via `tracker.update()` directly rather than
+  routing through a runner method. The runner's value-add is the
+  `preflight()` gate; resume/abandon don't have preflight semantics
+  (they're transitions OUT of stuck states, not transitions INTO an
+  autonomous run). If a future need surfaces — e.g., resume needs to
+  hold the round-runner lock briefly, or abandon needs to release a
+  worktree — those can land as runner methods then. Today, the
+  shorter path is cleaner.
+- **Resume worktree cleanup.** Spec § 1.5 step "Halt switch" says
+  "Worktrees retained for inspection (cleanup deferred to user
+  `/project resume` or `/project abandon`)." The new resume/abandon
+  routes do NOT prune worktrees — the autonomous child the poller
+  fires next will recreate them lazily. Worktree GC is a separate
+  follow-up (registered as a child of the spec's deferral list).
+- **No telemetry on action verbs.** The dashboard hint
+  (`skillCommandForAction()`) is read-only suggestion; we don't yet
+  count which verbs fire most frequently. A simple counter on the
+  `/projects/:id/next` handler would surface "what's the most common
+  unblocking step?" — interesting telemetry, but not Phase 1 scope.
+- **Skill body translation hooks.** The SKILL.md is a single file; we
+  don't (yet) split per-command bodies into separate files the agent
+  can lazy-load. At ~10KB the file is well within the context budget
+  for a `/project` invocation. If the surface keeps growing past
+  Phase 1, splitting per-command is the natural next move.
+
+## Side-effects review
+
+**Over-block.** All three new routes are pure tracker.update() calls
+with OCC. No child-process spawn, no git shell-out, no LLM call.
+P99 latency in test runs ~20ms (single tracker write + JSON encode).
+The skill body grew from ~3.5KB to ~10KB — adds one file read per
+`/project` invocation; well below the context-window pressure
+threshold.
+
+**Under-block.** `resume` does not re-run drift before scheduling.
+The poller's preflight (which fires after the route writes
+`autoAdvanceAt`) re-runs drift if the cached verdict is stale (>24h)
+per spec § Phase 1.4. So drift is enforced at fire time, not at
+resume time — same level as the original `/project run-round`. This
+is intentional: resume is a state mutation, not a fire trigger.
+
+**Level-of-abstraction fit.** Each new route sits at the same layer
+as the surrounding routes:
+- `run-round` belongs alongside `halt` and `ack` (all three are
+  user-initiated state changes that thread through the runner).
+- `resume` and `abandon` belong alongside `accept-partial` (all
+  three close out a specific round-end condition).
+
+The skill is the highest layer — it's the conversational shell over
+the HTTP API. SKILL.md is markdown the agent reads on `/project`
+invocation, not executable code; the body's instructions ARE the
+implementation.
+
+**Signal vs authority.** The new routes are authority paths — they
+mutate state. None of them consult an LLM signal. `run-round` does
+delegate to `ProjectRoundRunner.preflight()` for the deterministic
+gate checks; that's the spec's single-chokepoint pattern, not a
+signal/authority mix.
+
+**Interactions.**
+- `run-round` + `auto-advance poller`: the route writes `autoAdvanceAt`,
+  the poller reads it. The poller's `inFlight: Set<projectId>` guard
+  (shipped in connect-the-dots) ensures a manual run-round followed
+  by a poller tick doesn't double-fire.
+- `resume` + `halt`: idempotent in either direction. `halt` writes
+  `haltedAt`; `resume` strips it. Repeat halts on an already-halted
+  round are no-ops; repeat resumes on an already-resumed round
+  return 409 ("round is not halted or failed").
+- `abandon` + `claim-ownership`: abandon sets `project.status =
+  'abandoned'`; the auto-advance poller's owner filter already
+  excludes abandoned projects. A peer claiming ownership of an
+  abandoned project would just re-claim — the poller still skips
+  abandoned-status projects regardless of owner.
+- `skillCommandForAction()` realignment: existing test
+  `expect(typeof res.body.skillCommand).toBe('string')` doesn't
+  assert exact strings, so the rename is backwards-compatible at
+  the test level. Dashboard consumers render the string verbatim —
+  they get `/project ack` instead of `/project approve`, which is
+  what spec § 1.7 documented.
+
+**Rollback cost.** Three options:
+1. **Skill-only rollback** — restore the prior SKILL.md from
+   `git show HEAD~1:.claude/skills/instar-project/SKILL.md`. Agent
+   reverts to Phase 1a read-only behavior; new HTTP routes still
+   exist but are not surfaced. Zero state risk.
+2. **Routes-only rollback** — `git revert` the three new route
+   handlers. Skill still references them; agent surfaces 404 from
+   `/project run-round`, `/project resume`, `/project abandon`.
+   Surface-but-not-functional, but no data corruption — state
+   mutations all go through `tracker.update()` with OCC, which is
+   already proven safe.
+3. **Full revert** — drop the whole commit. No on-disk state from
+   this PR persists (the abandon/halt/resume state fields all
+   pre-exist in the `Initiative` schema from Phase 1a).
+
+All three are clean. The PR introduces no new persisted state, no
+new file paths, no new background work — it adds surface area over
+the existing state machine.
+
+## Files touched
+
+- `.claude/skills/instar-project/SKILL.md` (rewritten)
+- `src/server/routes.ts` (three new route handlers + one mapping fix)
+- `tests/integration/projects-api.test.ts` (10 new cases)
+- `tests/unit/instar-project-skill.test.ts` (new file, 28 assertions)
+- `upgrades/NEXT.md` (new release notes)
+
+## Spec references
+
+- `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.7 — canonical
+  command list.
+- `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.5 — runner preflight
+  contract; halt/resume worktree-retention rule.
+- `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.3 — HTTP layer
+  doesn't enforce gates the runner already enforces. `run-round`
+  delegates to `preflight()` cleanly.
+
+## Coverage
+
+- Unit: structural coverage of SKILL.md + endpoint existence —
+  `tests/unit/instar-project-skill.test.ts`.
+- Integration: happy + error paths for all three new routes against
+  the real `AgentServer` + `InitiativeTracker` + `ProjectRoundRunner`
+  — `tests/integration/projects-api.test.ts`.
+- Lint: clean.
+- Type-check: clean (new `RoundStatus` import).