Skip to content

Show where each change's issue, branch, and worktree live - #169

Merged
androidand merged 2 commits into
mainfrom
feat/168-agent-topology-command
Sep 17, 2026
Merged

androidand merged 2 commits into
mainfrom
feat/168-agent-topology-command

Conversation

@androidand

@androidand androidand commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Summary

  • Adds specsync topology: a read-only join of every OpenSpec change with its tracker issue, git branch, and worktree path across coordinated stores — so an agent can check what's already in flight before starting, instead of ad-hoc scanning git/gh state itself.
  • Every source is independently optional: no openspec binary, no gh auth, an uncloned sibling store, or a store with zero worktrees each narrow the affected rows and append a reason to status[] rather than failing the command. Exits non-zero only when nothing could be resolved at all.
  • linked resolves from links.md against a local slug index built across every loaded change. epic resolves an otherwise-unmatched related link by confirming the referenced issue's type:epic label via one bounded gh call — specsync epic only writes a remote backlink today (never a local one), so this is the only reliable signal available.
  • Adds the "check topology before starting" step to the embedded SKILL.md, propagated byte-identically to all 4 copies (verified by TestSkillDrift), plus a site/features.json entry and a README mention.
  • Also fixes an unrelated, pre-existing test bug: TestPull_CannotResolveFromBranch relied on whatever branch the suite happened to be run from instead of overriding currentBranchFn like every other branch-resolution test — it failed whenever run from a feat/<n>-<slug>-named branch (i.e. this one).

Closes #168

Test plan

  • go build ./..., go vet ./..., gofmt -l clean on every touched file
  • go test ./...806 passed, 0 failed
  • New unit tests for BuildTopology: fully resolved single store, no-worktree row still returned with exit 0, gh-unauthenticated degradation + status note, nothing-resolved is an empty result not an error, read-only (no cache/state written), -change scoping, archived exclusion + -all, multi-repo store join, linked resolution, epic resolution via label
  • New unit tests for listWorktrees/matchWorktree: regular/detached/bare porcelain parsing; matched by branch, matched by basename fallback, unmatched
  • New unit tests for printTopologyTable in cmd/specsync
  • Dogfooded against this repo: specsync topology correctly listed ~29 changes including this very change, with its real branch (feat/168-agent-topology-command) and worktree path (the worktree it was written in); specsync topology -json -change agent-topology-command with a local ref cache resolved live issue state via a real gh call; re-run with gh removed from PATH degraded exactly as documented (state omitted, status note present, everything else still resolved)
  • Timed: ~1.5s wall-clock for this repo's ~29 changes, one store, no gh calls — acceptable for an agent-startup check
  • specsync changelog -resolve-refs renders this commit under "Added" via the proposal's title

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 17, 2026

Copy link
Copy Markdown

Deploying specsync with  Cloudflare Pages  Cloudflare Pages

Latest commit: dda247f
Status: ✅  Deploy successful!
Preview URL: https://12aae2c2.specsync.pages.dev
Branch Preview URL: https://feat-168-agent-topology-comm.specsync.pages.dev

View logs

… join (#168)

Adds `specsync topology`, joining every OpenSpec change across
coordinated stores with its tracker issue, git branch, and worktree
path -- so an agent can check what's already in flight before
starting work, without a fragile ad-hoc scan of git and gh state.

Every source (openspec context, gh, git worktree listings) is
optional: a missing one narrows a row and appends a status note
instead of failing the command. Exits non-zero only when nothing
could be resolved at all.

Also resolves `linked` (from links.md) and `epic` (confirmed via the
epic issue's `type:epic` label on an otherwise-unresolved related
link, since `specsync epic` only writes a remote backlink today, not
a local one).

Adds the "check topology before starting" step to the embedded
SKILL.md (propagated to all 4 copies) and a site/features.json entry.
)

Relied on whatever branch the test suite happened to run from instead
of overriding currentBranchFn like every other branch-resolution
test, so it failed whenever run from a feat/<n>-<slug>-named branch
(i.e. this branch).
@androidand
androidand force-pushed the feat/168-agent-topology-command branch from 50243e2 to dda247f Compare September 17, 2026 14:29
@androidand
androidand merged commit fb4d8c0 into main Sep 17, 2026
2 checks passed
@androidand
androidand deleted the feat/168-agent-topology-command branch September 17, 2026 14:31
androidand added a commit that referenced this pull request Sep 17, 2026
… agent-topology-command (#159, #166, #168)

All three shipped (PRs #165, #167, #169) with every task checked.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Show where each change's issue, branch, and worktree live

1 participant