Topic resolution & incorporation — 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: Implement sub-project #4 of the collaborative-annotations initiative: the Resolve flow that turns an open Topic into either an Incorporated Source commit or a Discarded Topic, with an in-process Agent producing diffed Source rewrites for human review.

Architecture: Three layers on the existing #1–#3 substrate. (a) Slim the wb-agent CLI surface and the agent prompt to match a single consumer (the skill). (b) Add agent_job_id on proposals (migration 004), a freshness helper that catches both base-SHA drift and missing topic markers, and a transactional re-anchor step inside collab.CompleteIncorporation. (c) Ship seven HTTP endpoints (propose, list proposals, diff, preview render, approve, discard, plus the existing job-status endpoint) behind collaborator auth.

Tech Stack: Go 1.26, SQLite (modernc.org/sqlite), goldmark renderer, hexops/gotextdiff for unified diff, existing internal/{agent,auth,collab,render,server} packages. Tests use testing + internal/agent.FakeRunner + internal/collab in-memory stores.

Spec & decisions

• Spec: docs/superpowers/specs/2026-05-13-topic-resolution-incorporation-design.html
• Decisions: docs/superpowers/specs/2026-05-10-collaborative-annotations-decisions.md (the "Sub-project #4" section is the relevant one)
• Domain model: docs/superpowers/specs/2026-05-10-collaborative-annotations-domain-model.html

Read both before starting any task. Every task assumes the spec is the source of truth — if a step here diverges, the spec wins.

File structure

New files:

Modified files:

Conventions

• Commits: small, one logical change each. The commit-message style for this repo is wiki-browser: <area> — <imperative summary>. No Co-Authored-By trailer.
• Tests: Go's testing package. Each task that touches Go code lands with new or updated tests. Run only the package(s) you touched with go test ./internal/<pkg>/... or go test ./cmd/wb-agent/...; the full suite runs in CI.
• Linting / formatting: gofmt -w before committing. go vet ./... should pass.
• Database: the collab DB schema is forward-only. Migration 004 is the only schema change in this plan.
• Router: the server uses Go 1.22+ http.ServeMux with path-pattern variables. Pull params with r.PathValue("id"). See internal/server/topics.go and internal/server/agent_jobs.go for examples. Don't import gorilla/mux or chi.
• HTTP error handling: mirror the existing pattern in internal/server/topics.go. writeJSONError(w, http.StatusXxx, "<code>") for application errors; writeJSON(w, http.StatusXxx, body) for success/conflict bodies. Where the plan shows /* 500 */ or similar comments inside handler code blocks, write the corresponding writeJSONError(...) call with a descriptive error code following neighbouring handlers' style.
• Deps struct extension: reuse the current fields where possible: Root is the repo root, Cache is the live render cache, and AgentService is already the server-facing interface for the agent runtime. Do not add a parallel Agent, Renderer, or RepoRoot field. Approval handlers read the git author identity through d.AgentService.AuthorIdentity().
• CSRF middleware: all POST handlers added in Phase 4 must sit behind the existing auth.RequireCollaborator and CSRF middleware that #7 already wired for POST /api/topics. Mirror that route's registration in server.go.
• Auth principal: use auth.PrincipalFrom(r.Context()) — see internal/auth/principal.go. The principal carries UserID (normalised email) and DisplayName.

Phase 1 — Schema + collab additions

Task 1: Migration 004 — incorporation_proposals.agent_job_id

Files:

• Create: internal/collab/migrations/004_proposal_job_id.sql

• Modify: internal/collab/migrate_test.go (add a test that 004 applies cleanly and the new column accepts inserts)

• Step 1: Write the failing test

In internal/collab/migrate_test.go, append:

func TestMigration004_AddsAgentJobID(t *testing.T) {
	store := newTestStore(t)

	// Insert a job + a topic so the FK has a target.
	mustExec(t, store, `INSERT INTO users(id, display_name, created_at)
		VALUES ('u1', 'u1', unixepoch())`)
	mustExec(t, store, `INSERT INTO topics(id, source_path, anchor, created_by, created_at, updated_at)
		VALUES ('t1', 'docs/x.md', '{"kind":"global"}', 'u1', unixepoch(), unixepoch())`)
	mustExec(t, store, `INSERT INTO agent_jobs(id, kind, source_path, topic_id, status, created_at)
		VALUES ('j1', 'incorporate', 'docs/x.md', 't1', 'succeeded', unixepoch())`)

	// Insert a proposal with agent_job_id set.
	mustExec(t, store, `INSERT INTO incorporation_proposals(
		id, topic_id, revision_number, proposed_source, base_source_sha,
		proposed_by, agent_job_id, created_at)
		VALUES ('p1', 't1', 1, 'x', 'sha', NULL, 'j1', unixepoch())`)

	// Insert a legacy NULL row to confirm the column is nullable.
	mustExec(t, store, `INSERT INTO incorporation_proposals(
		id, topic_id, revision_number, proposed_source, base_source_sha,
		proposed_by, agent_job_id, created_at)
		VALUES ('p2', 't1', 2, 'x', 'sha', NULL, NULL, unixepoch())`)

	// Bad FK should fail.
	_, err := store.RawDB().Exec(`INSERT INTO incorporation_proposals(
		id, topic_id, revision_number, proposed_source, base_source_sha,
		proposed_by, agent_job_id, created_at)
		VALUES ('p3', 't1', 3, 'x', 'sha', NULL, 'no-such-job', unixepoch())`)
	if err == nil {
		t.Fatal("expected FK violation, got nil")
	}
}

// mustExec — add this helper next to other test helpers if not present.
func mustExec(t *testing.T, store *Store, sql string, args ...any) {
	t.Helper()
	if _, err := store.RawDB().Exec(sql, args...); err != nil {
		t.Fatalf("exec %q: %v", sql, err)
	}
}

• Step 2: Run the test and confirm it fails

go test ./internal/collab/ -run TestMigration004_AddsAgentJobID -v

Expected: FAIL — column does not exist.

• Step 3: Write the migration

Create internal/collab/migrations/004_proposal_job_id.sql:

ALTER TABLE incorporation_proposals
  ADD COLUMN agent_job_id TEXT
  REFERENCES agent_jobs(id);

CREATE INDEX incorporation_proposals_agent_job
  ON incorporation_proposals(agent_job_id);

No -- migrate:no-tx directive — this is a plain ALTER TABLE ADD COLUMN, which SQLite allows inside the standard migration transaction.

• Step 4: Re-run the test

go test ./internal/collab/ -run TestMigration004_AddsAgentJobID -v

Expected: PASS.

• Step 5: Run the full collab test suite

go test ./internal/collab/...

Expected: PASS. Look out for migration-runner tests that count migrations; bump them if needed.

• Step 6: Commit

git add internal/collab/migrations/004_proposal_job_id.sql internal/collab/migrate_test.go
git commit -m "wiki-browser: collab — migration 004 adds incorporation_proposals.agent_job_id"

Task 1b: Migration 005 — per-topic inflight for incorporate jobs

The spec says "Jobs for different Topics on the same Source are allowed to queue; the per-Source agent queue serializes them" (HTTP surface, POST /api/topics/{id}/proposals row). The current #3 implementation has a partial unique index agent_jobs_one_inflight_source (in migration 003) and an in-memory map keyed on source_path inside agent.Service.Submit, both of which reject the same-Source-different-Topic enqueue the spec wants. Migration 005 + a small agent.Service change fixes this without touching perspective-job behaviour materially.

Files:

• Create: internal/collab/migrations/005_inflight_keys.sql

• Modify: internal/collab/reader.go (replace HasInflightForSource with kind-specific helpers)

• Modify: internal/agent/service.go (per-topic key for incorporate, per-(source, persona) for perspective)

• Modify: internal/agent/service_test.go

• Step 1: Write the failing test

In internal/agent/service_test.go, add:

func TestSubmit_AllowsDifferentTopicsOnSameSource(t *testing.T) {
	svc, store := newTestServiceWithBlockingRunner(t)
	createTopic(t, store, "t1", "docs/x.md")
	createTopic(t, store, "t2", "docs/x.md")

	id1, err := svc.Submit(SubmitInput{Kind: "incorporate", SourcePath: "docs/x.md", TopicID: "t1"})
	if err != nil {
		t.Fatalf("first submit: %v", err)
	}
	id2, err := svc.Submit(SubmitInput{Kind: "incorporate", SourcePath: "docs/x.md", TopicID: "t2"})
	if err != nil {
		t.Fatalf("second submit (different topic, same source): %v", err)
	}
	if id1 == id2 {
		t.Fatalf("expected distinct job ids")
	}
}

func TestSubmit_RejectsSameTopicInflight(t *testing.T) {
	svc, store := newTestServiceWithBlockingRunner(t)
	createTopic(t, store, "t1", "docs/x.md")
	if _, err := svc.Submit(SubmitInput{Kind: "incorporate", SourcePath: "docs/x.md", TopicID: "t1"}); err != nil {
		t.Fatal(err)
	}
	if _, err := svc.Submit(SubmitInput{Kind: "incorporate", SourcePath: "docs/x.md", TopicID: "t1"}); !errors.Is(err, ErrInflight) {
		t.Fatalf("expected ErrInflight, got %v", err)
	}
}

newTestServiceWithBlockingRunner is a helper variant (build it from the existing newTestService shape in service_test.go) that uses a BlockingRunner so the first job stays in flight while the second Submit call runs.

• Step 2: Run, confirm failure

go test ./internal/agent/ -run TestSubmit_AllowsDifferentTopicsOnSameSource -v

Expected: FAIL — ErrInflight returned for the second submit on a different topic.

• Step 3: Write the migration

Create internal/collab/migrations/005_inflight_keys.sql:

DROP INDEX IF EXISTS agent_jobs_one_inflight_source;

CREATE UNIQUE INDEX IF NOT EXISTS agent_jobs_one_inflight_incorporate_topic
  ON agent_jobs(topic_id)
  WHERE kind = 'incorporate'
    AND status IN ('queued','running');

CREATE UNIQUE INDEX IF NOT EXISTS agent_jobs_one_inflight_perspective_source
  ON agent_jobs(source_path, persona_name)
  WHERE kind = 'perspective'
    AND status IN ('queued','running');

• Step 4: Update collab.reader.go inflight helpers

Replace HasInflightForSource with two kind-specific helpers:

// HasInflightIncorporateForTopic reports whether a queued/running
// incorporate job exists for topicID.
func (s *Store) HasInflightIncorporateForTopic(topicID string) (bool, error) {
	var one int
	err := s.db.QueryRow(
		`SELECT 1 FROM agent_jobs
		  WHERE kind = 'incorporate'
		    AND topic_id = ?
		    AND status IN ('queued','running')
		  LIMIT 1`, topicID,
	).Scan(&one)
	if err == sql.ErrNoRows {
		return false, nil
	}
	if err != nil {
		return false, err
	}
	return true, nil
}

// HasInflightPerspectiveForSourcePersona reports whether a queued/running
// perspective job exists for the given (source_path, persona_name).
func (s *Store) HasInflightPerspectiveForSourcePersona(sourcePath, persona string) (bool, error) {
	var one int
	err := s.db.QueryRow(
		`SELECT 1 FROM agent_jobs
		  WHERE kind = 'perspective'
		    AND source_path = ?
		    AND persona_name = ?
		    AND status IN ('queued','running')
		  LIMIT 1`, sourcePath, persona,
	).Scan(&one)
	if err == sql.ErrNoRows {
		return false, nil
	}
	if err != nil {
		return false, err
	}
	return true, nil
}

Delete the old HasInflightForSource. grep for callers — there's at least one in internal/agent/service.go — and update each.

• Step 5: Update agent.Service.Submit

Rewrite the inflight section of Submit (currently lines ~106–145) to use a kind-keyed map and the new helpers:

	key := inflightKey(in)

	s.mu.Lock()
	if _, ok := s.inflight[key]; ok {
		s.mu.Unlock()
		return "", ErrInflight
	}
	jobID := uuid.NewString()
	s.inflight[key] = struct{}{}
	s.mu.Unlock()

	if inflight, err := s.checkPersistedInflight(in); err != nil {
		s.releaseInflight(key)
		return "", fmt.Errorf("agent.Service: persisted inflight check: %w", err)
	} else if inflight {
		s.releaseInflight(key)
		return "", ErrInflight
	}

	// ... existing InsertJob block unchanged. In its error branch, replace
	// the HasInflightForSource() call with checkPersistedInflight(in), and
	// the delete(s.inflight, in.SourcePath) call with releaseInflight(key).

Helpers (add at the bottom of service.go):

func inflightKey(in SubmitInput) string {
	switch in.Kind {
	case "incorporate":
		return "incorporate:" + in.TopicID
	case "perspective":
		return "perspective:" + in.SourcePath + ":" + in.PersonaName
	}
	return in.Kind + ":" + in.SourcePath
}

func (s *Service) checkPersistedInflight(in SubmitInput) (bool, error) {
	switch in.Kind {
	case "incorporate":
		return s.cfg.Store.HasInflightIncorporateForTopic(in.TopicID)
	case "perspective":
		return s.cfg.Store.HasInflightPerspectiveForSourcePersona(in.SourcePath, in.PersonaName)
	}
	return false, nil
}

func (s *Service) releaseInflight(key string) {
	s.mu.Lock()
	delete(s.inflight, key)
	s.mu.Unlock()
}

Also update the post-run release path (wherever delete(s.inflight, in.SourcePath) is called when a job finishes) to use inflightKey(in).

The per-Source execution-serialisation queue (max_concurrent_jobs=1 per source) stays unchanged: the inflight gate prevents same-Topic duplication; the execution queue prevents two Source rewrites racing each other.

• Step 6: Re-run tests

go test ./internal/collab/... ./internal/agent/...

Expected: PASS. Existing service_test.go tests that asserted same-source rejection of different topics encoded the old behaviour — update or delete them.

• Step 7: Commit

git add internal/collab/migrations/005_inflight_keys.sql internal/collab/reader.go internal/agent/service.go internal/agent/service_test.go
git commit -m "wiki-browser: collab+agent — migration 005, per-topic inflight for incorporate jobs"

Task 2: collab.NewProposal.AgentJobID + InsertProposal writes it; extend Proposal struct + GetProposal

The proposal type Proposal and the GetProposal reader (both in mutators.go) don't currently carry agent_job_id. Several later tasks read it back (Tasks 10, 14, 17), so this task also lifts the field into the Go type and adds a job-keyed lookup the invariant check uses.

Files:

• Modify: internal/collab/mutators.go (NewProposal, InsertProposal, Proposal, GetProposal)

• Modify: internal/collab/reader.go (GetProposalByJobID)

• Modify: internal/collab/mutators_test.go

• Step 1: Write the failing test

In internal/collab/mutators_test.go, append:

func TestInsertProposal_WritesAgentJobID(t *testing.T) {
	store, _ := setupStoreWithTopic(t) // existing helper; if not, see neighbours
	jobID := "job-1"
	mustExec(t, store, `INSERT INTO agent_jobs(id, kind, source_path, topic_id, status, created_at)
		VALUES (?, 'incorporate', 'docs/x.md', ?, 'running', unixepoch())`,
		jobID, "t1") // replace with the topic ID setupStoreWithTopic created

	_, err := store.InsertProposal(NewProposal{
		ID: "p1", TopicID: "t1", RevisionNumber: 1,
		ProposedSource: "hello", BaseSourceSHA: "abcd",
		ProposedBy:  nil,
		AgentJobID: &jobID,
	})
	if err != nil {
		t.Fatalf("InsertProposal: %v", err)
	}

	var got sql.NullString
	if err := store.RawDB().QueryRow(
		`SELECT agent_job_id FROM incorporation_proposals WHERE id = 'p1'`,
	).Scan(&got); err != nil {
		t.Fatalf("scan: %v", err)
	}
	if !got.Valid || got.String != jobID {
		t.Fatalf("agent_job_id: got %#v, want %q", got, jobID)
	}
}

If setupStoreWithTopic doesn't exist with that exact name, adapt to whatever the file uses to seed a Topic.

• Step 2: Run the test and confirm it fails

go test ./internal/collab/ -run TestInsertProposal_WritesAgentJobID -v

Expected: FAIL — NewProposal has no AgentJobID field.

• Step 3: Extend the struct and the insert

In internal/collab/mutators.go, modify NewProposal:

type NewProposal struct {
	ID             string
	TopicID        string
	RevisionNumber int
	ProposedSource string
	BaseSourceSHA  string
	ProposedBy     *string // nil = Agent-authored
	AgentJobID     *string // set by wb-agent insert-proposal; nil for legacy/manual rows
}

And update InsertProposal:

func (s *Store) InsertProposal(p NewProposal) (string, error) {
	if p.ID == "" || p.TopicID == "" || p.RevisionNumber < 1 ||
		p.BaseSourceSHA == "" {
		return "", fmt.Errorf("collab.InsertProposal: required fields missing")
	}
	err := s.send(func(db *sql.DB) error {
		_, err := db.Exec(
			`INSERT INTO incorporation_proposals(
			   id, topic_id, revision_number, proposed_source,
			   base_source_sha, proposed_by, agent_job_id, created_at
			 ) VALUES (?, ?, ?, ?, ?, ?, ?, unixepoch())`,
			p.ID, p.TopicID, p.RevisionNumber, p.ProposedSource,
			p.BaseSourceSHA, p.ProposedBy, p.AgentJobID,
		)
		return err
	})
	if err != nil {
		return "", err
	}
	return p.ID, nil
}

Also extend the read shape:

type Proposal struct {
	ID             string
	TopicID        string
	RevisionNumber int
	ProposedSource string
	BaseSourceSHA  string
	AgentJobID     sql.NullString // nil for legacy / non-Agent rows
	CreatedAt      int64
}

func (s *Store) GetProposal(id string) (Proposal, error) {
	var p Proposal
	err := s.db.QueryRow(
		`SELECT id, topic_id, revision_number, proposed_source,
		        base_source_sha, agent_job_id, created_at
		   FROM incorporation_proposals WHERE id = ?`,
		id,
	).Scan(&p.ID, &p.TopicID, &p.RevisionNumber, &p.ProposedSource,
		&p.BaseSourceSHA, &p.AgentJobID, &p.CreatedAt)
	return p, err
}

If CreatedAt wasn't on the old struct, that's fine — adding it is needed by Task 14's list view.

In internal/collab/reader.go, add:

// GetProposalByJobID returns the proposal row inserted by an Agent job, or
// sql.ErrNoRows if none. Used by the post-job invariant check.
func (s *Store) GetProposalByJobID(jobID string) (Proposal, error) {
	var p Proposal
	err := s.db.QueryRow(
		`SELECT id, topic_id, revision_number, proposed_source,
		        base_source_sha, agent_job_id, created_at
		   FROM incorporation_proposals WHERE agent_job_id = ?`,
		jobID,
	).Scan(&p.ID, &p.TopicID, &p.RevisionNumber, &p.ProposedSource,
		&p.BaseSourceSHA, &p.AgentJobID, &p.CreatedAt)
	return p, err
}

(If the schema permits multiple Agent proposals to share one job — it shouldn't, since each job ships at most one proposal — change the query to ORDER BY revision_number DESC LIMIT 1 as a defence in depth.)

• Step 4: Re-run tests

go test ./internal/collab/...

Expected: PASS.

• Step 5: Commit

git add internal/collab/mutators.go internal/collab/reader.go internal/collab/mutators_test.go
git commit -m "wiki-browser: collab — agent_job_id on Proposal struct, InsertProposal, GetProposal, GetProposalByJobID"

Task 3: collab.ProposalFreshness helper

The freshness helper is the single source of truth for whether a proposal is approvable. Used by both the proposals-list endpoint (advisory stale_reasons) and the approval endpoint (gating).

Files:

• Create: internal/collab/freshness.go

• Create: internal/collab/freshness_test.go

• Step 1: Write the failing test

Create internal/collab/freshness_test.go:

package collab

import (
	"reflect"
	"sort"
	"testing"
)

func TestProposalFreshness_Fresh(t *testing.T) {
	store, repoRoot := setupStoreWithSourceFile(t, "docs/x.md", "hello world")
	jobID, topicID := "j1", "t1"
	seedJobTopicProposal(t, store, jobID, topicID, "docs/x.md",
		/*baseSHA=*/ blobSHA(t, "hello world"),
		/*proposed=*/ `<span data-orcha-anchor="t2">x</span>`,
		/*agentJobStatus=*/ "succeeded")
	mustInsertOpenTopic(t, store, "t2", "docs/x.md")

	res, err := ProposalFreshness(store, repoRoot, "p1")
	if err != nil {
		t.Fatalf("ProposalFreshness: %v", err)
	}
	if !res.Fresh {
		t.Fatalf("expected Fresh=true, got %+v", res)
	}
	if len(res.StaleReasons) != 0 {
		t.Fatalf("expected no stale_reasons, got %v", res.StaleReasons)
	}
}

func TestProposalFreshness_StaleBaseSourceSHA(t *testing.T) {
	store, repoRoot := setupStoreWithSourceFile(t, "docs/x.md", "DIFFERENT now")
	seedJobTopicProposal(t, store, "j1", "t1", "docs/x.md",
		/*baseSHA stored on proposal=*/ "deadbeef",
		"", "succeeded")

	res, err := ProposalFreshness(store, repoRoot, "p1")
	if err != nil {
		t.Fatalf("ProposalFreshness: %v", err)
	}
	if res.Fresh {
		t.Fatalf("expected Fresh=false")
	}
	if !containsString(res.StaleReasons, "source_sha") {
		t.Fatalf("expected source_sha reason, got %v", res.StaleReasons)
	}
}

func TestProposalFreshness_MissingTopicMarkers(t *testing.T) {
	store, repoRoot := setupStoreWithSourceFile(t, "docs/x.md", "hello")
	seedJobTopicProposal(t, store, "j1", "t1", "docs/x.md",
		blobSHA(t, "hello"),
		/*proposed = no marker for t2*/ "bare proposal body",
		"succeeded")
	mustInsertOpenTopic(t, store, "t2", "docs/x.md")

	res, err := ProposalFreshness(store, repoRoot, "p1")
	if err != nil {
		t.Fatalf("ProposalFreshness: %v", err)
	}
	if res.Fresh {
		t.Fatalf("expected Fresh=false")
	}
	if !containsString(res.StaleReasons, "missing_topic_markers") {
		t.Fatalf("expected missing_topic_markers, got %v", res.StaleReasons)
	}
	sort.Strings(res.MissingTopicIDs)
	if !reflect.DeepEqual(res.MissingTopicIDs, []string{"t2"}) {
		t.Fatalf("MissingTopicIDs: got %v, want [t2]", res.MissingTopicIDs)
	}
}

func TestProposalFreshness_FailedJobIsNotApprovable(t *testing.T) {
	store, repoRoot := setupStoreWithSourceFile(t, "docs/x.md", "hi")
	seedJobTopicProposal(t, store, "j1", "t1", "docs/x.md",
		blobSHA(t, "hi"), "", "failed")

	res, err := ProposalFreshness(store, repoRoot, "p1")
	if err != nil {
		t.Fatalf("ProposalFreshness: %v", err)
	}
	if res.Fresh {
		t.Fatalf("expected Fresh=false for failed linked job")
	}
}

// Helpers — implement next to the existing test helpers in collab. If
// setupStoreWithSourceFile / seedJobTopicProposal / mustInsertOpenTopic /
// blobSHA / containsString don't exist, add them in this file or a shared
// _test_helpers.go.

The helpers (setupStoreWithSourceFile, seedJobTopicProposal, etc.) should be added next to existing test helpers. blobSHA should use SourceSHAOfBytes (already in hashes.go) so the test matches what the code under test will compute.

• Step 2: Run the test and confirm it fails

go test ./internal/collab/ -run TestProposalFreshness -v

Expected: FAIL — ProposalFreshness undefined.

• Step 3: Implement the helper

Create internal/collab/freshness.go:

package collab

import (
	"database/sql"
	"fmt"
	"strings"
)

// Freshness is the result of checking whether a proposal is approvable.
// Fresh = true iff (linked Agent job is succeeded OR there is no linked job)
// AND base_source_sha matches the current Source SHA AND every current open
// non-global Topic on the Source except the proposal's own Topic has at
// least one data-orcha-anchor marker in proposed_source.
type Freshness struct {
	Fresh           bool
	StaleReasons    []string // subset of {"source_sha", "missing_topic_markers"}
	MissingTopicIDs []string // sorted; populated when StaleReasons contains "missing_topic_markers"
	JobStatus       string   // empty if there is no linked job
}

// ProposalFreshness inspects the proposal at proposalID and returns its
// approvability against the current state. Caller passes the repo root so
// the helper can hash the current Source on disk.
func ProposalFreshness(s *Store, repoRoot, proposalID string) (Freshness, error) {
	var (
		topicID, sourcePath, baseSourceSHA, proposed string
		agentJobID                                   sql.NullString
	)
	err := s.db.QueryRow(
		`SELECT p.topic_id, t.source_path, p.base_source_sha,
		        p.proposed_source, p.agent_job_id
		   FROM incorporation_proposals p
		   JOIN topics t ON t.id = p.topic_id
		  WHERE p.id = ?`, proposalID,
	).Scan(&topicID, &sourcePath, &baseSourceSHA, &proposed, &agentJobID)
	if err != nil {
		return Freshness{}, fmt.Errorf("load proposal: %w", err)
	}

	out := Freshness{Fresh: true}

	if agentJobID.Valid {
		var status string
		if err := s.db.QueryRow(
			`SELECT status FROM agent_jobs WHERE id = ?`, agentJobID.String,
		).Scan(&status); err != nil {
			return Freshness{}, fmt.Errorf("load agent_job: %w", err)
		}
		out.JobStatus = status
		if status != "succeeded" {
			out.Fresh = false
			// Not in stale_reasons — distinct concept (job didn't succeed
			// at all vs. proposal's bytes are out of date). UI surfaces via
			// JobStatus separately.
		}
	}

	currentSHA, err := SourceSHA(repoRoot, sourcePath)
	if err != nil {
		return Freshness{}, fmt.Errorf("hash current source: %w", err)
	}
	if currentSHA != baseSourceSHA {
		out.Fresh = false
		out.StaleReasons = append(out.StaleReasons, "source_sha")
	}

	openIDs, err := openNonGlobalTopicIDsExcluding(s, sourcePath, topicID)
	if err != nil {
		return Freshness{}, err
	}
	var missing []string
	for _, id := range openIDs {
		marker := `data-orcha-anchor="` + id + `"`
		if !strings.Contains(proposed, marker) {
			missing = append(missing, id)
		}
	}
	if len(missing) > 0 {
		out.Fresh = false
		out.StaleReasons = append(out.StaleReasons, "missing_topic_markers")
		out.MissingTopicIDs = missing
	}

	return out, nil
}

// openNonGlobalTopicIDsExcluding lists the IDs of open (not incorporated,
// not discarded) non-global Topics on sourcePath, minus excludeID. Sorted
// ascending for determinism.
func openNonGlobalTopicIDsExcluding(s *Store, sourcePath, excludeID string) ([]string, error) {
	rows, err := s.db.Query(
		`SELECT id FROM topics
		  WHERE source_path = ?
		    AND incorporated_at IS NULL
		    AND discarded_at IS NULL
		    AND id != ?
		    AND json_extract(anchor, '$.kind') != 'global'
		  ORDER BY id`, sourcePath, excludeID,
	)
	if err != nil {
		return nil, fmt.Errorf("list open topics: %w", err)
	}
	defer rows.Close()
	var ids []string
	for rows.Next() {
		var id string
		if err := rows.Scan(&id); err != nil {
			return nil, err
		}
		ids = append(ids, id)
	}
	return ids, rows.Err()
}

• Step 4: Re-run tests

go test ./internal/collab/ -run TestProposalFreshness -v

Expected: PASS.

• Step 5: Commit

git add internal/collab/freshness.go internal/collab/freshness_test.go
git commit -m "wiki-browser: collab — ProposalFreshness helper for stale_reasons"

Task 4: collab.CompleteIncorporation re-anchors other open Topics in-tx

Files:

• Modify: internal/collab/mutators.go (CompleteIncorporationInput, CompleteIncorporation)

• Modify: internal/collab/mutators_test.go

• Step 1: Write the failing test

In internal/collab/mutators_test.go, append:

func TestCompleteIncorporation_ReanchorsOtherOpenTopics(t *testing.T) {
	store, _ := setupStoreWithSourceFile(t, "docs/x.md", "hi")
	mustExec(t, store, `INSERT INTO users(id, display_name, created_at)
		VALUES ('u1','u1',unixepoch())`)
	// Incorporated Topic.
	mustExec(t, store, `INSERT INTO topics(id, source_path, anchor, created_by, created_at, updated_at)
		VALUES ('t1','docs/x.md','{"kind":"global"}','u1',unixepoch(),unixepoch())`)
	// Two other open Topics on the same source, currently in pre-marker state.
	pre := `{"kind":"pre-marker","source_sha":"stale","start":0,"end":1,"quote":"h"}`
	mustExec(t, store, `INSERT INTO topics(id, source_path, anchor, created_by, created_at, updated_at)
		VALUES ('t2','docs/x.md',?,'u1',unixepoch(),unixepoch())`, pre)
	mustExec(t, store, `INSERT INTO topics(id, source_path, anchor, created_by, created_at, updated_at)
		VALUES ('t3','docs/x.md',?,'u1',unixepoch(),unixepoch())`, pre)
	// One discarded Topic — must NOT be reanchored.
	mustExec(t, store, `INSERT INTO topics(id, source_path, anchor, created_by, discarded_by, discarded_at, created_at, updated_at)
		VALUES ('t4','docs/x.md',?,'u1','u1',unixepoch(),unixepoch(),unixepoch())`, pre)

	// Seed a proposal + attempt the incorporation transaction normally seeds.
	mustExec(t, store, `INSERT INTO incorporation_proposals(
		id, topic_id, revision_number, proposed_source, base_source_sha,
		proposed_by, created_at) VALUES ('p1','t1',1,'x','sha',NULL,unixepoch())`)
	mustExec(t, store, `INSERT INTO incorporation_attempts(
		id, proposal_id, topic_id, source_path, base_source_sha,
		approved_by, approved_at, created_at)
		VALUES ('a1','p1','t1','docs/x.md','sha','u1',unixepoch(),unixepoch())`)

	if err := store.CompleteIncorporation(CompleteIncorporationInput{
		TopicID:           "t1",
		ProposalID:        "p1",
		AttemptID:         "a1",
		CommitSHA:         "deadbeef",
		IncorporatedBy:    "u1",
		IncorporatedAt:    1700000000,
		ReanchorTopicIDs:  []string{"t2", "t3", "t4"}, // t4 must be filtered out
	}); err != nil {
		t.Fatalf("CompleteIncorporation: %v", err)
	}

	// t2 and t3 flip to marker; t4 stays pre-marker.
	assertAnchorKind(t, store, "t2", "marker")
	assertAnchorKind(t, store, "t3", "marker")
	assertAnchorKind(t, store, "t4", "pre-marker")
}

func assertAnchorKind(t *testing.T, s *Store, id, want string) {
	t.Helper()
	var anchor string
	if err := s.RawDB().QueryRow(
		`SELECT anchor FROM topics WHERE id = ?`, id,
	).Scan(&anchor); err != nil {
		t.Fatal(err)
	}
	a, err := UnmarshalAnchor(json.RawMessage(anchor))
	if err != nil {
		t.Fatalf("unmarshal %s: %v", id, err)
	}
	var kind string
	switch a.(type) {
	case MarkerAnchor:
		kind = "marker"
	case PreMarkerAnchor:
		kind = "pre-marker"
	case GlobalAnchor:
		kind = "global"
	}
	if kind != want {
		t.Fatalf("%s anchor kind = %q, want %q", id, kind, want)
	}
}

Adjust imports (encoding/json) at the top of the test file.

• Step 2: Run the test and confirm it fails

go test ./internal/collab/ -run TestCompleteIncorporation_ReanchorsOtherOpenTopics -v

Expected: FAIL — ReanchorTopicIDs undefined.

• Step 3: Extend the struct and the transaction

In internal/collab/mutators.go, extend CompleteIncorporationInput:

type CompleteIncorporationInput struct {
	TopicID          string
	ProposalID       string
	AttemptID        string
	CommitSHA        string
	IncorporatedBy   string
	IncorporatedAt   int64 // unix seconds; usually time.Now().Unix()
	ReanchorTopicIDs []string
}

In CompleteIncorporation, after the existing UPDATE incorporation_attempts … and before return tx.Commit(), add:

	if len(in.ReanchorTopicIDs) > 0 {
		// Build placeholders + args. Filter is by id IN (...), and the
		// WHERE clause additionally guards against any concurrent terminal
		// transitions (Discard or another Incorporation) and against
		// re-running the update against rows already at marker kind.
		placeholders := strings.TrimSuffix(strings.Repeat("?,", len(in.ReanchorTopicIDs)), ",")
		args := make([]any, 0, len(in.ReanchorTopicIDs))
		for _, id := range in.ReanchorTopicIDs {
			args = append(args, id)
		}
		query := `UPDATE topics
		             SET anchor = '{"kind":"marker"}',
		                 updated_at = unixepoch()
		           WHERE id IN (` + placeholders + `)
		             AND discarded_at IS NULL
		             AND incorporated_at IS NULL
		             AND json_extract(anchor, '$.kind') = 'pre-marker'`
		if _, err := tx.Exec(query, args...); err != nil {
			_ = tx.Rollback()
			return fmt.Errorf("reanchor topics: %w", err)
		}
	}

Add "strings" to the imports if not present.

• Step 4: Re-run tests

go test ./internal/collab/ -run TestCompleteIncorporation -v

Expected: PASS, plus any pre-existing tests on CompleteIncorporation should still pass.

• Step 5: Commit

git add internal/collab/mutators.go internal/collab/mutators_test.go
git commit -m "wiki-browser: collab — CompleteIncorporation reanchors other open Topics in-tx"

Task 5: Thread ReanchorTopicIDs through collab.Incorporate

Files:

• Modify: internal/collab/incorporate.go (IncorporateInput, body)

• Modify: internal/collab/incorporate_test.go (smoke test through the full protocol)

• Step 1: Write the failing test

In internal/collab/incorporate_test.go, append a test that runs Incorporate end-to-end with one other open Topic on the same Source and asserts it flips to marker. Pattern:

func TestIncorporate_ThreadsReanchorTopicIDs(t *testing.T) {
	// setup: a git repo at repoRoot with docs/x.md containing the base bytes,
	// a topic t1 to incorporate, a proposal p1 whose proposed_source replaces
	// the file content, and another open topic t2 with pre-marker anchor.
	// Reuse whatever helpers existing Incorporate tests use.

	got, err := Incorporate(store, IncorporateInput{
		RepoRoot:          repoRoot,
		ProposalID:        "p1",
		ApproverID:        "u1",
		ApproverName:      "U One",
		Subject:           "test",
		AuthorName:        "Orcha Agent",
		AuthorEmail:       "agent@orcha.local",
		ReanchorTopicIDs: []string{"t2"},
	})
	if err != nil {
		t.Fatalf("Incorporate: %v", err)
	}
	_ = got
	assertAnchorKind(t, store, "t2", "marker")
}

• Step 2: Run the test, confirm it fails

go test ./internal/collab/ -run TestIncorporate_ThreadsReanchorTopicIDs -v

Expected: FAIL — ReanchorTopicIDs undefined on IncorporateInput.

• Step 3: Extend IncorporateInput

In internal/collab/incorporate.go, modify the struct:

type IncorporateInput struct {
	RepoRoot         string
	ProposalID       string
	ApproverID       string // user id
	ApproverName     string // display name
	Subject          string // commit subject line
	Body             string // optional commit body
	AuthorName       string // git author/committer name (Agent identity)
	AuthorEmail      string // git author/committer email
	ReanchorTopicIDs []string
}

And update the call to CompleteIncorporation to pass it through:

	if err := s.CompleteIncorporation(CompleteIncorporationInput{
		TopicID:          prop.TopicID,
		ProposalID:       prop.ID,
		AttemptID:        attemptID,
		CommitSHA:        sha,
		IncorporatedBy:   in.ApproverID,
		IncorporatedAt:   time.Now().Unix(),
		ReanchorTopicIDs: in.ReanchorTopicIDs,
	}); err != nil {

• Step 4: Re-run tests

go test ./internal/collab/...

Expected: PASS.

• Step 5: Commit

git add internal/collab/incorporate.go internal/collab/incorporate_test.go
git commit -m "wiki-browser: collab — Incorporate threads ReanchorTopicIDs"

Phase 2 — wb-agent CLI simplifications

Task 6: wb-agent get-topic switches to --job-id, returns absolute path

Files:

• Modify: cmd/wb-agent/get_topic.go

• Modify: cmd/wb-agent/main_test.go (and any get-topic-specific test fixtures)

• Step 1: Write the failing test

In cmd/wb-agent/main_test.go, add or update a TestGetTopic_ByJobID that exercises the new shape:

func TestGetTopic_ByJobID(t *testing.T) {
	store, repoRoot, cfgPath := setupStoreWithJob(t, "j1", "t1", "docs/x.md", "hello")
	_ = store

	var stdout, stderr bytes.Buffer
	code := runGetTopic([]string{"--config=" + cfgPath, "--job-id=j1"},
		&stdout, &stderr, openTestStore(t))
	if code != 0 {
		t.Fatalf("exit %d, stderr=%q", code, stderr.String())
	}

	var got struct {
		ID            string `json:"id"`
		SourcePath    string `json:"source_path"`
		BaseSourceSHA string `json:"base_source_sha"`
		// no repo_root
		Messages []struct {
			Kind           string  `json:"kind"`
			ProposalID     *string `json:"proposal_id,omitempty"`
			ProposedSource *string `json:"proposed_source,omitempty"`
		} `json:"messages"`
	}
	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
		t.Fatalf("decode: %v", err)
	}
	if got.ID != "t1" {
		t.Fatalf("ID = %q, want t1", got.ID)
	}
	if got.SourcePath != filepath.Join(repoRoot, "docs/x.md") {
		t.Fatalf("SourcePath = %q, want absolute %q", got.SourcePath,
			filepath.Join(repoRoot, "docs/x.md"))
	}
	if got.BaseSourceSHA == "" {
		t.Fatalf("BaseSourceSHA empty")
	}
	// If setupStoreWithJob seeds an earlier agent-proposal message, it
	// must inline proposed_source so rework runs can see prior attempts.
	for _, m := range got.Messages {
		if m.Kind == "agent-proposal" && (m.ProposedSource == nil || *m.ProposedSource == "") {
			t.Fatalf("agent-proposal missing proposed_source: %+v", m)
		}
	}
}

Add helper setupStoreWithJob that writes the Source file inside the repo root, inserts a topic + agent_jobs row, and returns repo root + config path. Seed one prior proposal + agent-proposal message in the fixture so the test proves proposed_source is inlined.

• Step 2: Run, confirm failure

go test ./cmd/wb-agent/ -run TestGetTopic_ByJobID -v

Expected: FAIL.

• Step 3: Rewrite cmd/wb-agent/get_topic.go

Replace the file's body with:

package main

import (
	"database/sql"
	"encoding/json"
	"errors"
	"flag"
	"fmt"
	"io"
	"path/filepath"

	"github.com/getorcha/wiki-browser/internal/collab"
)

type getTopicOutput struct {
	ID            string            `json:"id"`
	SourcePath    string            `json:"source_path"` // absolute
	BaseSourceSHA string            `json:"base_source_sha"`
	Anchor        json.RawMessage   `json:"anchor"`
	CreatedBy     string            `json:"created_by"`
	CreatedAt     int64             `json:"created_at"`
	Messages      []getTopicMessage `json:"messages"`
}

type getTopicMessage struct {
	ID             string  `json:"id"`
	TopicID        string  `json:"topic_id"`
	Kind           string  `json:"kind"`
	Body           string  `json:"body"`
	AuthorUserID   *string `json:"author_user_id,omitempty"`
	ProposalID     *string `json:"proposal_id,omitempty"`
	ProposedSource *string `json:"proposed_source,omitempty"`
	Sequence       int     `json:"sequence"`
	CreatedAt      int64   `json:"created_at"`
}

func runGetTopic(args []string, stdout, stderr io.Writer, opener storeOpener) int {
	fs := flag.NewFlagSet("get-topic", flag.ContinueOnError)
	fs.SetOutput(stderr)
	configPath := fs.String("config", "wiki-browser.yaml", "path to config file")
	jobID := fs.String("job-id", "", "agent_jobs.id")
	if err := fs.Parse(args); err != nil {
		return 2
	}
	if *jobID == "" {
		fmt.Fprintln(stderr, "get-topic: --job-id is required")
		return 2
	}

	store, cfg, err := opener(*configPath)
	if err != nil {
		fmt.Fprintf(stderr, "open store: %v\n", err)
		return 1
	}
	defer store.Close()

	var (
		topicID, sourcePath string
	)
	if err := store.RawDB().QueryRow(
		`SELECT topic_id, source_path FROM agent_jobs WHERE id = ?`, *jobID,
	).Scan(&topicID, &sourcePath); err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			fmt.Fprintf(stderr, "agent job %s not found\n", *jobID)
			return 1
		}
		fmt.Fprintf(stderr, "scan job: %v\n", err)
		return 1
	}
	if topicID == "" {
		fmt.Fprintf(stderr, "agent job %s has no topic_id\n", *jobID)
		return 1
	}

	row := store.RawDB().QueryRow(
		`SELECT id, anchor, created_by, created_at
		   FROM topics WHERE id = ?`, topicID,
	)
	out := getTopicOutput{SourcePath: filepath.Join(cfg.Root, sourcePath)}
	var anchor string
	if err := row.Scan(&out.ID, &anchor, &out.CreatedBy, &out.CreatedAt); err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			fmt.Fprintf(stderr, "topic %s not found\n", topicID)
			return 1
		}
		fmt.Fprintf(stderr, "scan topic: %v\n", err)
		return 1
	}
	out.Anchor = json.RawMessage(anchor)

	sha, err := collab.SourceSHA(cfg.Root, sourcePath)
	if err != nil {
		fmt.Fprintf(stderr, "source sha: %v\n", err)
		return 1
	}
	out.BaseSourceSHA = sha

	msgs, err := store.ListMessages(topicID)
	if err != nil {
		fmt.Fprintf(stderr, "list messages: %v\n", err)
		return 1
	}
	out.Messages = make([]getTopicMessage, 0, len(msgs))
	for _, m := range msgs {
		gm := getTopicMessage{
			ID: m.ID, TopicID: m.TopicID, Kind: m.Kind, Body: m.Body,
			AuthorUserID: m.AuthorUserID, ProposalID: m.ProposalID,
			Sequence: m.Sequence, CreatedAt: m.CreatedAt,
		}
		if m.Kind == "agent-proposal" && m.ProposalID != nil {
			var proposed string
			if err := store.RawDB().QueryRow(
				`SELECT proposed_source FROM incorporation_proposals WHERE id = ?`,
				*m.ProposalID,
			).Scan(&proposed); err != nil {
				fmt.Fprintf(stderr, "load proposal %s: %v\n", *m.ProposalID, err)
				return 1
			}
			gm.ProposedSource = &proposed
		}
		out.Messages = append(out.Messages, gm)
	}

	if err := json.NewEncoder(stdout).Encode(out); err != nil {
		fmt.Fprintf(stderr, "encode: %v\n", err)
		return 1
	}
	return 0
}

Note the storeOpener signature change: it now returns (store, cfg, error) so subcommands know the repo root. Update storeOpener and its production / test implementations in cmd/wb-agent/main.go and the test helpers accordingly.

• Step 4: Update storeOpener and main.go

In cmd/wb-agent/main.go, change:

type storeOpener func(configPath string) (*collab.Store, *config.Config, error)

The production opener loads config.Config from the YAML and opens the store; tests can mock both.

• Step 5: Update every other subcommand that uses storeOpener

The signature change cascades. Five subcommands take storeOpener today: runGetTopic (this task), runListOpenTopics, runInsertProposal, runGetPersona (in cmd/wb-agent/stubs.go), and runPutPerspective (also stubs.go). All five must accept the third return value or the package won't compile. The list-open-topics and insert-proposal logic changes land in Tasks 7 and 8; for now make a minimal mechanical edit in each:

store, _, err := opener(*configPath) // cfg unused here yet

Touch the stub files (stubs.go) the same way — they don't use cfg but they must accept the new return shape. Update the test helpers (the test storeOpener factory) to return the three-value shape.

• Step 6: Re-run tests

go test ./cmd/wb-agent/...

Expected: PASS. Existing tests against the old --id flag will fail — delete them; this is the surface change.

• Step 7: Commit

git add cmd/wb-agent/get_topic.go cmd/wb-agent/list_open_topics.go cmd/wb-agent/insert_proposal.go cmd/wb-agent/main.go cmd/wb-agent/main_test.go
git commit -m "wiki-browser: wb-agent — get-topic keys on --job-id, returns absolute source_path"

Task 7: wb-agent list-open-topics adds --exclude-topic, validates absolute paths

Files:

• Modify: cmd/wb-agent/list_open_topics.go

• Modify: cmd/wb-agent/main_test.go

• Modify: internal/collab/reader.go (extend ListOpenTopicsForSource to take an exclusion list, or add a sibling)

• Step 1: Write the failing test

In cmd/wb-agent/main_test.go, add:

func TestListOpenTopics_ExcludesSelf_ValidatesPath(t *testing.T) {
	store, repoRoot, cfgPath := setupStoreWithTwoOpenTopics(t, "docs/x.md", "t1", "t2")
	_ = store

	abs := filepath.Join(repoRoot, "docs/x.md")
	var stdout, stderr bytes.Buffer
	code := runListOpenTopics(
		[]string{"--config=" + cfgPath, "--source-path=" + abs, "--exclude-topic=t1"},
		&stdout, &stderr, openTestStore(t),
	)
	if code != 0 {
		t.Fatalf("exit %d, stderr=%q", code, stderr.String())
	}
	var got []struct{ ID string }
	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
		t.Fatal(err)
	}
	if len(got) != 1 || got[0].ID != "t2" {
		t.Fatalf("got %v, want [t2]", got)
	}
}

func TestListOpenTopics_RejectsEscapingPath(t *testing.T) {
	_, _, cfgPath := setupStoreWithTwoOpenTopics(t, "docs/x.md", "t1", "t2")
	var stdout, stderr bytes.Buffer
	code := runListOpenTopics(
		[]string{"--config=" + cfgPath, "--source-path=/etc/passwd", "--exclude-topic=t1"},
		&stdout, &stderr, openTestStore(t),
	)
	if code == 0 {
		t.Fatalf("expected non-zero exit, got 0")
	}
	if !strings.Contains(stderr.String(), "source path") {
		t.Fatalf("stderr = %q, want path validation error", stderr.String())
	}
}

• Step 2: Run, confirm failure

go test ./cmd/wb-agent/ -run TestListOpenTopics -v

Expected: FAIL.

• Step 3: Rewrite cmd/wb-agent/list_open_topics.go

package main

import (
	"encoding/json"
	"flag"
	"fmt"
	"io"
	"path/filepath"
	"strings"

	"github.com/getorcha/wiki-browser/internal/collab"
)

func runListOpenTopics(args []string, stdout, stderr io.Writer, opener storeOpener) int {
	fs := flag.NewFlagSet("list-open-topics", flag.ContinueOnError)
	fs.SetOutput(stderr)
	configPath := fs.String("config", "wiki-browser.yaml", "path to config file")
	sourcePath := fs.String("source-path", "", "absolute path to the source file")
	excludeTopic := fs.String("exclude-topic", "", "topic id to exclude from the listing")
	if err := fs.Parse(args); err != nil {
		return 2
	}
	if *sourcePath == "" {
		fmt.Fprintln(stderr, "list-open-topics: --source-path is required")
		return 2
	}

	store, cfg, err := opener(*configPath)
	if err != nil {
		fmt.Fprintf(stderr, "open store: %v\n", err)
		return 1
	}
	defer store.Close()

	// Normalise absolute path to repo-relative + validate.
	abs := filepath.Clean(*sourcePath)
	rel, err := filepath.Rel(cfg.Root, abs)
	if err != nil || strings.HasPrefix(rel, "..") || filepath.IsAbs(rel) {
		fmt.Fprintf(stderr, "list-open-topics: source path escapes repo root: %q\n", abs)
		return 1
	}
	if _, err := collab.ValidateSourcePath(rel); err != nil {
		fmt.Fprintf(stderr, "list-open-topics: invalid source path %q: %v\n", rel, err)
		return 1
	}

	topics, err := store.ListOpenTopicsForSourceExcluding(rel, *excludeTopic)
	if err != nil {
		fmt.Fprintf(stderr, "list: %v\n", err)
		return 1
	}
	if err := json.NewEncoder(stdout).Encode(topics); err != nil {
		fmt.Fprintf(stderr, "encode: %v\n", err)
		return 1
	}
	return 0
}

• Step 4: Add ListOpenTopicsForSourceExcluding to collab.reader.go

In internal/collab/reader.go, add a sibling method to ListOpenTopicsForSource:

// ListOpenTopicsForSourceExcluding is like ListOpenTopicsForSource but skips
// the topic whose id equals excludeID (empty string disables the filter) and
// any global-anchor topics. Use this for re-anchor working sets where the
// caller needs every-other open Topic except the one currently being
// resolved.
func (s *Store) ListOpenTopicsForSourceExcluding(sourcePath, excludeID string) ([]TopicSummary, error) {
	if _, err := ValidateSourcePath(sourcePath); err != nil {
		return nil, fmt.Errorf("collab.ListOpenTopicsForSourceExcluding: %w", err)
	}
	rows, err := s.db.Query(
		`SELECT id, source_path, anchor, created_by, created_at, updated_at
		   FROM topics
		  WHERE source_path = ?
		    AND incorporated_at IS NULL
		    AND discarded_at IS NULL
		    AND id != COALESCE(?, '')
		    AND json_extract(anchor, '$.kind') != 'global'
		  ORDER BY created_at`, sourcePath, excludeID,
	)
	if err != nil {
		return nil, err
	}
	defer rows.Close()
	// Reuse the same scan logic as ListOpenTopicsForSource. Pull the helper
	// out if it's currently inlined.
	return scanTopicSummaries(rows)
}

If scanTopicSummaries doesn't exist, extract the scan loop from ListOpenTopicsForSource into a helper and reuse it from both methods.

• Step 5: Re-run tests

go test ./cmd/wb-agent/... ./internal/collab/...

Expected: PASS.

• Step 6: Commit

git add cmd/wb-agent/list_open_topics.go cmd/wb-agent/main_test.go internal/collab/reader.go
git commit -m "wiki-browser: wb-agent — list-open-topics adds --exclude-topic, validates absolute path"

Task 8: wb-agent insert-proposal — slim flags, BEGIN IMMEDIATE, explanation, agent_job_id

Files:

• Modify: cmd/wb-agent/insert_proposal.go

• Modify: cmd/wb-agent/main_test.go

• Step 1: Write the failing test

In cmd/wb-agent/main_test.go, add:

func TestInsertProposal_JobID_Explanation_AgentMessage(t *testing.T) {
	store, repoRoot, cfgPath := setupStoreWithJob(t, "j1", "t1", "docs/x.md", "hi")
	_ = repoRoot

	body := bytes.NewBufferString(`<span data-orcha-anchor="t2">x</span>`)
	var stdout, stderr bytes.Buffer
	code := runInsertProposal(
		[]string{
			"--config=" + cfgPath,
			"--job-id=j1",
			"--explanation=I understood the discussion as foo and applied it as bar.",
		},
		&stdout, &stderr, body, openTestStore(t),
	)
	if code != 0 {
		t.Fatalf("exit %d, stderr=%q", code, stderr.String())
	}

	var out struct {
		ID             string `json:"id"`
		RevisionNumber int    `json:"revision_number"`
		MessageID      string `json:"message_id"`
	}
	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
		t.Fatal(err)
	}
	if out.ID == "" || out.MessageID == "" || out.RevisionNumber != 1 {
		t.Fatalf("unexpected output: %+v", out)
	}

	// Verify proposal row.
	var (
		jobID sql.NullString
		bodyGot, kind string
		propID sql.NullString
	)
	if err := store.RawDB().QueryRow(
		`SELECT agent_job_id FROM incorporation_proposals WHERE id = ?`, out.ID,
	).Scan(&jobID); err != nil {
		t.Fatal(err)
	}
	if !jobID.Valid || jobID.String != "j1" {
		t.Fatalf("agent_job_id: %v", jobID)
	}

	// Verify accompanying agent-proposal message.
	if err := store.RawDB().QueryRow(
		`SELECT kind, body, proposal_id FROM topic_messages WHERE id = ?`,
		out.MessageID,
	).Scan(&kind, &bodyGot, &propID); err != nil {
		t.Fatal(err)
	}
	if kind != "agent-proposal" {
		t.Fatalf("message kind = %q, want agent-proposal", kind)
	}
	if !propID.Valid || propID.String != out.ID {
		t.Fatalf("message proposal_id: %v", propID)
	}
	if !strings.Contains(bodyGot, "I understood") {
		t.Fatalf("body: %q", bodyGot)
	}
}

func TestInsertProposal_RejectsEmptyExplanation(t *testing.T) {
	_, _, cfgPath := setupStoreWithJob(t, "j1", "t1", "docs/x.md", "hi")

	body := bytes.NewBufferString("anything")
	var stdout, stderr bytes.Buffer
	code := runInsertProposal(
		[]string{"--config=" + cfgPath, "--job-id=j1", "--explanation="},
		&stdout, &stderr, body, openTestStore(t),
	)
	if code == 0 {
		t.Fatalf("expected non-zero exit on empty explanation")
	}
}

• Step 2: Run, confirm failure

go test ./cmd/wb-agent/ -run TestInsertProposal -v

Expected: FAIL.

• Step 3: Rewrite cmd/wb-agent/insert_proposal.go

package main

import (
	"context"
	"database/sql"
	"encoding/json"
	"errors"
	"flag"
	"fmt"
	"io"
	"strings"

	"github.com/google/uuid"

	"github.com/getorcha/wiki-browser/internal/collab"
)

func runInsertProposal(args []string, stdout, stderr io.Writer, stdin io.Reader, opener storeOpener) int {
	fs := flag.NewFlagSet("insert-proposal", flag.ContinueOnError)
	fs.SetOutput(stderr)
	configPath := fs.String("config", "wiki-browser.yaml", "path to config file")
	jobID := fs.String("job-id", "", "agent_jobs.id")
	explanation := fs.String("explanation", "",
		"natural-language explanation of the rewrite; stored as the agent-proposal message body")
	if err := fs.Parse(args); err != nil {
		return 2
	}
	if *jobID == "" {
		fmt.Fprintln(stderr, "insert-proposal: --job-id is required")
		return 2
	}
	if strings.TrimSpace(*explanation) == "" {
		fmt.Fprintln(stderr, "insert-proposal: --explanation must be non-empty")
		return 2
	}

	source, err := io.ReadAll(stdin)
	if err != nil {
		fmt.Fprintf(stderr, "read stdin: %v\n", err)
		return 1
	}
	if len(source) == 0 {
		fmt.Fprintln(stderr, "insert-proposal: stdin (proposed source) is empty")
		return 2
	}

	store, cfg, err := opener(*configPath)
	if err != nil {
		fmt.Fprintf(stderr, "open store: %v\n", err)
		return 1
	}
	defer store.Close()

	// Look up topic + source_path through the job.
	var topicID, sourcePath string
	if err := store.RawDB().QueryRow(
		`SELECT topic_id, source_path FROM agent_jobs WHERE id = ?`, *jobID,
	).Scan(&topicID, &sourcePath); err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			fmt.Fprintf(stderr, "agent job %s not found\n", *jobID)
			return 1
		}
		fmt.Fprintf(stderr, "scan job: %v\n", err)
		return 1
	}
	if topicID == "" {
		fmt.Fprintln(stderr, "insert-proposal: job has no topic_id")
		return 1
	}

	// Hash the current Source at the moment the proposal is recorded.
	baseSHA, err := collab.SourceSHA(cfg.Root, sourcePath)
	if err != nil {
		fmt.Fprintf(stderr, "hash source: %v\n", err)
		return 1
	}

	proposalID := uuid.NewString()
	messageID := uuid.NewString()

	// Single transaction, BEGIN IMMEDIATE so the cross-process write lock
	// acquires up-front. Do this on a dedicated raw connection; calling
	// db.Begin() first would already start a DEFERRED transaction and make
	// BEGIN IMMEDIATE fail as a nested transaction.
	db := store.RawDB()
	ctx := context.Background()
	conn, err := db.Conn(ctx)
	if err != nil {
		fmt.Fprintf(stderr, "conn: %v\n", err)
		return 1
	}
	defer conn.Close()
	rollback := func() { _, _ = conn.ExecContext(ctx, `ROLLBACK`) }

	if _, err := conn.ExecContext(ctx, `BEGIN IMMEDIATE`); err != nil {
		fmt.Fprintf(stderr, "begin immediate: %v\n", err)
		return 1
	}

	// Allocate revision_number.
	var nextRev int
	if err := conn.QueryRowContext(ctx,
		`SELECT COALESCE(MAX(revision_number), 0) + 1
		   FROM incorporation_proposals WHERE topic_id = ?`, topicID,
	).Scan(&nextRev); err != nil {
		rollback()
		fmt.Fprintf(stderr, "next revision: %v\n", err)
		return 1
	}

	// Insert proposal row.
	if _, err := conn.ExecContext(ctx,
		`INSERT INTO incorporation_proposals(
		   id, topic_id, revision_number, proposed_source,
		   base_source_sha, proposed_by, agent_job_id, created_at
		 ) VALUES (?, ?, ?, ?, ?, NULL, ?, unixepoch())`,
		proposalID, topicID, nextRev, string(source), baseSHA, *jobID,
	); err != nil {
		rollback()
		fmt.Fprintf(stderr, "insert proposal: %v\n", err)
		return 1
	}

	// Allocate sequence and insert agent-proposal message.
	var nextSeq int
	if err := conn.QueryRowContext(ctx,
		`SELECT COALESCE(MAX(sequence), 0) + 1
		   FROM topic_messages WHERE topic_id = ?`, topicID,
	).Scan(&nextSeq); err != nil {
		rollback()
		fmt.Fprintf(stderr, "next sequence: %v\n", err)
		return 1
	}
	if _, err := conn.ExecContext(ctx,
		`INSERT INTO topic_messages(
		   id, topic_id, kind, body, author_user_id, proposal_id, sequence, created_at
		 ) VALUES (?, ?, 'agent-proposal', ?, NULL, ?, ?, unixepoch())`,
		messageID, topicID, *explanation, proposalID, nextSeq,
	); err != nil {
		rollback()
		fmt.Fprintf(stderr, "insert message: %v\n", err)
		return 1
	}

	if _, err := conn.ExecContext(ctx, `COMMIT`); err != nil {
		rollback()
		fmt.Fprintf(stderr, "commit: %v\n", err)
		return 1
	}

	_ = json.NewEncoder(stdout).Encode(struct {
		ID             string `json:"id"`
		RevisionNumber int    `json:"revision_number"`
		MessageID      string `json:"message_id"`
	}{ID: proposalID, RevisionNumber: nextRev, MessageID: messageID})
	return 0
}