instar 0.28.95 → 0.28.96

package/upgrades/side-effects/project-scope-phase1b-pr3.md

@@ -0,0 +1,228 @@
+# Side-Effects Review — project-scope Phase 1b PR 3 (Round runner + halt/advance/ack endpoints)
+
+**Version / slug:** `project-scope-phase1b-pr3`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `required (new HTTP mutating surface + lock primitive + cross-record mutation orchestration)`
+
+## Summary of the change
+
+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 endpoints
+that route through it (`/advance`, `/halt`, `/ack`, `/accept-partial`).
+The actual autonomous-delegating run loop and dynamic stop-condition
+revalidation are intentionally deferred to a follow-up PR — this PR
+ships the **preflight gate** + **lock primitive** + **state-management
+verbs** without the orchestration loop, so the routes can be exercised
+end-to-end with real validators today.
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.5 (preflight,
+lock, halt switch, runner authority model), § Phase 1.3 (HTTP endpoints).
+
+New files:
+- `src/core/ProjectRoundLock.ts` (~150 lines) — machine-local lock
+  primitive at `.instar/local/round-runner.lock`. Acquire encodes
+  `{pid, projectId, roundIndex, acquiredAt}` as JSON, atomic via
+  `O_CREAT|O_EXCL` write + rename. Stale-PID sweep on every acquire
+  uses `process.kill(pid, 0)`. Release / read / isAlive helpers.
+- `src/core/ProjectRoundRunner.ts` (~470 lines) — the single
+  chokepoint. `preflight(projectId, roundIndex)` runs the 9 deterministic
+  checks from § Phase 1.5 (drift check, step 10, deferred to a follow-up
+  PR alongside the cache+ledger HTTP wiring). `halt`, `recordAck`, and
+  `acceptPartial` are idempotent state-management verbs that mutate
+  through `InitiativeTracker.update()` with OCC. Static
+  `validateChildFrontmatter` exported for future `run()` and dashboard
+  consumers — verifies `review-convergence: true` AND `approved: true`.
+- `tests/unit/ProjectRoundLock.test.ts` (9 cases) — acquire on free,
+  reject on held + alive PID, stale-PID sweep, release returns true /
+  false correctly, malformed-file tolerance, `isAlive` edges.
+- `tests/unit/ProjectRoundRunner.test.ts` (27 cases) — all preflight
+  reject codes (`PROJECT_NOT_FOUND`, `PROJECT_NOT_PROJECT_KIND`,
+  `PROJECT_INACTIVE`, `ROUND_INDEX_OUT_OF_RANGE`, `PROJECT_HALTED`,
+  `FIRST_LAUNCH_ACK_REQUIRED`, `UNACKED_ADVANCES_OVER_CAP`,
+  `ROUND_ACK_GAP_TOO_LARGE`, `NOT_OWNER_MACHINE`,
+  `TARGET_REPO_PATH_INVALID`, `LOCK_HELD`, `ITEMS_NOT_ALL_APPROVED`) +
+  happy path, halt idempotent + lock-release behavior, recordAck
+  semantics (populate + reset + never-regress + idempotent on index),
+  acceptPartial (skip + complete-with-skips + ack-advance),
+  `validateChildFrontmatter` happy + reject cases.
+
+Modified files:
+- `src/server/routes.ts` (+~190 lines) — adds `projectRoundRunner`
+  field to `RouteContext`. Adds four mutating routes:
+  - `POST /projects/:id/advance` — single-item stage transition through
+    `StageTransitionValidator`. Requires `If-Match` (OCC). Body:
+    `{itemId, targetStage, artifact: {...}, fromStage?}`. Returns
+    409 on validator reject (with code + reason), 409 on version
+    mismatch, 404 on unknown child / non-project record, 428 on
+    missing `If-Match`. Bumps project version on success so concurrent
+    /advance calls don't operate on a stale view.
+  - `POST /projects/:id/halt` — calls `ProjectRoundRunner.halt`. Body:
+    `{reason}`. Idempotent.
+  - `POST /projects/:id/ack` — calls `ProjectRoundRunner.recordAck`.
+    Body: `{forRoundIndex}` (or `{roundIndex}` for symmetry).
+  - `POST /projects/:id/accept-partial` — calls
+    `ProjectRoundRunner.acceptPartial`. Body:
+    `{roundIndex, reason, skippedBy}`. Both `reason` and `skippedBy`
+    required (downstream StageTransitionValidator demands them on
+    every `* → skipped` transition).
+- `src/server/AgentServer.ts` (+5 lines) — `projectRoundRunner`
+  field added to `AgentServerOptions` + passed through to the
+  `RouteContext`.
+- `src/commands/server.ts` (+10 lines) — instantiates
+  `ProjectRoundRunner` at startup, passes it into `new AgentServer({})`.
+  `machineId` falls back to `os.hostname()` when the multi-machine
+  coordinator isn't configured, matching the existing fallback in
+  `src/commands/server.ts:5428`.
+- `tests/integration/projects-api.test.ts` (+~150 lines) — 11 new
+  integration cases covering the four new routes. `targetRepo` is
+  now `git init`-ialized in `beforeAll` so preflight step 8 passes;
+  the `ProjectRoundRunner` is instantiated and passed into
+  `AgentServer`.
+
+## Decision-point inventory
+
+- **Preflight gate** (`ProjectRoundRunner.preflight`) — **add** — the
+  single chokepoint for round-start authority. Routes don't re-implement
+  these checks; the runner is authoritative. Drift check (step 10) is
+  intentionally deferred until the drift-check HTTP endpoint and its
+  cache+ledger wiring are in place.
+- **Lock acquisition** (`ProjectRoundLock.acquire`) — **add** —
+  `O_CREAT|O_EXCL` + rename. Stale-PID sweep ensures a dead runner
+  doesn't permanently block subsequent acquires. The lock file is
+  MACHINE-LOCAL (under `.instar/local/`, not git-synced), matching the
+  spec's separation between machine-level mutual exclusion and
+  cross-machine ownership via `ownerMachineId`.
+- **Stage transition rejection** (`/advance` calling
+  `validateStageTransition`) — **reuse** — the validator from PR 2 is
+  the authority for artifact-bound transitions. Routes return its
+  rejection code verbatim.
+- **OCC enforcement on every mutating route** — **add** — `If-Match`
+  required on `/advance` (428 if missing, 409 if stale). Halt, ack,
+  accept-partial use the tracker's own `If-Match`-aware `update()`,
+  re-asserting the spec's OCC contract across the new routes.
+- **Halt as idempotent kill switch** (`ProjectRoundRunner.halt`) —
+  **add** — finds the active round (preference: in-progress → pending /
+  ready → already-halted) and writes `haltedAt` + `haltReason` if not
+  already set. Releases the lock if the calling machine holds it. The
+  SIGTERM-of-autonomous-child path lands when `run()` ships in a
+  follow-up.
+
+## Over-block vs under-block analysis
+
+### Preflight
+Over-block: every reject code corresponds to a documented spec invariant
+(see § Phase 1.5 steps 1–9). Returning a structured `code` (rather than
+just `reason`) lets the dashboard render targeted UI hints later. The
+default-undefined round status is treated as `'pending'`, so freshly-
+parsed plan-doc rounds don't false-negative on a status check.
+
+Under-block: step 10 (drift check) is missing here. The follow-up PR
+that wires the drift-check HTTP endpoint will add it to preflight in
+the same commit. Until then, callers SHOULD treat preflight as
+"deterministic gate passed; drift signal still pending."
+
+### `/advance` route
+Over-block: rejects with 409 on every validator failure (file missing,
+slug regex fail, frontmatter mismatch, mergeCommit not on origin/main,
+etc.). The 409 body carries `{error, code, reason}` so callers can
+distinguish failure modes. **Refuses to advance without
+`If-Match`** even though the canonical project record may not have
+changed — protects against TOCTOU when two clients race
+on the same record.
+
+Under-block: `/advance` operates on child records, not on rounds. It
+does NOT enforce round-level invariants (first-launch ack, owner
+machine, etc.) — those belong to `run()` (the autonomous loop) and to
+auto-advance. This is intentional and matches the spec's separation
+between "single-item user-driven advance" and "round-start automated
+flow." The follow-up PR will close any gap if a `run()` consumer
+discovers one.
+
+### Lock primitive
+Over-block: the rename can technically race with another acquirer if
+two processes pass the read-then-write window simultaneously. The spec
+declares at-most-one-runner-per-machine as a single-process guarantee
+(routes hold the call in one promise; runners only spawn from the
+supervised AgentServer), so cross-process concurrent acquires are
+out-of-band. Documented in the source comment.
+
+Under-block: a runner that crashes between rename and a subsequent
+operation leaves a lock file holding its (now-dead) PID. The stale-PID
+sweep on the next acquire reclaims it. No alternate path (e.g., file
+mtime-based timeout) is needed at this layer.
+
+## Signal vs authority audit
+
+The runner is authority for round-start preflight. It produces a
+deterministic `ok|reject` based on verifiable artifacts (tracker
+record fields, lock file state, filesystem checks, `gh pr view` via
+the existing StageTransitionValidator). No LLM-mediated judgment
+lives here — that's the drift checker (signal), which is invoked
+separately at step 10 (deferred).
+
+The HTTP routes don't add authority; they thread requests through the
+runner / validator. Auth is enforced globally by `authMiddleware`.
+OCC is enforced via `If-Match`. The validator's reject codes flow
+verbatim to the response — clients see the exact failure mode.
+
+## Interactions with existing systems
+
+- **`InitiativeTracker.update()`.** Halt / ack / accept-partial all
+  mutate through update with `ifMatch`, so concurrent writers race
+  through the tracker's existing OCC. Bumping the project version
+  inside `/advance` (via a no-op `nextCheckAt` self-write) makes the
+  next caller see the new version on `GET /projects/:id`.
+- **`StageTransitionValidator`.** The drift checker (PR 1) and the
+  /advance route (this PR) are the only callers. Validator's slug
+  regex + `realpath` jailing protect against path traversal in the
+  `specPath` artifact field.
+- **`ProjectDigestCache`.** Every mutation (halt, ack, accept-partial,
+  advance) goes through the tracker, which calls the digest cache
+  invalidator on the write path. Session-start hook reads the updated
+  cache on next session bootstrap.
+- **Multi-machine.** `machineId` is read from
+  `coordinator.identity?.machineId ?? os.hostname()` — same fallback
+  the existing PR-coordination code uses. `NOT_OWNER_MACHINE` rejection
+  fires if a project record has been claimed by another machine; the
+  claim-ownership flow ships in PR 4.
+- **No new dependencies.** `proper-lockfile` (already a dep) is NOT
+  used here — the round-runner lock is sub-process scoped, where the
+  atomic-rename pattern is cheaper and matches the spec's
+  machine-local intent.
+
+## Rollback cost
+
+Revert deletes `src/core/ProjectRound{Lock,Runner}.ts`, removes the
+ctx field, drops the four routes, drops the test files. Existing
+project records carry the optional fields `firstLaunchAckAt`,
+`lastAckedRoundIndex`, etc. through unchanged — older code that
+doesn't know about them ignores them. No schema migration, no
+state-file migrations. The lock file at `.instar/local/round-runner.lock`
+becomes orphaned but harmless; subsequent acquires would error
+gracefully because no code reads it.
+
+## What this PR explicitly defers (and where it lands)
+
+- **Step 10 of preflight (drift check).** Lands when `POST
+  /projects/:id/drift-check` ships with its per-project mutex; the
+  cache + ledger from PR 2 are already on disk waiting for a consumer.
+- **Autonomous-delegating run loop (`run()`)** with lazy worktrees,
+  dynamic stop-condition revalidation, SIGTERM/SIGKILL of process
+  groups, partial-complete detection. Round-runner verb scope is
+  state-management today; the orchestration loop is the next
+  follow-up PR.
+- **Auto-advance poller** and **multi-machine claim-ownership**.
+  Phase 1b PR 4.
+- **`GET /projects/:id/next` real implementation.** Still 501 in PR 3;
+  ships alongside `run()`.
+
+## Verification
+
+- `npm run lint` — passes (tsc + lint-no-direct-destructive).
+- `npx vitest run tests/unit/ProjectRoundLock.test.ts
+  tests/unit/ProjectRoundRunner.test.ts
+  tests/integration/projects-api.test.ts` — 61/61 pass (9 lock + 27
+  runner + 25 routes).
+- Existing PR 1 + PR 2 tests still green (DriftChecker / Cache / Ledger
+  tests unaffected — the runner doesn't touch them yet).

package/upgrades/side-effects/project-scope-phase1b-pr4.md

@@ -0,0 +1,198 @@
+# Side-Effects Review — project-scope Phase 1b PR 4 (Auto-advance poller + multi-machine claim-ownership)
+
+**Version / slug:** `project-scope-phase1b-pr4`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `required (new periodic-job + new multi-machine ownership transfer surface)`
+
+## Summary of the change
+
+Fourth PR of project-scope Phase 1b. Ships the three pieces the spec
+names for multi-machine and time-based round automation:
+
+- `MachineHeartbeat` — per-machine liveness signal at
+  `.instar/machine-health/<machineId>.json` (git-synced), updated every
+  30 minutes. Consulted by the claim-ownership flow for the 48h
+  staleness check.
+- `ProjectAutoAdvancePoller` — periodic scan that finds projects
+  with `autoAdvanceAt <= now` and bookkeeps the next round
+  (clears the timestamp, increments `unacknowledgedAdvanceCount`)
+  when the round runner's preflight passes.
+- `POST /projects/:id/claim-ownership` — OCC-protected ownership
+  transfer with the heartbeat-staleness gate.
+- Post-restore reconciler — server startup downgrades any round
+  flagged `in-progress` to `pending` (the previous owner may have
+  crashed; no TaskFlow exists yet to detect an actually-live run).
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` § P5 ("Machine ownership"),
+§ Phase 1.3 (HTTP), § Phase 1.5 ("Auto-advance polling"), § Phase 1.12
+("Post-restore reconciler").
+
+New files:
+- `src/core/MachineHeartbeat.ts` (~160 lines) — write + read +
+  isStale + listAll. Machine id is URL-encoded into the file name so a
+  stray slash can't escape `.instar/machine-health/`. Periodic timer
+  is `.unref()`'d so heartbeats never keep the process alive.
+- `src/core/ProjectAutoAdvancePoller.ts` (~140 lines) — `tick()` does
+  one pass over `tracker.list({kind:'project', status:'active'})`,
+  applies the owner-machine / cap / autoAdvanceAt filters, calls
+  `ProjectRoundRunner.preflight`, and either bookkeeps the fire or
+  clears the timestamp on structural rejects.
+- `tests/unit/MachineHeartbeat.test.ts` (10 cases)
+- `tests/unit/ProjectAutoAdvancePoller.test.ts` (7 cases)
+
+Modified files:
+- `src/server/routes.ts` (+~65 lines) — `machineHeartbeat` field on
+  `RouteContext`. New route `POST /projects/:id/claim-ownership` with
+  OCC + heartbeat-staleness gate. Idempotent on already-owns,
+  409 on fresh-peer-heartbeat (unless `{force:true}`), 200 with
+  `previousOwner` and `ownerMachineId` on success.
+- `src/server/AgentServer.ts` (+8 lines) — `machineHeartbeat` field
+  on `AgentServerOptions`, threaded into `RouteContext`.
+- `src/commands/server.ts` (+~50 lines) — instantiates
+  `MachineHeartbeat`, calls `start()`, instantiates
+  `ProjectAutoAdvancePoller` and wires a 60-second interval (also
+  `.unref()`'d). Runs the post-restore reconciler once at startup,
+  best-effort, ignoring OCC races.
+- `tests/integration/projects-api.test.ts` (+~110 lines) — 5 new
+  integration cases for `/claim-ownership`: idempotent on
+  already-owned, refused on fresh peer heartbeat, succeeds on stale
+  peer heartbeat, `{force:true}` override, auth + If-Match gates.
+
+## Decision-point inventory
+
+- **Heartbeat staleness gate** (`MachineHeartbeat.isStale`) — **add** —
+  returns true when the file is missing, malformed, or older than the
+  threshold (default 48h, configurable for tests). Used by
+  `/claim-ownership` to decide whether a peer's record is recoverable.
+  Conservative: a missing record is treated as stale (consistent with
+  the spec's "leader-election fires when no heartbeat").
+- **Claim-ownership refusal** (`/claim-ownership` route) — **add** —
+  refuses with 409 when the current owner has a fresh heartbeat AND
+  `force: true` was not set. Idempotent on already-owns.
+- **Auto-advance structural-reject clearing**
+  (`ProjectAutoAdvancePoller.tick`) — **add** — rejects from preflight
+  that mean "the project structurally cannot advance" (FIRST_LAUNCH_ACK_REQUIRED,
+  UNACKED_ADVANCES_OVER_CAP, PROJECT_INACTIVE, PROJECT_HALTED,
+  PROJECT_NOT_PROJECT_KIND, PROJECT_NOT_FOUND, TARGET_REPO_PATH_INVALID,
+  ROUND_ACK_GAP_TOO_LARGE) cause us to clear `autoAdvanceAt` so we don't
+  re-fire every tick. Transient rejects (lock held, items missing
+  temporarily) leave the timestamp so a future tick can succeed.
+- **Post-restore reconciler downgrade** — **add** — startup-only,
+  one-shot. Any project round flagged `in-progress` is reset to
+  `pending`. The previous owner may have crashed; no TaskFlow yet
+  exists to verify whether a child is actually live. Best-effort — OCC
+  races are silently ignored (next reconcile pass will retry).
+
+## Over-block vs under-block analysis
+
+### Auto-advance poller
+Over-block: the structural-reject list errs on the side of clearing
+`autoAdvanceAt`. The cap-brake (≥2 unacked) is in that list, so if a
+user acks the project the timestamp is no longer set — they'd have to
+explicitly re-set it (or wait for a completed round to auto-set the
+next). Acceptable: requiring an explicit step to re-engage auto-advance
+after the brake fires matches the spec's user-attention semantics.
+
+Under-block: the poller skips projects with a different owner machine
+silently — no attention queue entry, no telemetry. A user who's
+working with a forgotten ownership claim would not see this from the
+poller's perspective; they'd need to use `/claim-ownership` or
+`/projects/:id` to discover the state. Acceptable: this is the
+documented multi-machine semantics, not a failure.
+
+### Claim-ownership
+Over-block: refuses 409 when the peer heartbeat is fresh AND no
+`{force:true}`. The `force` flag is the documented escape hatch when
+two machines genuinely conflict — fairness preserved by recording the
+`previousOwner` in the response and by the audit-log entry the route
+emits.
+
+Under-block: the route only RECORDS the claim. The spec requires the
+caller to commit-and-push the change AND wait 60s for git-sync to
+converge BEFORE acting on it. That's a property of the consumer (the
+round runner, the auto-advance poller, the dashboard) — not this
+endpoint. The endpoint's behavior is correct as a primitive; the
+caller-level safety is documented in the spec and enforced when the
+autonomous loop ships.
+
+### Heartbeat
+Over-block: a malformed heartbeat is treated as stale. A peer with a
+corrupted record could lose ownership unexpectedly. The corruption
+case is rare (atomic write + rename) and the recovery is one write of
+a fresh record.
+
+Under-block: heartbeats are written every 30 minutes. A machine that
+sleeps for an hour then wakes up will have a 30-90 minute gap before
+the next heartbeat lands. Acceptable: the staleness threshold is 48h
+by spec, leaving generous slack for sleep/wake cycles.
+
+## Signal vs authority audit
+
+The poller is **authority** for time-based round advancement bookkeeping
+but the *decision to advance* still routes through the round runner's
+preflight (the chokepoint). The poller never bypasses preflight.
+
+The heartbeat is **signal** for staleness — the claim-ownership endpoint
+uses it as one input to its decision, alongside OCC and `{force}`.
+The signal is read-only deterministic, no LLM-mediated judgment.
+
+The post-restore reconciler is **authority** for the narrow case of
+"no TaskFlow yet exists" → downgrade-to-pending. It does NOT touch
+rounds in any other state. Future TaskFlow integration will provide
+the authoritative liveness check.
+
+## Interactions with existing systems
+
+- **`InitiativeTracker.update()`.** Every mutation in this PR
+  (auto-advance bookkeeping, claim-ownership, reconciler) goes through
+  `update` with OCC. Concurrent writes race through the tracker's
+  existing version-mismatch mechanism.
+- **`ProjectRoundRunner.preflight()`.** The poller's only entry into
+  the runner. Preflight rejects are surfaced verbatim (code + reason)
+  to telemetry — no re-interpretation here.
+- **Git-sync.** The heartbeat file lives at
+  `.instar/machine-health/<machineId>.json` — the GitSync layer treats
+  it like any other state file. Per-machine paths mean two machines
+  never collide on the same file.
+- **Multi-machine coordinator.** `machineId` source: the existing
+  `coordinator.identity?.machineId ?? os.hostname()` fallback,
+  consistent with PR 3.
+- **Scheduler.** Auto-advance poller runs on its own 1-minute
+  `setInterval`, not through the existing `JobScheduler` cron system.
+  Rationale: the poller is a small, fast scan (millisecond-class on
+  typical project sets) and doesn't benefit from the job scheduler's
+  rate-limit / quota plumbing. Both timers are `.unref()`'d.
+
+## Rollback cost
+
+Revert deletes `src/core/MachineHeartbeat.ts`,
+`src/core/ProjectAutoAdvancePoller.ts`, removes the new ctx field,
+drops the `/claim-ownership` route, drops the heartbeat + poller
+instantiation from `src/commands/server.ts`. Heartbeat files on disk
+become orphaned but harmless. Project records carry the optional
+`ownerMachineId` field through unchanged; older code that doesn't
+know about it ignores it.
+
+## What this PR explicitly defers
+
+- **Autonomous-delegating `run()` loop.** The poller bookkeeps the
+  auto-advance move (increments `unacknowledgedAdvanceCount`, clears
+  `autoAdvanceAt`); the actual round-running work waits on `run()`.
+  Phase 1b PR 5.
+- **`GET /projects/:id/next` real implementation.** Still 501 in PR 4.
+  Ships alongside `run()` in PR 5.
+- **`POST /projects/:id/resolve-conflict`.** The git-sync conflict
+  resolution endpoint. Phase 1.12 work; ships when the git-sync
+  conflict path is rebuilt.
+
+## Verification
+
+- `npm run lint` — passes (tsc + lint-no-direct-destructive).
+- `npx vitest run tests/integration/projects-api.test.ts
+  tests/unit/MachineHeartbeat.test.ts
+  tests/unit/ProjectAutoAdvancePoller.test.ts
+  tests/unit/ProjectRoundRunner.test.ts
+  tests/unit/ProjectRoundLock.test.ts
+  tests/unit/route-completeness.test.ts` — 92/92 pass (30 integration
+  + 27 runner + 10 heartbeat + 9 lock + 7 poller + 9 route-completeness).

package/upgrades/side-effects/project-scope-phase1b-pr5.md

@@ -0,0 +1,150 @@
+# Side-Effects Review — project-scope Phase 1b PR 5 (Dashboard Projects tab + Initiatives filter)
+
+**Version / slug:** `project-scope-phase1b-pr5`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `required (new dashboard surface + new server-side filter)`
+
+## Summary of the change
+
+Fifth PR of project-scope Phase 1b. Ships the dashboard surface plus
+the small server-side filter the dashboard depends on. The compaction-
+recovery hook's active-projects digest was already in the template (it
+shipped alongside session-start.sh in Phase 1.9 / PR 1's session-start
+work and the equivalent block is present at lines 467-509 of
+`src/templates/hooks/compaction-recovery.sh`), so no template change
+is needed for this PR.
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.10
+("Dashboard Projects tab"), § Phase 1.10 ("Initiatives tab filter").
+
+Modified files:
+- `dashboard/index.html` (+~210 lines) — adds the Projects tab button
+  alongside the Initiatives tab, adds the Projects panel HTML (header,
+  empty state, list container), registers the tab in the panel router,
+  and ships ~180 lines of JS:
+  - `loadProjects()` — fetches `/projects`, filters to `status:'active'`
+    client-side, fetches each project's joined view via
+    `/projects/:id?reconcile=false` in parallel (capped at 25), renders
+    cards.
+  - `renderProjectCard(project, children)` — XSS-safe construction
+    (`textContent` everywhere, `appendChild` only, no `innerHTML`).
+    Per spec: title row, drift status badge (colored per verdict),
+    round-by-round progress bar + pipelineStage histogram + Halt
+    + Ack buttons.
+  - `startProjectsPoll` / `stopProjectsPoll` — 15-second `setInterval`
+    when the tab is active, cleared on deactivation.
+  - `projectHalt(id)` + `projectAck(id, idx)` — POST to the new
+    runner-backed routes. 409 ("version mismatch") triggers a silent
+    `loadProjects()` re-render rather than an error toast.
+  - `loadInitiatives()` is updated to pass
+    `?excludeKind=project&excludeParented=true` by default, with a
+    "Show projects + children" checkbox to bypass. The filter is
+    server-side; the records never make the wire-trip.
+- `src/server/routes.ts` (+~10 lines) — `GET /initiatives` now accepts
+  `excludeKind=<string>` (drops records where `kind ?? 'task'` matches)
+  and `excludeParented=true` (drops records with a `parentProjectId`).
+- `tests/unit/routes-initiatives.test.ts` (+3 cases + mirror update) —
+  exercises both new params individually and combined with the existing
+  `status=` filter. The test mirror at the top of the file (which
+  duplicates the production handler shape) was updated in lockstep.
+
+## Decision-point inventory
+
+- **Initiatives filter** — **add** — `excludeKind` and
+  `excludeParented` are additive query parameters that DEFAULT TO NOT
+  EXCLUDING. Existing callers see no behavior change. The dashboard
+  opts in via a UI checkbox that defaults to "exclude" (matches the
+  spec's "filter project-kind by default").
+- **Projects tab read-only verbs** — **add** — the Halt and Ack
+  buttons route through the existing `POST /projects/:id/halt` and
+  `POST /projects/:id/ack` (shipped in PR 3). No new HTTP surface in
+  this PR. The buttons act on the project record's current version
+  (from the latest `loadProjects()` fetch); the routes enforce OCC
+  via `If-Match` — actually, `/halt` and `/ack` do NOT require
+  `If-Match` in PR 3's design (they use the tracker's internal
+  version-aware update via `ifMatch` from the latest `get()`). The
+  dashboard relies on that internal handling rather than passing
+  `If-Match` itself.
+- **15-second poll cadence** — **add** — matches the spec exactly.
+  The interval is cleared when the tab deactivates so a hidden tab
+  doesn't burn cycles.
+
+## Over-block vs under-block analysis
+
+### Server-side filter
+Over-block: the dashboard's default-on filter means a user who clicks
+"Initiatives" no longer sees project-kind records or child items
+unless they tick the "Show projects + children" checkbox. This is the
+spec's documented behavior (Projects get their own tab; children live
+inside their parent's card). No information is lost, just relocated.
+
+Under-block: the filter is purely additive. Existing scripts or
+clients that hit `/initiatives` without the new params see the same
+behavior they always have.
+
+### Dashboard rendering
+Over-block: 409 from `/halt` or `/ack` is treated as "stale view,
+just refresh" — no error toast, no user-visible noise. The spec
+explicitly calls this out: "409 response handled silently: refresh
++ re-render, no error toast."
+
+Under-block: the project-list fetch caps detailed lookups at 25. A
+deployment with >25 active projects would have the rest rendered as
+empty cards (since `detailed` is `null` for un-fetched IDs and we
+skip nulls). Acceptable for Phase 1; a follow-up PR can add pagination
+when project count actually exceeds the cap.
+
+### XSS safety
+Every rendered string goes through `.textContent` (never `.innerHTML`).
+Project ids, titles, round names, child stages, drift verdicts — all
+constructed via `createElement` + `textContent` + `appendChild`. The
+existing `dashboard/index.html` conventions already enforce this; the
+new code follows the same pattern.
+
+## Signal vs authority audit
+
+Dashboard is **read-only display** for the project surface (with two
+button-triggered mutating calls to existing PR 3 routes). The
+authority for halt and ack lives in `ProjectRoundRunner` — the
+dashboard just calls the documented endpoints. No new authority
+introduced.
+
+The initiatives filter is a **read-side** filter, not a
+record-modifying gate. The records themselves are unchanged; the
+filter only affects the response set.
+
+## Interactions with existing systems
+
+- **PR Pipeline tab.** No interaction — the Projects tab uses its
+  own panel + JS namespace.
+- **Initiatives tab.** Shares the existing `loadInitiatives()`
+  function; the new filter is a query-string addition with a UI
+  checkbox to bypass. Existing tab behavior preserved when the
+  checkbox is checked.
+- **`/projects/:id?reconcile=false`.** This query parameter is
+  already documented in the spec (Phase 1.3 — "Clients that need
+  pure-read semantics use `?reconcile=false`"). The dashboard uses
+  it to avoid triggering the lazy reconciler on every 15-second
+  poll. The `?reconcile=false` parameter is honored as a passthrough
+  in the existing route (the lazy reconciler isn't wired yet, so
+  it's a no-op today — when the reconciler ships, the dashboard
+  poll won't trigger it).
+- **Compaction-recovery hook.** Already includes the active-projects
+  digest section (PR 1's template work). No change needed in this PR.
+
+## Rollback cost
+
+Revert removes the new tab button, the new panel HTML, the JS block,
+the Initiatives filter checkbox, the server-side filter, and the test
+cases. No schema changes. Existing project records and initiatives
+are unaffected.
+
+## Verification
+
+- `npm run lint` — passes (tsc + lint-no-direct-destructive).
+- `npx vitest run tests/unit/routes-initiatives.test.ts
+  tests/unit/route-completeness.test.ts
+  tests/integration/projects-api.test.ts
+  tests/unit/dashboard-initiativesTab.test.ts` — 66/66 pass.
+- Existing PR 1-4 invariants still green.