instar 0.28.96 → 0.28.98

package/upgrades/side-effects/NEXT.md

@@ -1,61 +1,68 @@
-# Side-Effects Review — Compaction-resume payload carries real context
-
-**Version / slug:** `NEXT` (will be assigned on publish)
-**Date:** `2026-04-17`
-**Author:** `echo`
-**Second-pass reviewer:** `(this is a prompt-shape fix with no Guard surface — second pass not required per skill Phase 5)`
-
-## Summary of the change
-
-Replaces the one-sentence `COMPACTION_RESUME_PROMPT` constant with a payload built from `topicMemory.formatContextForSession(topicId, 20)` (summary + last 20 real messages + search hint). For Slack and TopicMemory-not-ready fallback, the same payload is built from inline log entries via a new `formatInlineHistory` helper. A `prepareInjectionText` helper writes payloads over 500 chars to `/tmp/instar-compaction-resume/` and replaces the inject with a "read this file immediately" reference — matching the `spawnSessionForTopic` bootstrap pattern.
-
-Slack recovery path picks up `findLastRealMessage` as well, so proxy standbys / delivery acks newer than the user's message no longer mask unanswered state.
-
-## Over-block risk
-
-**None.** The decision of whether to recover is unchanged — `lastReal?.fromUser` still gates re-injection on both paths. The change is purely in the *content* of the injected text. No new filter, no new gate, no new "do not recover" conditions.
-
-## Under-block risk
-
-**None.** The module doesn't classify or authorize anything; it builds strings. The existing InputGuard check in `sessionManager.injectMessage` still applies — the Telegram inject still starts with `[telegram:${topicId}]` so provenance is `verified`, bypassing the Layer 1.5 injection-pattern check (unchanged behavior).
-
-## Level-of-abstraction fit
-
-The new module sits at `src/messaging/shared/` alongside `isSystemOrProxyMessage.ts` — same layer as other prompt/classifier helpers shared between the Telegram and Slack messaging paths. It does **not** reach into `SessionManager` internals, does **not** reinvent `InputGuard` logic, and does **not** read/write any state-dir files. It only writes to `/tmp`, which matches the `spawnSessionForTopic` bootstrap pattern (`/tmp/instar-telegram/`).
-
-## Signal-vs-authority compliance
-
-Not applicable. The preamble is a **prompt to the agent**, not a gate with blocking authority. It can only influence; the agent still decides what to say. There is no downstream check that treats the preamble's output as authoritative.
-
-## Interactions
-
-- **`isSystemOrProxyMessage` / `findLastRealMessage`** — now used on both Telegram and Slack recovery paths. Existing contract preserved: filters system/proxy entries, walks backward, returns last real entry. Slack log entries have the same `{ text, fromUser, timestamp }` shape the classifier expects.
-- **`topicMemory.formatContextForSession`** — already used on the session-spawn path. The compaction-resume path now calls the same function with the same args (`recentLimit=20`). No new dependency; no new failure modes.
-- **`sessionManager.injectMessage`** — receives a larger text in the common case. Input handling unchanged: bracketed-paste mode for multi-line content. The 500-char file-threshold keeps us inside the spawn-path's tested envelope.
-- **`PresenceProxy`** — unaffected. Continues to call `isSystemOrProxyMessage` unchanged.
-- **`CompactionSentinel`** — unaffected. It calls `recoverCompactedSession` with the same signature and interprets the boolean return value the same way.
-- **`checkLogForAgentResponse`** — unaffected. Same classifier delegate, same log-scan semantics.
-- **`InputGuard` Layer 2 (coherence review)** — the new payload has more context, which may change LLM verdicts at the margin, but the review is non-blocking (inject already happened) and only emits a warning message. No blocking impact.
-
-## Rollback cost
-
-**Low.** The new module is purely additive — nothing else depends on it. To roll back: revert `src/commands/server.ts` to use the one-line `COMPACTION_RESUME_PROMPT` constant, delete `src/messaging/shared/compactionResumePayload.ts`, delete `tests/unit/compactionResumePayload.test.ts`. No schema changes, no state-file migrations, no API contract changes.
-
-## File-system footprint
-
-The file-reference path creates one file per compaction event in `/tmp/instar-compaction-resume/resume-<topicId>-<ts>-<uuid>.txt`. `/tmp` is cleaned on macOS reboot; files are small (one summary + ~20 messages, typically <10KB). For bounded hygiene we rely on the OS reboot sweep — same as the existing `/tmp/instar-telegram/` and `/tmp/instar-paste/` dirs. No new disk-leak risk.
-
-## Test coverage
-
-`tests/unit/compactionResumePayload.test.ts` (12 tests) covers:
-- Preamble shape and empty-context handling
-- Inline history formatting (sender, timestamp, truncation, missing fields)
-- File-threshold cutover + stub language
-- Topic 6795 regression shape — user's verbatim last message survives the pipeline
-
-Existing `tests/unit/isSystemOrProxyMessage.test.ts` (25 tests) still green — the walk-back contract now used on both recovery paths is unchanged.
-
-## Failure modes explicitly left unfixed
-
-- **Huge conversation summaries.** If `topicMemory`'s rolling summary itself exceeds some absurd size, the file-reference payload could grow large. We cap at `recentLimit=20` messages + summary, so in practice this tops out at ~20–50 KB. Not a concern at current scale; will revisit if we hit it.
-- **Racing compaction events.** If two triggers (PreCompact hook + watchdog poll) fire within milliseconds, `CompactionSentinel` already dedupes — unchanged here.
+# Side-effects review — validator: tighten FIX_PATTERNS to reduce false positives
+
+**Scope**: Three `FIX_PATTERNS` in `upgrade-guide-validator.mjs` were matching
+technical prose that was not claiming a bug fix, causing the publish CI to
+block with a false "no Evidence section" error on the Phase 1b connect-the-dots
+release (NEXT.md v0.28.96).
+
+**Root cause**: The NEXT.md for the Phase 1b connect-the-dots release used
+three words in technical contexts that the validator treated as bug-fix claims:
+- `broken` — "while a child is broken" (describes a runtime state, not a defect
+  we fixed)
+- `crashed` — "a crashed runner" (adjective, describes a process that exited
+  non-zero, not a crash we fixed)
+- `resolve` — "items resolve" and `resolve-conflict` (validation-check language
+  and API action-verb name, not "I fixed an issue")
+
+**Files touched**:
+- `scripts/upgrade-guide-validator.mjs` — three pattern changes:
+  1. `/\bcrashed\b/i` removed. `crashes?` and `crashing` (verb forms) are kept.
+  2. `/\bbroken\b/i` tightened to `/\b(?:was|were)\s+broken\b/i` — only the
+     predicate form ("X was broken") triggers; attributive uses ("a broken
+     pipeline") and present-state descriptions ("is broken") do not.
+  3. `/\bresolves?\b/i` tightened to `/\bresolves?\s+(?:an?\b|the\b)/i` — only
+     "resolves a/an/the <defect>" triggers; bare "resolve" as a technical verb
+     ("items resolve") and hyphenated action verbs ("resolve-conflict") do not.
+- `tests/unit/upgrade-guide-evidence.test.ts` — three regression tests added,
+  one per false-positive pattern.
+
+**Under-block**: Three narrow edge cases are no longer caught:
+
+1. `crashed` standalone past tense: "the server crashed when X" without also
+   containing "fix" or another trigger. In practice any guide describing a crash
+   fix would also say "fixed a crash" or "fixes the crash" — caught by the
+   existing `\bfix(es|ed|ing)?\b` pattern. Removal of `crashed` alone is
+   low-risk.
+
+2. `broken` as attributive adjective or present state: "fixed the broken poller"
+   still triggers because "fixed" catches it. "X is broken (and we fixed it)"
+   would also need "fixed" or another trigger — acceptable.
+
+3. `resolves` without article: "Resolves race condition" (unusual English, almost
+   always "Resolves the/a race condition"). The tightened pattern retains all
+   natural phrasing.
+
+**Over-block**: None introduced. The change makes the validator more permissive.
+Historical guide warnings decrease slightly.
+
+**Level-of-abstraction fit**: `claimsFix` is a pure heuristic signal. The gate
+(`validateGuideContent` requiring Evidence) is the authority. These changes stay
+entirely within the signal layer. Evidence requirement, Evidence validation, and
+all structural checks are unchanged.
+
+**Signal vs authority**: Compliant. Tightened patterns are still signals; blocking
+authority remains in the Evidence-section check. No new blocking authority.
+
+**Interactions**: `claimsFix` is called only from `validateGuideContent`, called
+by `check-upgrade-guide.js` (CI publish gate) and the test suite. No other
+callers. Historical guide warnings decrease slightly — correct noise reduction.
+
+**External surfaces**: None. `claimsFix`/`evidenceIssues` are not part of the
+public npm package surface. No API, config, or CLI change.
+
+**Rollback cost**: Trivial. 7 lines changed in validator, 18 lines added to test.
+Revert brings back the over-broad patterns.
+
+**Tests**: 24/24 unit tests pass in `upgrade-guide-evidence.test.ts` (3 new +
+21 prior). 1294/1294 tests pass across all three upgrade-guide test files.
+`check-upgrade-guide.js` passes against the previously-blocking NEXT.md.

package/upgrades/side-effects/jobs-as-agentmd-phase-1a.md

@@ -0,0 +1,153 @@
+# Side-Effects Review — jobs-as-agentmd Phase 1a
+
+**Version / slug:** `jobs-as-agentmd-phase-1a`
+**Date:** `2026-05-12`
+**Author:** `echo`
+**Second-pass reviewer:** _appended below at completion_
+
+## Summary of the change
+
+Phase 1a of the INSTAR-JOBS-AS-AGENTMD spec lands the **loader-side only** support for the new agentmd format. The scheduler can now read per-slug manifests at `.instar/jobs/schedule/<slug>.json`, validate them, resolve and parse a markdown body at `.instar/jobs/<origin>/<slug>.md`, and surface fully-populated `JobDefinition` records into memory. The agentmd entries do NOT yet fire — Phase 1b adds scheduler dispatch and Phase 1c adds the signed lock-file pipeline. Existing `execute.type: "prompt" | "skill" | "script"` entries are unchanged. Files touched:
+
+- `src/core/types.ts` — additive fields on `JobDefinition` and a new optional case on `JobExecution.type`. New `AgentMdExecute` interface.
+- `src/scheduler/AgentMdJobLoader.ts` — new module containing manifest validation, agentmd body loader, YAML hardening, Zod preprocessors, path-safety checks, case-fold collision resolution, and a bounded-concurrency runner.
+- `src/scheduler/JobLoader.ts` — extended `loadJobs` to also load per-slug manifests, merge with legacy `jobs.json` (per-slug wins on collision), and re-export `LoadProblem`.
+- `src/scheduler/JobScheduler.ts` — `buildPrompt` learns `case 'agentmd':` (throws — Phase 1b implements it); `start()` filters out agentmd entries from the active set with a loud log line.
+- `tests/unit/scheduler/JobLoader.agentmd.test.ts` — 68 new tests.
+- `tests/unit/scheduler/agentmd-helpers.ts` — synthetic-agent fixture helper.
+- `package.json` — adds `js-yaml ≥ 4` and `@types/js-yaml`. No `p-limit` (hand-rolled bounded-concurrency to avoid a new dep, per spec permission).
+- `upgrades/NEXT.md` — release notes with Evidence section.
+
+The decision points this change interacts with:
+
+## Decision-point inventory
+
+- **Job validation** (`JobLoader.validateJob`) — pass-through (unchanged). New manifest validator (`AgentMdJobLoader.validateManifest`) covers the per-slug shape.
+- **YAML parsing surface** — added. `js-yaml` FAILSAFE_SCHEMA + parsed-tree anchor rejection. Hard-invariant boundary validation.
+- **Path safety on filesystem reads** — added. `realpath` + `lstat` + slug regex. Hard-invariant structural checks.
+- **Tool-allowlist gate** (existing, owned by Phase 1b/1c) — pass-through. Phase 1a reads `unrestrictedTools` into `JobDefinition` but does not act on it.
+- **Grounding-audit gate** (`JobLoader.auditGrounding`) — pass-through. Phase 1a does not change how it routes; agentmd jobs flow through the same audit path post-merge.
+- **Scheduler dispatch** (`JobScheduler.start`/`buildPrompt`) — modified: agentmd entries filtered from active set with a clear log line; `buildPrompt` throws on agentmd as a programmer-error guard (Phase 1b removes the throw).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The change adds three rejection surfaces — all of them documented and tested:
+
+- **YAML anchor rejection.** Done at the parsed-tree level via `js-yaml`'s `listener` callback, NOT at raw-text. A raw-text precheck would have over-rejected legitimate string values like `description: "Bash & Read"` or `description: "matches *.md files"`. There is an explicit test (`ACCEPTS anchor-like text inside string values`) asserting that such legitimate values pass.
+- **Frontmatter key whitelist.** Closed-set: `name`, `description`, `toolAllowlist`, `grounding`, `notificationMode`, `viewMetadata`, `commonBlockers`. An author writing a key outside this set gets a per-entry skip with a problem record naming the unknown key. Phase 1a starter set; the spec's later phases extend it. The over-block is bounded: adding a new key is a code change, not silent.
+- **Slug regex.** ASCII-only `^[a-zA-Z0-9_-]{1,100}$`. This deliberately rejects NFD-encoded, RTL-override, ZWJ/ZWNJ/ZWSP, dotless-i, and `..`/`/`/NUL inputs. Legitimate slugs in any human-readable form are ASCII; the regex is the same one shipped in `validateJob` today.
+
+For each surface, per-entry skip is the response (the scheduler keeps running with the surviving jobs) — not refuse-to-boot.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Manifest "value" field for agentmd.** The validator rejects `execute.value` when `execute.type === "agentmd"`. It does NOT enforce the inverse — a manifest with `type: "skill"` but no `value` was already rejected by the legacy validator; this is structurally unchanged.
+- **Frontmatter `commonBlockers` deep-validation.** Phase 1a accepts `commonBlockers` as part of the closed-set whitelist but does not deeply validate it inside the agentmd path. The legacy `validateCommonBlockers` in `JobLoader.ts` is still the authority on shape; agentmd entries carrying `commonBlockers` will be validated by it when Phase 1b wires the field through to scheduler dispatch.
+- **Hash verification against lock-file.** This is the explicit responsibility of Phase 1c. Phase 1a treats `origin === "instar"` as a manifest claim only, NOT a trust elevation. Per spec §"Two namespaces": `origin` is a signal, the lock-file (Phase 1c) is the authority.
+- **Per-process file descriptor exhaustion.** Bounded by the read-concurrency limit of 32 and the small expected manifest count (<= 200 entries per spec budget). Tested up to 10 concurrent reads.
+
+These misses are bounded-by-design and pinned to subsequent phases.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The change introduces structural, deterministic validation gates at the I/O boundary:
+
+- **Zod schema validation** of typed frontmatter fields → hard-invariant type validation, executed once per file at load. Not judgment, not context-dependent.
+- **YAML parser hardening** (FAILSAFE_SCHEMA, anchor-walk, size caps) → structural rejection of malformed input. Same shape as the JSON parsing in `validateJob` today.
+- **Path safety** (`realpath`/`lstat`/regex) → deterministic filesystem-shape checks. Same shape as existing path safety in SafeFsExecutor.
+
+None of these are smart-gate-replacements. None of them hold semantic authority — they own the same kind of boundary validation already done at every other instar I/O surface (e.g. `validateJob`, manifest validation in `MachineRegistry`, etc.). The `instar`-wins case-fold collision resolution is a structural disambiguation (origin field comparison), not a brittle heuristic.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface that requires conversational reasoning. The validation gates added here are exactly the kinds the doc enumerates as legitimate:
+  - **Boundary type validation (Zod):** hard-invariant.
+  - **Structural rejection of malformed/unsafe input (YAML parser hardening):** hard-invariant.
+  - **Path safety on filesystem reads:** deterministic checks.
+  - **Case-fold collision resolution by origin:** structural disambiguation rule, not a brittle blocker. The fallback is "skip both with a surfaced problem," and the rule is named in the spec text.
+
+The change introduces **no new gate that consumes user message intent or conversational context.** The per-entry skip pattern is the existing pattern in `JobLoader.ts`. The "origin: instar wins on collision" rule is the only new decision authority, and it is a closed-form structural rule, not a brittle classifier.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing.** Per-slug manifests shadow legacy `jobs.json` entries with the same slug. This is deliberate per spec §"Backwards Compatibility" and is logged at load time so an operator sees which legacy entries are no longer active. Test: `per-slug manifest shadows legacy jobs.json entry of the same slug`.
+- **Double-fire.** The scheduler filters agentmd entries out of its dispatch set in Phase 1a (`JobScheduler.start` filter). `buildPrompt` throws on agentmd as a defense-in-depth guard. Two layers prevent the same misfire — load surfaces the job, but dispatch refuses it until Phase 1b. There is no path by which an agentmd entry could fire its prompt body in Phase 1a; the throw is dead-code-by-design for now.
+- **Races.** All filesystem I/O is sync (matching the existing `loadJobs` sync API). The bounded-concurrency runner is exported but not yet used in the boot path — it's the migration surface for Phase 1b's async dispatch. No shared mutable state is introduced.
+- **Feedback loops.** None. The change does not emit events into a system that consumes them in a self-reinforcing way.
+
+The interaction with `JobScheduler.buildPrompt` deserves a closer look. Adding `case 'agentmd'` that throws means: if anything queues an agentmd job, the runtime will throw inside the cron-driven invocation. But the queue-feed is `start()`'s filter, which explicitly excludes agentmd entries from `scopedJobs`. Tested + verified — the throw is unreachable in Phase 1a runtime. The throw exists so that a Phase 1b implementer wiring buildPrompt cannot accidentally fall through to `undefined`.
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine?** No. The change is internal to one agent's `.instar/jobs/` tree.
+- **Other users of the install base?** No behavioral change for any pre-spec agent (jobs.json-only is unchanged).
+- **External systems?** None — no network calls added.
+- **Persistent state?** The change reads `.instar/jobs/schedule/<slug>.json` and `.instar/jobs/<origin>/<slug>.md` if those paths exist. It does NOT write or migrate any state. Migration is Phase 3.
+- **Timing or runtime conditions?** Cold-boot time gains one synchronous directory enumeration + per-file read pass. The spec budgets 1500 ms cold @ 200 jobs; current usage is ≪ 50 jobs and the operation is bounded by directory enumeration + 200 small file reads. Well inside budget.
+- **Per-machine commit storms?** The change does not touch the git-sync auto-commit path. Schedule directory files are read-only inputs.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure additive code change with no persistent state migration. Rollback options:
+
+- **Hot-fix revert:** revert the commit. Per-slug manifests on disk simply stop being read; legacy `jobs.json` continues to drive the scheduler. No user-visible regression during rollback window because Phase 1a does not dispatch agentmd entries.
+- **Field flip:** because agentmd is filtered at `JobScheduler.start`, an emergency disable could be effected by deleting all `.instar/jobs/schedule/*.json` files (operator action). No data loss — the manifests are recoverable from git history.
+- **No schema migration.** The disk format on `.instar/jobs/schedule/` is new — there are no Phase 1a agents that have populated it yet (Phase 3 ships the migration script). Rollback before Phase 3 is "delete schedule/ if present"; rollback after Phase 3 requires `instar jobs migrate --abandon` (defined in spec).
+
+Estimated rollback: revert + patch release. Five minutes of build + publish.
+
+---
+
+## Conclusion
+
+Phase 1a is structural, additive, and rollback-cheap. The validation gates it introduces are boundary type/shape checks (Zod, YAML hardening, path safety) and one closed-form disambiguation rule (origin-wins on case-fold collision). No brittle blocking authority is added. The scheduler dispatch path is intentionally NOT updated — agentmd entries load into memory but cannot fire until Phase 1b. Two defense-in-depth layers (the `start()` filter and the `buildPrompt` throw) prevent an agentmd entry from accidentally running its body in Phase 1a. The change ships with 68 new tests covering happy path, every YAML hardening case, every Zod coercion semantic per spec §6, every path-safety vector, both case-fold collision modes, both mixed-state precedence scenarios, the backwards-compat invariant, and the hydration invariant the SchedulerProbe will assert against in Phase 1b.
+
+The change is clear to ship.
+
+---
+
+## Second-pass review
+
+**Reviewer:** focused self-audit (no Task/Spawn tool surface in this build environment — the standard general-purpose subagent surface was unavailable; this is documented honestly here rather than fabricated)
+**Independent read of the artifact: concur, with one verified caveat**
+
+Independent pass over the artifact against the diff:
+
+- **Decision-point inventory matches code.** Confirmed by re-reading `src/scheduler/JobLoader.ts`, `src/scheduler/AgentMdJobLoader.ts`, and `src/scheduler/JobScheduler.ts`. No undocumented decision-point touched. The `buildPrompt` `case 'agentmd':` throw is the only "modified-but-Phase-1b" line and is correctly disclosed.
+- **Over-block claim verified by test.** `ACCEPTS anchor-like text inside string values (Bash & Read, *.md)` exists at `tests/unit/scheduler/JobLoader.agentmd.test.ts` and passes. The risk of over-rejecting legitimate `&`/`*` in prose strings is therefore tested-against, not just claimed.
+- **Under-block claim verified by scope.** `commonBlockers` deep-validation is correctly deferred. The legacy `validateCommonBlockers` in `JobLoader.ts` is unchanged; agentmd entries do not yet flow through scheduler dispatch (Phase 1b), so no fire-path missing the deep validation exists.
+- **Defense-in-depth on `buildPrompt`.** Re-read: `start()` filters `j.execute.type !== 'agentmd'` from `enabledJobs`; only filtered entries become `scopedJobs`; only `scopedJobs` get cron tasks. Independent of the throw, the agentmd entries are unreachable from cron. The throw is dead-code-by-design; this is correctly stated.
+- **Backwards-compat scope verified.** The new `loadLegacyJobsJson` is a direct extraction of the prior `loadJobs` body with no logic change. Verified by reading both versions side-by-side. The `mergeLegacyWithAgentMd` step is purely additive — when `agentMd` is empty, the legacy list is returned untouched.
+- **One verified caveat (not blocking):** the Zod preprocessor `IntField` rejects `1.5` as written, but a YAML number `1.5` parsed by FAILSAFE_SCHEMA returns the STRING `"1.5"`, not the number 1.5. The IntField preprocessor's `/^-?\d+$/` regex correctly rejects this. The test `rejects floats: '1.5'` covers the string path; the additional test `rejects floats: 1.5 (native number)` covers the number path. Both paths verified.
+
+Concur. The change is structurally clean and ready to ship.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/INSTAR-JOBS-AS-AGENTMD-SPEC.md` (approved 2026-05-12)
+- Convergence report: `docs/specs/reports/instar-jobs-as-agentmd-convergence.md`
+- New tests: `tests/unit/scheduler/JobLoader.agentmd.test.ts` (68 cases, all passing).
+- New helper: `tests/unit/scheduler/agentmd-helpers.ts`.
+- Backwards-compat verification: existing `tests/unit/JobLoader.test.ts` continues to pass unchanged.
+- Logs (local): `node_modules/.bin/vitest run tests/unit/scheduler/JobLoader.agentmd.test.ts` → `Tests  68 passed (68)`.
+- Fixup verified: `node_modules/.bin/vitest run tests/unit/scheduler-queue-edge.test.ts tests/unit/scheduler/JobLoader.agentmd.test.ts tests/unit/JobLoader.test.ts` → `Tests 120 passed (120)`. The fix reverts a typing-tightening (`const execValue`) back to the inlined `job.execute.value` form expected by `scheduler-queue-edge.test.ts:builds skill prompt correctly`, which asserts on the literal source text. No behavioral change; the agentmd case + exhaustive default remain.

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).