@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/docs/provider.md

@@ -0,0 +1,98 @@
+# Knowledge Transport Providers
+
+The sync layer's transport is pluggable (governing record: `knowledge-repo.md` §3.2 extended by
+Amendment 2026-09-21). One project record picks one provider; nothing else knows the difference.
+This file is the contract: what a provider must do, which invariants it inherits, and how each
+backend fills them.
+
+## The seam
+
+`runSync`'s transport surface is exactly six verbs — a provider is those, plus identity:
+
+```ts
+interface SyncProvider extends GitDriver {          // src/provider.ts
+  readonly kind: 'git' | 'treedx'
+  describe(project: ProjectRecord): string          // one honest status line
+  ensureClone(dir, remote, opts?)   // make the mirror exist and reflect the remote
+  initLocal(dir, remote?, opts?)    // offline mirror (§5.3)
+  removeMirror(dir)                 // destroy transport (the store is truth, §3.1)
+  stageAllAndCommit(dir, message, author)  // LOCAL diff workdir-vs-known-baseline
+  pullFastForward(dir, remote, opts?)      // converge; failure classes diverged|network|auth
+  push(dir, remote, opts?)                 // ship the staged delta
+}
+```
+
+Rules a provider must honor (all inherited from the record, restated at the seam):
+
+1. **The mirror directory exists in every mode.** The workspace store is the read path's truth
+   (§3.1); the mirror under `.dsh-knowledge/` is materialized content — search (`loadCorpus`),
+   rules (`collectMirrorRules`), the index build, and the notice layers consume it unchanged.
+   A provider that skips materialization breaks all of them.
+2. **Every failure is a value.** `{ok:false, code}` — the machine-readable classes drive
+   runSync's branching: `network` (degrade to local-only), `diverged` (rebuild the mirror from
+   the store and re-push), `rejected` (pull-and-retry once), `origin-mismatch` (rebuild; never
+   sync into the wrong pool), `auth` (surface the re-link instruction with the detail). Providers
+   branch on status + code, **never on prose** (r35).
+3. **ff-only, append-only.** Divergence is never merge-resolved; it is rebuilt
+   (§5.2). A provider never rewrites remote content.
+4. **Nothing throws into the conversation path**, and no token bytes appear in any `detail`
+   string (§2.1).
+5. **Provider selection is scheme-first, policy-strict.** `treedx+<url>/<repo>` → TreeDX;
+   anything else → git. `knowledgeProvider: 'git'|'treedx'` forces one and REFUSES a
+   contradiction rather than falling back — a wrong pool is a data-privacy failure, not a
+   config convenience (`providerKindFor`).
+
+## Backend truth table
+
+| Verb | git (`gitops.ts`) | TreeDX (`treedx/provider.ts`) |
+|---|---|---|
+| ensureClone | clone (or adopt existing repo + origin sentinel) | resolve repo in the catalog; fetch refs + `paths/list` (no extension filter — the mirror must be faithful) + `files/read`/`blobs/read`; materialize; write `.treedx-state.json` |
+| initLocal | `git init` + origin | state file with `offline: true` (publish/commit/index/search keep working) |
+| stageAllAndCommit | workdir-vs-HEAD content diff → git commit objects | workdir-vs-baseline diff → staged path list in the state file (baseline advances at stage time: restaging identical bytes says 'nothing to commit', the git parity) |
+| pullFastForward | fetch, ancestor checks, ff; non-ff ⇒ `diverged` | head compare vs state. Unmoved ⇒ up to date. Moved, nothing staged ⇒ refetch (ff). Moved with staged work ⇒ `diverged` — a merge could leave derived files (index/, topics/) built against a stale corpus; the rebuild re-derives |
+| push | git push (rejected ⇒ pull-retry) | workspace-create (`refs/heads/main`, one writable lease per branch) → write each staged path (UTF-8 File API; binary via Blob API) → commit. 409 with head unmoved ⇒ `rejected` (lease), bounded retry; 409 after the head moved ⇒ `diverged`; 401 ⇒ `auth` |
+| offline recovery | remote returns → pull diverged → rebuild | `state.offline` + reachable ⇒ `diverged` (same rebuild-from-store path) |
+| origin drift | `.git/DSH-ORIGIN` sentinel | `state.origin` vs the record's remote ⇒ `origin-mismatch` |
+
+## State: `.treedx-state.json` (the TreeDX mirror's `.git/`)
+
+`{origin, head, baseline: {path → sha256}, staged: {message, author, paths} | null, offline, repoId?}`
+— lives inside the mirror, starts with a dot so it never walks into any commit, and is the
+provider's memory across verbs (provider instances stay stateless per call, safe to share).
+
+## Identity and credentials (§2.1/§2.3, one rule for both providers)
+
+`projectKey = UUIDv5(NAMESPACE_OID, "treedx/" + canonicalize(baseUrl/repoName))` for TreeDX;
+the unchanged `canonicalize(remote)` for git. The `treedx/` namespace keeps a service whose URL
+happens to canonicalize like a git remote from stealing another's pool. Credentials ride the
+same DSH-home store (`credentials/<projectKey>`, 0600); for TreeDX the token is ALWAYS required
+(no loopback exemption: TreeDX answers 401, and a service URL without auth is a config bug,
+not a local file).
+
+## What a provider may NOT touch
+
+The workspace store, the registry domain, chapter rendering, redaction, the injection screen
+(`src/injections.ts`), composition, budgets, notice assembly, and the rules-approval gate. The
+approval (§15 amendment: per-machine curation fact) is the trust boundary shared state passes
+through a human on the local machine — a server (TreeDX included, federation included) cannot
+pre-approve anything, because the fact file lives under `edits/<harness-id>/` and the effective
+status is computed locally.
+
+## TreeDX API surface consumed (spikes/treedx/FINDINGS.md carries the pinning)
+
+`GET /health`, `POST /auth/dev-token` (dev), `GET|POST /repos`, `GET /repos/:id/refs`,
+`POST /repos/:id/paths/list`, `POST /repos/:id/files/read`, `POST /repos/:id/blobs/read`,
+`POST /repos/:id/workspaces`, `PUT|DELETE /workspaces/:id/files`, `POST /workspaces/:id/blobs/write`,
+`POST /workspaces/:id/commit`. Server-side search/graph/context (`files/search`, `graph/*`,
+`context/build`) and federation are Phase F: the plugin codes to one ingress URL and federation
+needs no client change.
+
+## Failure semantics summary (§5.3, per backend)
+
+| Condition | git | TreeDX |
+|---|---|---|
+| remote down | offline mirror init; push deferred | offline state; push deferred; pull probes recovery → diverged → rebuild |
+| credential bad/revoked | 401 as network class + detail | `auth` class: status says "re-link the token with /chapters-link", conversation untouched |
+| repo missing | GitHub creates on first push for scoped tokens (config'd) | link command creates it; sync-time absence ⇒ `not_found`, degraded with the name in the detail |
+| oversized file | n/a (packs stream) | File API 413 ⇒ refuse-with-numbers detail (§1.2), never truncate; >1 MiB belongs in multipart (Phase F) |
+| lease busy (two machines at once) | push rejected → pull → retry | create/commit 409 → bounded provider retry → `rejected` → runSync's pull-and-retry |

package/docs/superpowers/plans/2026-10-17-chapters-save.md

@@ -0,0 +1,198 @@
+# Implementation Plan: `/chapters-save` Command
+
+**Issue:** #11
+**Date:** 2026-10-17
+**Author:** Agent (subagent)
+**Status:** ✅ IMPLEMENTED — shipped as a6c840d (#11 → PR #12), hardened by 75ca0ff (#16 → PR #17,
+fire-and-forget enrichment after the timeout bug). `runSave` lives in `src/tools.ts` (`saveCommand`,
+registered beside fork/continue); tests in `tests/unit/save-command.test.ts`; behavior documented on
+the site at `site/src/content/docs/reference/commands.md` § `/chapters-save`. Kept as the design
+record for that command — read it with the shipped code, not as an open to-do.
+
+## Goal
+
+Implement `/chapters-save` — a host command that archives the current session into
+searchable chapters **without** creating a child session or triggering compaction.
+The parent session remains fully functional; archived content becomes searchable
+via `chapters_search` from any session in the workspace.
+
+## Success Criteria
+
+- `/chapters-save` archives completed turns into verbatim chapter files on disk
+- Session state is updated with new chapter records (search index picks them up)
+- Enrichment is triggered after archiving (if configured)
+- Idempotent: respects the watermark, re-running saves only new content
+- No child session is created
+- No compaction is triggered
+- Returns clear success/error messages
+
+## Architecture Decision
+
+`/chapters-save` is the **side-effect-only half** of the deterministic door. It reuses
+the same archive pipeline as `/chapters-fork` and `/chapters-continue`:
+
+```
+composeChapters → renderChapter → writeArchive → commitChapters → scheduler.schedule
+```
+
+But stops before `agents.create`. The key insight: `runContinue` in `src/continue-core.ts`
+bundles rendering + writing + child creation into one function. We need to extract the
+render+write portion into a reusable function, then call it from both `runContinue` and
+the new `runSave`.
+
+### Why NOT reuse `runContinue` directly
+
+`runContinue` calls `finishChild` which does budget preflight, notice assembly, and
+`ports.createChild` — all of which are irrelevant for save. Extracting the archive-only
+portion avoids coupling save to child-creation logic and keeps the atomicity contract
+clean.
+
+## File Structure
+
+| File | Change | Responsibility |
+|------|--------|---------------|
+| `src/continue-core.ts` | Add `runSave()` function | Pure archive-without-child orchestration |
+| `src/tools.ts` | Add `saveCommand` to `buildChaptersTools` return | Host command definition + handler |
+| `src/tools.ts` | Register `saveCommand` in `registerChaptersTools` | Wire into host command service |
+| `tests/unit/save-command.test.ts` | New test file | Unit tests for the save command handler |
+| `site/src/content/docs/reference/commands.md` | Already documented | No change needed |
+
+## Detailed Tasks
+
+### Task 1: Extract `runSave` in `src/continue-core.ts`
+
+Add a new exported function that performs steps 1-3 of `runContinue` (validate, render,
+write, commit) but skips step 4-5 (notice, budget, create child).
+
+```typescript
+// src/continue-core.ts — new export
+
+export interface SaveArgs {
+  callerSessionId: string
+  chapters: ChapterRange[]
+  toolResultOverrides: ToolResultOverride[]
+}
+
+export interface SaveConfig extends RenderConfig {
+  artifactStoreRoot: string
+}
+
+export interface SaveResult {
+  ok: boolean
+  chapters?: Array<{ number: number; path: string; startSeq: number; endSeq: number }>
+  warnings?: string[]
+  reason?: string
+}
+
+export async function runSave(
+  ports: Pick<ContinuePorts, 'readCallerEvents' | 'getState' | 'putState' | 'fs'>,
+  args: SaveArgs,
+  config: SaveConfig,
+): Promise<SaveResult>
+```
+
+**Implementation notes:**
+- Reuse `validateRanges`, `renderChapter`, `writeArchive`, `appendChapters` from existing imports
+- Use `attemptKey(args.callerSessionId, ceiling)` for idempotent number allocation
+- Call `ports.putState` with `appendChapters(state, wrote.records)` to commit records
+- Do NOT call `ports.createChild`, `assembleNotice`, `preflight`, or `linkChild`
+- Return `{ ok: true, chapters, warnings }` on success
+
+### Task 2: Add `saveCommand` in `src/tools.ts`
+
+Inside `buildChaptersTools`, after the `continueCommand` definition (~line 529), add:
+
+```typescript
+const saveCommand: HostCommand = {
+  name: 'chapters-save',
+  description: 'Archive completed turns into searchable chapters without creating a child session. The parent stays fully functional.',
+  input: { hint: '[title]' },
+  async handler(invocation): Promise<CommandResult> {
+    // 1. Get ports (same as deterministicCommand)
+    // 2. Read events, find anchor (last turn/end)
+    // 3. Check watermark — if nothing new, return success with "nothing to save"
+    // 4. Compose/derive ranges (same logic as deterministicCommand lines 485-494)
+    // 5. Call runSave(ports, { callerSessionId, chapters, toolResultOverrides }, config)
+    // 6. On success: trigger scheduler.schedule(cwd, 'archive:save')
+    // 7. Return success text with chapter count and seq range
+  }
+}
+```
+
+**Key differences from `deterministicCommand`:**
+- No `intent`, no `handoffNote`, no `callerPreset`, no `rulesSection`, no `projectLine`
+- No `runContinue` / `runFork` call — uses `runSave` instead
+- No child session ID in the return message
+- Simpler error handling (no Refusal/budget concerns)
+
+Update the return value of `buildChaptersTools` (line 734):
+
+```typescript
+return {
+  segment: chaptersSegment,
+  chaptersContinue, chaptersFork, chaptersSearch, chaptersArtifact, chaptersRulePropose,
+  forkCommand, continueCommand, saveCommand  // ← add saveCommand
+}
+```
+
+### Task 3: Register `saveCommand` in `registerChaptersTools`
+
+In `registerChaptersTools` (line 737), add `saveCommand` to the command registration loop:
+
+```typescript
+for (const def of [built.forkCommand, built.continueCommand, built.saveCommand]) {
+  const disposer = commands.register(def)
+  if (typeof disposer === 'function') commandDisposers.push(disposer as () => void)
+}
+```
+
+This is a one-line change to the existing loop — the disposal mechanism already handles N commands.
+
+### Task 4: Write tests in `tests/unit/save-command.test.ts`
+
+Follow the pattern from `tests/unit/fork-command.test.ts`:
+
+```typescript
+// Test cases:
+// 1. Saves completed turns into chapter files on disk
+// 2. Updates session state with chapter records
+// 3. Respects watermark — second call with no new turns returns "nothing to save"
+// 4. Returns error when no completed turn exists
+// 5. Triggers scheduler.schedule after successful save
+// 6. Does NOT create a child session (verify agents.create is never called)
+// 7. Handles title argument (optional prefix)
+```
+
+**Test infrastructure:** Same `world()` helper pattern as fork-command tests. Stub `ctx`
+with `agents.create` that throws if called (proving no child is created). Real temp-dir
+fs so chapter files materialize.
+
+### Task 5: Verify documentation
+
+`site/src/content/docs/reference/commands.md` lines 77-94 already document `/chapters-save`.
+Verify the documented behavior matches the implementation. No doc changes expected.
+
+## Dependencies Between Tasks
+
+```
+Task 1 (runSave) → Task 2 (saveCommand) → Task 3 (registration) → Task 4 (tests)
+Task 5 (docs verification) can run in parallel with Task 4
+```
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|------|-----------|
+| `runSave` duplicates logic from `runContinue` | Extract shared render+write into a private helper if duplication exceeds ~20 lines |
+| Scheduler not triggered | Mirror the exact `config.scheduler?.schedule(cwd, 'archive:save')` pattern from fork/continue |
+| Search index doesn't pick up new chapters | `commitChapters` via `appendChapters` updates the registry; search reads from registry |
+| Watermark check wrong | Use identical logic to `deterministicCommand` lines 473-480 |
+
+## Verification
+
+After implementation:
+1. `npm test` — all existing tests still pass (no regressions)
+2. `npm run build` — compiles cleanly
+3. Manual: run `/chapters-save` in a live session, verify chapter files appear in `.dsh-chapters/`
+4. Manual: run `chapters_search` from another session, verify archived content is findable
+5. Manual: run `/chapters-save` again immediately, verify "nothing to save" response

package/docs/superpowers/plans/2026-11-02-chapter-removal.md

@@ -0,0 +1,151 @@
+# Chapter Removal (`/chapters-remove`) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Operator command that actually deletes bad chapters (file, orphaned artifacts, plan docs, mirror copy) from a project store, leaving a `removed` stub so the watermark holds and no derived surface re-cites the chapter; journalled, re-derivable undo. Ships as 0.2.17.
+
+**Architecture:** Registry widening (`status: 'superseded' | 'removed'` through the one `isActiveChapter` predicate) + a pure `src/removal.ts` core (resolve → plan → journal → unlink → mutate-stub → force sync) wired into `src/commands.ts` beside `chapters-status`. Sync gains clone-side unlinking and a rehydrate guard; dangling citations are reported and logged; restore re-renders the span through the save core repair already uses.
+
+**Tech Stack:** TypeScript, zod (domain records), Node ≥ 24 test loop, host slash-command plane (`CommandResult`), git provider (`stageAllAndCommit`).
+
+**Spec:** `docs/superpowers/specs/2026-11-02-chapter-removal-design.md` — read it first; the plan argues from it.
+
+## Global Constraints
+
+- Durable log append-only (Invariant 1); registry writes only via `store.mutate(sessionId, fn)`; never put a snapshot (#59).
+- Stored paths: mint with `toStoredPath`, compare with `sameStoredPath` — never `===` (#69).
+- One predicate per semantic decision: all active-chapter filtering goes through `isActiveChapter`; no second status list may appear (#59 rule; enrich-wire.ts:195 gets swept).
+- Never commit an archive that rendered nothing (`stats.messages === 0` over `events > 0` is a refusal, before any number is spent).
+- Report caps are config rows; withheld lines are named, never silent (#117). Diagnostics and warnings must reach a human or a file (#61).
+- No model-visible prompt bytes change ⇒ no e2e corpus/tape re-record; the acceptance job's nine model-free legs must stay green untouched.
+- Commits/PR bodies through files (`git commit -F`, `--body-file`), never quoted args with backticks.
+- Version bump = `package.json` + `src/version.ts` + lock root together; `tests/unit/loudness.test.ts` pins `PLUGIN_VERSION === pkg.version`.
+- Both typechecks green: `npm run typecheck` and `npm run typecheck:client`.
+- Node ≥ 24 for test runs; on older node every suite fails misleadingly — check `node --version` first.
+
+## Review Focus
+
+(Each line gets its pinning test in the named task.)
+
+1. Shared content-addressed artifact still referenced by a surviving chapter → must NOT be deleted (Task 3).
+2. Removing the **tail** chapter → watermark still `max(endSeq)` over stubs; next auto-save archives only seqs above the removed span, never re-captures it (Task 2).
+3. Sync pass running between unlink and push → `rehydrateStoreFromMirror` does not resurrect removed names (Task 4).
+4. `find` result pool path and a registry path naming the same chapter → resolve to one record; ambiguous or cross-project ids refuse with candidates (Task 3).
+5. `apply` interrupted (journal write fails, or first unlink succeeds and a second throws) → nothing applied without a journal; partial apply is listed by bytes and named in output and journal (Task 3).
+
+---
+
+### Task 0: Issue, branch, docs commit
+
+- [ ] Issue #255 exists; branch `feature/255-chapter-removal` from latest `origin/staging`.
+- [ ] Commit the spec (this plan's source doc) + this plan file: `docs: chapter-removal design record and implementation plan (#255)` via `git commit -F`.
+
+### Task 1: Documentation FIRST
+
+**Files:**
+- Modify: `AGENTS.md` (Hard Rules: the append-only bullet gains the sanctioned removal class; What-This-Is/Storage tables stay truthful)
+- Modify: `docs/architecture.md` (integrity/storage section), `docs/knowledge-repo.md` (amendment: deletions in the transport layer + follow-up tombstone note), `docs/verify.md` (manual procedures), one new numbered site page in `site/src/content/docs/` (§29) + cross-link from the repair page; README doorway line.
+
+- [ ] Write the guidance amendment exactly as the spec's last section frames it: bad bytes leave the memory; the log stays; the stub keeps the watermark; the journal makes reversal re-derivable; removal is an operator door, not an eighth archive moment.
+- [ ] Site page documents the verbs, identifiers, what is deleted at each layer, the dangling/missing-access log, restore semantics, and the single-machine v1 bar with the multi-machine follow-up named.
+- [ ] `docs/verify.md`: rows for each acceptance criterion with the command or fixture that proves it.
+- [ ] Commit `docs: chapter-removal guidance amendment and operator manual (#255)`; check the issue's docs checkbox.
+
+### Task 2: Registry widening — one predicate
+
+**Files:**
+- Modify: `src/archive.ts` (`ChapterRecord`, ~:76), `src/registry.ts` (`isActiveChapter`, ~:213), `src/store.ts` (zod `chapterRecordSchema`), `src/enrich-wire.ts` (~:195 filter → predicate), `src/render.ts` if the stub needs a shape note.
+- Test: `tests/unit/registry.test.ts` (new rows), plus touched rows in `tests/unit/continue.test.ts` / enrichment suites.
+
+**Interfaces:**
+- Produces: `isActiveChapter(c: { status?: 'superseded' | 'removed' }): boolean` (excludes both); `ChapterRecord.status?: 'superseded' | 'removed'`; `ChapterRecord.removedAt?: string`.
+
+- [ ] **Step 1 (failing tests):** (a) zod round-trips a record with `status:'removed'` + `removedAt`; (b) `buildIndex`/`collectEntries` exclude a `removed` stub and keep `superseded` excluded; (c) watermark math over `[{endSeq:50,status:'removed'}]` yields 50 — assert at the three reduce sites' shared helper or via a small pure function `archiveWatermark(records)` (already exists in continue-core.ts:447 — reuse; extend it, do not duplicate); (d) enrichment candidate scan excludes `removed` (replaces the inline string compare at enrich-wire.ts:195).
+- [ ] **Step 2:** run, watch fail.
+- [ ] **Step 3:** implement the widening; sweep `enrich-wire.ts:195` to `isActiveChapter`; add `status` to zod as `z.enum(['superseded', 'removed']).optional()` and `removedAt` as `z.string().datetime().optional()` (Optional-with-default precedent: old rows parse unchanged).
+- [ ] **Step 4:** run green; `npm run typecheck`.
+- [ ] **Step 5:** commit `feat: registry status 'removed' behind the one active-chapter predicate (#255)`.
+
+### Task 3: Removal core — `src/removal.ts`
+
+**Files:**
+- Create: `src/removal.ts`; Test: `tests/unit/removal.test.ts` (+ fixture helpers copied from repair test patterns).
+
+**Interfaces (produced for Tasks 4–7):**
+```ts
+export interface RemovalPorts { fs: () => FsLike; store: RegistryStore; storeRoot: string; cwd: string; now: () => string }
+export type RemovalId = { sessionId: string; number: number }
+export function resolveRemovalId(raw: string, rows: Iterable<[string, SessionState]>, cwd: string): { sessionId: string; record: ChapterRecord } | { refusal: string }
+export function planRemoval(plan: { target: { sessionId: string; record: ChapterRecord }[]; rows: Iterable<[string, SessionState]>; fs: ...; storeRoot: string; cwd: string }): { removals: RemovalEntry[]; dangling: DanglingRef[]; refused: string[] }
+export function applyRemoval(ports: RemovalPorts, plan: ReturnType<typeof planRemoval>): Promise<{ journalId: string; removed: string[]; problems: string[] }>
+export function scanDangling(fs, roots: string[], needles: string[]): DanglingRef[]
+export function appendMissingAccess(storeRoot: string, lines: string[]): void
+```
+
+- [ ] **Step 1 (failing unit tests)** — names and assertions:
+  - `resolveRemovalId accepts registry path / pool path / "<sessionId>:<number>" / bare number against the display index`
+  - `resolveRemovalId refuses unknown id naming near candidates` ; `refuses ambiguous pool path hitting two sessions` ; `refuses a path under a different store root (cross-project)`
+  - `planRemoval keeps an artifact blob still named by an ACTIVE record; deletes one named only by removed/none` (two records sharing sha, one active)
+  - `planRemoval includes planDocs + plan artifactPath files in the deletion set`
+  - `planRemoval dangling scan reports a surviving chapter whose body cites "007-evil.md"`
+  - `applyRemoval writes the journal BEFORE the first unlink (throw on journal write ⇒ zero unlinks, record unmutated)`
+  - `applyRemoval partial failure lists what went and journals it (second unlink throws)`
+  - `applyRemoval mutates through store.mutate and leaves a stub: number/startSeq/endSeq/path/sha256/artifacts kept, status 'removed', removedAt set`
+- [ ] **Step 2:** run to fail.
+- [ ] **Step 3:** implement. Notes for choices the tests don't fix: journal lives at `<storeRoot>/<rootSession>/removals/<journalId>.json` with the `repair-run.ts:196-247` write-ahead pattern (same `journalId` format); needles for the dangling scan = removed filename basename + registry path (match via `sameStoredPath` for path arms, substring for body-citation arms); store-root scoping = `resolveStoreRoot`-adjacent path prefix check.
+- [ ] **Step 4:** green; commit `feat: removal core — resolve/plan/journal/apply with orphan-artifact math (#255)`.
+
+### Task 4: Sync correctness
+
+**Files:**
+- Modify: `src/sync.ts` (`rehydrateStoreFromMirror` ~:488 + its caller in `runSync`; possibly a `removedNames` set threaded from registry rows read by the sync pass), `src/removal.ts` (clone-side unlink in `applyRemoval` behind a `cloneDir?: string` port; force-sync trigger).
+- Test: `tests/integration/sync.test.ts` new rows + `tests/unit/removal.test.ts` clone-arm rows.
+
+- [ ] **Step 1 (failing):** (a) given a mirror clone containing `chapters/<key>/<s>/007-x.md` and a store stub naming it removed, `rehydrateStoreFromMirror` restores zero files; (b) after clone unlink, `buildIndexInClone` output no longer contains the removed entry; (c) stale topic shard cleanup on the `changed=true` branch (read the current behavior first — if shards for vanished topics already get removed, pin it with a test instead of writing code).
+- [ ] **Step 2:** run to fail.
+- [ ] **Step 3:** implement guard + unlink arms; keep the copy-only invariant of `publishIntoClone` (deletions are done by the removal, not the publisher — the doc comment in sync.ts must say so).
+- [ ] **Step 4:** green (integration sync suites on Node ≥ 24 — check `node --version`); commit `feat: deletions publish to the pool and the mirror never rehydrates them (#255)`.
+
+### Task 5: Missing-access log
+
+**Files:**
+- Modify: `src/removal.ts` (apply writes dangling lines to `<storeRoot>/removals/missing-access.log`), `src/continue-core.ts`/`src/prompt.ts` where `verifyChapter` mints `"<path>: missing since archived"` — emit a structured dead-citation line there too (grep both call sites; the delivery must not depend on the caller reading `warnings`).
+- Test: `tests/unit/removal.test.ts` append rows + `tests/integration/` TOC-build row.
+
+- [ ] **Step 1 (failing):** `removal appends dangling report lines "ts | removed=<path> | referrer=<path> | how=cited-in-body"` ; `collectEntries marks a chapter missing and appends a dead-citation line naming the citing session`.
+- [ ] **Step 2:** run to fail. **Step 3:** implement; confirm the #61 diagnostics sink already receives the warning text (it does for doors — verify, don't assume). **Step 4:** green; commit `feat: missing-access log for removed-chapter citations (#255)`.
+
+### Task 6: `/chapters-remove` command wiring
+
+**Files:**
+- Modify: `src/commands.ts` (new command object; shape = `statusCommand` :271-…), `src/index.ts` (registration + config plumbing; report cap row e.g. `removalReportMaxLines` defaulting to `repairReportMaxLines`'s value), `src/diag.ts` if a status line helper is wanted.
+- Test: `tests/integration/commands-removal.test.ts` (fixture store: 3 sessions, 5 chapters, one linked project with a throwaway loopback remote; port-keyed temp homes per rig rules).
+
+- [ ] **Step 1 (failing integration):** verbs — `list` prints flat ancestor index with canonical ids + statuses; `find` returns pool-scoped hits; `dry-run` prints deletion set + dangling report + `NOTHING WRITTEN`; `apply` journals and reports counts; `report` tails the log with the cap and withheld count named; unknown verb/args refuse without touching state; no-session/no-cwd invocation refuses cleanly.
+- [ ] **Step 2–4:** implement the handler against the core; green; commit `feat: /chapters-remove operator command (#255)`.
+- [ ] `/chapters-status` addition (one line, printed in EVERY state incl. unlinked): `Removals (this project): N removed stub(s); missing-access log: <path or 'empty'>`. Test it renders in the unlinked case.
+
+### Task 7: Restore = re-derivation
+
+**Files:**
+- Modify: `src/removal.ts` (`restoreRemoval(ports, journalId)`), reuse the explicit-span seam `src/save-core.ts` exposes to repair (`spanOverride`, see save-core ~:70/:189 and `repair-run.ts` usage).
+- Test: `tests/integration/removal-restore.test.ts` with a synthetic durable log (deterministic bulk per rig rules — no model).
+
+- [ ] **Step 1 (failing):** `restore re-renders the journaled span at a NEW number, chapter bytes sha-match the journal's recorded sha256`; `restore of a span whose render yields zero messages refuses, stub untouched`; `restore is journaled (second journal entry, or appended to the same file)`; `restore after supersede-by-repair of the same span refuses and says why`.
+- [ ] **Step 2–4:** implement, green; commit `feat: /chapters-remove restore re-derives a removed chapter from the durable log (#255)`.
+
+### Task 8: Full deterministic verification — run ONCE
+
+- [ ] Confirm `node --version` ≥ 24 (if not, find the pinned runtime — the local-llm/dev-platform docs name the rig; do not trust red suites on 22.x).
+- [ ] `npm run typecheck && npm run typecheck:client && npm test` — all green.
+- [ ] `git diff origin/staging -- tests/e2e` shows **no** changes to model-visible prompts/tool descriptions ⇒ no re-record; the CI acceptance job must run its nine model-free legs untouched as proof.
+- [ ] `node scripts/check-env-parity.mjs` — note drift for the maintainer's install step (do not force the live home).
+
+### Task 9: PR → staging → RC (stop at the maintainer's gate)
+
+- [ ] `git fetch origin staging && git merge origin/staging` into the branch; resolve; push.
+- [ ] Check every acceptance box in #255 with evidence (test names / CI run ids); post the final progress comment.
+- [ ] PR to `staging` per template via `--body-file`, title `feat: /chapters-remove — spot-delete contaminated chapters (#255)`, `Closes #255`.
+- [ ] CI green ⇒ squash-merge to staging (agents may).
+- [ ] Bump `0.2.17` (three files together) `chore: release 0.2.17 — /chapters-remove (#255)`; open RC PR `staging → main` (`Release candidate: 0.2.17`, `Changes since 0.2.16`).
+- [ ] **Do not merge or tag.** File the cross-machine-tombstone follow-up issue; link it in the RC body and the design doc. Hand the maintainer: parity script output + a note that BOTH of their harnesses need a restart to load the new copy.

package/docs/superpowers/specs/2026-11-02-chapter-removal-design.md

@@ -0,0 +1,115 @@
+# Chapter Removal — design record (issue #255)
+
+Date: 2026-11-02. Decided with the maintainer across three brainstorming rounds in the session
+that archived this design; approved plan at `docs/superpowers/plans/2026-11-02-chapter-removal.md`.
+
+## Intent and the why
+
+Operators mistype prompts meant for another project into a project session. When that session
+archives, the contaminated turns become chapters that flow through every derived surface from that
+point on — TOCs, index shards, search, enrichment. The maintainer asked for the ability to see the
+active chapters of a session and **spot-delete** the bad ones, removing the chapter *everywhere it
+matters*: file, metadata, artifacts, and references.
+
+The bar the maintainer set, in their words: removal must be *actual* — "I want the bad chapters
+actually removed" — and the project guidance must accept that **removal can be good when the data
+is bad**. What matters is the generated TOCs from that point on; git history of the pool and other
+chapters that happen to cite the removed file are acceptable residue. An open question the
+maintainer raised themselves: a log of missing-chapter access from other chapters, so they can
+decide whether those referrers need to stay too.
+
+## Goals
+
+1. `/chapters-remove` — operator-only command: `list` (active TOC view with canonical ids),
+   `find <query>` (project pool-mirror search), `[dry-run] <ids…>`, `apply <ids…>`, `report`,
+   `restore <journalId>`.
+2. `apply` deletes the chapter file, its **orphaned** artifacts and plan docs, from the store AND
+   the pool mirror clone (so the deletion publishes and the derived index regenerates clean), and
+   flips the registry record to a `status: 'removed'` stub.
+3. No TOC, search result, or enrichment pass cites a removed chapter from that moment on —
+   through the ONE predicate `isActiveChapter` (no second filter lists).
+4. The archive watermark never rewinds: a removed chapter's span is never silently re-captured
+   by an auto-archive moment.
+5. Every removal is journaled; `restore` re-derives the chapter from the durable log through the
+   same save core (a NEW number — identity is `(number, sha256)`).
+6. Dangling citations of removed chapters are reported at removal time and logged thereafter
+   (`removals/missing-access.log`), per the #61 rule that a detected failure is a delivered one.
+
+## Non-goals
+
+- Not a model-facing tool. The human made the mistake; the human pulls the trigger. This also
+  keeps every model-visible prompt byte unchanged — no corpus/tape re-record (rig rule).
+- Not scrubbing git history, already-seeded child-session TOCs, or other projects' stores.
+  Invariant 1 (append-only durable log) is never bent.
+- Not cross-machine tombstones: v1 guarantees correctness on the removing machine and on clones
+  pulled after the deletion commit. A second machine holding a local copy can re-publish it; the
+  follow-up is a removal fact carried in the per-session collections JSONL (which already syncs),
+  consumed by `planStoreToRepo`. Filed as follow-up at PR time.
+
+## Anti-goals (what would make this a failure)
+
+- A removed chapter reappearing — via watermark rewind (re-archived span), via mirror rehydration,
+  or via a stale put resurrecting the record. Each has a named test.
+- Deleting bytes that a *surviving* chapter still references (shared content-addressed blobs).
+- A destructive apply that cannot be explained or reversed: no journal written before the first
+  unlink ⇒ refuse.
+
+## Constraints (from AGENTS.md, load-bearing)
+
+- Append-only durable log; registry mutation only through `store.mutate(sessionId, fn)`.
+- Stored paths are one dialect: `sameStoredPath(a, b, cwd)`, never `===` (#69).
+- One predicate per semantic decision (#59) — this feature extends `isActiveChapter`, it must not
+  fork it; the hand-rolled `!== 'superseded'` in `src/enrich-wire.ts:195` is swept into the
+  predicate as part of this change.
+- Never bound reports loosely: caps are config rows, withheld counts are named (#117/#61).
+- Three schema systems, never mixed: zod for domain records (`ChapterRecord`), plain specs for
+  tool params, Schemastery for `Config`.
+- Version bumps touch `package.json`, `src/version.ts`, and the lock root together
+  (`loudness.test.ts` pins it); commit/PR bodies via files, never quoted args.
+
+## The mechanics, as decided
+
+**Why the stub survives deletion.** The watermark is `max(chapter.endSeq)` over all records in the
+author session's row (`src/save-core.ts:187`, `src/tools.ts:559`, `src/continue-core.ts:279`).
+Deleting the record outright rewinds the watermark and the next archive moment re-captures the
+poisoned span — the exact failure the feature exists to prevent. So the record keeps `number`,
+`startSeq`/`endSeq`, `path`, `sha256`, the artifact manifest (for orphan forensics and restore
+re-counting), title, plus `status: 'removed'` and `removedAt`. The *bytes* are gone; the *span book
+keeping* is not. `nextChapterNumber` never rewinds: numbers are never re-spent.
+
+**Orphan math.** Artifacts are content-addressed and deduplicated across the subtree, so a blob is
+deleted only when no *active* record in any session tree under the project's store root names it
+(chapter `artifacts`, `plans[].artifactPath`, `planDocs[]`). `removed` stubs do not hold blobs
+open — their references are exactly what the operator judged bad.
+
+**Publish + rehydrate.** `publishIntoClone` only copies new files; a store-side deletion never
+reaches the pool by itself, so `apply` unlinks the clone-relative paths directly and forces a sync
+pass, letting `stageAllAndCommit` record `git rm` deletions. Independently,
+`rehydrateStoreFromMirror` (which copies *absent* files back) gains a guard: names belonging to
+`removed` stubs are never restored — closing the window between unlink and push, and protecting a
+future `git checkout` of an old pool commit.
+
+**Identifiers.** Canonical id is the registry `path` (workspace-relative, the #69 dialect).
+`find` results (`chapters/<projectKey>/<session>/<file>` pool dialect) map through the
+`<session>/<file>` tail; a TOC display ordinal from `list` is accepted alongside `list` output but
+re-checked against the flat index at apply time. Unknown/ambiguous ids refuse with near candidates;
+an id resolving outside this project's store root refuses outright.
+
+**Dangling / missing-access.** At removal, scan every active chapter file (store and clone) plus
+registry `plans` titles for citations of the removed filename; report + append to
+`<store-root>/removals/missing-access.log`. Ongoing: where `collectEntries` mints
+`"<path>: missing since archived"` warnings, also append a structured dead-citation line. The
+report verb reads the log tail with the same cap discipline as repair reports.
+
+**Restore.** Re-render the journaled span through the same save-core path repair already uses for
+explicit-span re-derivation, commit as a NEW chapter number, flip the stub's tombstone into the
+new record's lineage (`repairs: <n>`-style provenance), and journal the restore. A restore whose
+render yields zero messages is refused (never-commit-an-empty-archive rule), not faked.
+
+## Guidance amendment (docs-first deliverable)
+
+AGENTS.md's Hard Rule currently says the store is append-only "with no exceptions" and damage is
+"superseded, not repaired in place". It gains the sanctioned operator class beside #60 repair:
+**removal of bad data** — bytes leave the store, the log stays, the stub keeps the watermark, and
+the journal makes reversal re-derivable. The seven archive moments are untouched: removal is an
+operator door, not a moment.