feat(#96): linker cleanup — LinkerResult, slug-matching, dead code removal (#97)

## What ships

- **LinkerResult with Source** — sync now reports whether an issue was
resolved from branch name or cache
- **Slug-aware branch matching** — `feat/42-my-change` only resolves for
`my-change`, not all changes
- **Dead code removed** — MarkerResolver (expensive API call) and
ExternalResolver (placeholder) gone
- **Pull simplified** — uses BranchResolver directly instead of full
Linker chain
- **Site** — added linker feature to features.json
- **npm** — bumped to 0.10.0

## Tests

395 tests pass, 2 dead tests removed (ExternalResolver,
resolveOpenSpecDir).

Author: androidand

cmd/specsync/main.go

@@ -256,6 +256,7 @@ func runSync(args []string) {
 		Reconcile:      *reconcile,
 		CloseCompleted: *closeCompleted,
 		Project:        target,
+		Linker:         buildSyncLinker(*repo, providers),
 	})
 	if err != nil {
 		fail(err)
@@ -351,9 +352,6 @@ func runPull(args []string) {
 		StatusMapping: statusMapping,
 	}
 
-	// Auto-resolve issue from branch name when -issue is not provided.
-	linker := buildPullLinker(*repo)
-
 	if *worktree {
 		runPullWithWorktree(*issue, *change, *repo, *dryRun, target, *worktreeDir)
 		return
@@ -366,7 +364,6 @@ func runPull(args []string) {
 		Slug:        *change,
 		DryRun:      *dryRun,
 		Project:     target,
-		Linker:      linker,
 	})
 	if err != nil {
 		fail(err)
@@ -703,6 +700,23 @@ func detectProvider(provider string) (string, string) {
 	return "github", ""
 }
 
+// buildSyncLinker builds a ChainLinker for sync with discovery resolvers
+// in priority order: branch only. The cache is NOT a resolver here — the
+// provider loop already reads the cache for each provider. Including the
+// cache in the Linker would return a ref from one provider and use it as
+// a fallback for another, causing cross-provider ref pollution.
+func buildSyncLinker(repo string, providers []specsync.WorkProvider) specsync.Linker {
+	var resolvers []specsync.Resolver
+
+	// Branch resolver — slug-aware to prevent resolving all changes to the
+	// same issue when syncing multiple changes at once.
+	if repo != "" {
+		resolvers = append(resolvers, specsync.NewBranchResolver(repo))
+	}
+
+	return specsync.NewChainLinker(resolvers...)
+}
+
 // makeProvider builds the selected work provider, substituting a dry-runner that
 // prints commands instead of executing them when dryRun is set. github
 // (default) targets repo (auto-detect when empty); beads drives the local `bd`
@@ -725,18 +739,6 @@ func makeProvider(repo string, dryRun bool, provider string) specsync.WorkProvid
 	}
 }
 
-// buildPullLinker creates a Linker for the pull command. It resolves the issue
-// from the current branch name (e.g., feat/42-change → #42) so -issue is
-// optional when on an issue-linked branch.
-func buildPullLinker(repo string) specsync.Linker {
-	r, err := getRepoName(context.Background(), repo)
-	if err != nil {
-		return nil
-	}
-	br := specsync.NewBranchResolver(r)
-	return specsync.NewChainLinker(br)
-}
-
 // parseStatusMapping parses "-status-map" (falling back to $SPECSYNC_STATUS_MAP)
 // into per-stage Status-name overrides. The format is comma-separated
 // stage=Name pairs where stage is active, complete, or archived; Status names

linker.go

@@ -8,17 +8,24 @@ import (
 	"strings"
 )
 
+// LinkerResult holds a resolved Ref and the source that produced it
+// (e.g., "branch", "cache"). Used by sync for dry-run visibility.
+type LinkerResult struct {
+	Ref    *Ref
+	Source string // human-readable source label
+}
+
 // Linker resolves a change to its issue ref by consulting multiple sources
 // in priority order. The first hit wins; the result is cached for the
 // duration of the sync run.
 type Linker interface {
-	// Resolve returns the Ref for the given change directory. Returns nil if
-	// no resolver found a match.
-	Resolve(ctx context.Context, changeDir string) (*Ref, error)
+	// Resolve returns the LinkerResult for the given change directory, or
+	// (nil, nil) if no resolver found a match.
+	Resolve(ctx context.Context, changeDir string) (*LinkerResult, error)
 	// ResolveFromContext resolves without a change directory, using only
 	// the context (e.g., current branch name). Returns (nil, nil) if not
 	// supported by this linker.
-	ResolveFromContext(ctx context.Context) (*Ref, error)
+	ResolveFromContext(ctx context.Context) (*LinkerResult, error)
 }
 
 // ChainLinker tries each resolver in order until one returns a non-nil Ref.
@@ -30,9 +37,9 @@ type ChainLinker struct {
 // Resolver is a single link resolution strategy. Returns (nil, nil) if it
 // cannot resolve (not a match), or (nil, err) if it encounters an error.
 type Resolver interface {
-	// Resolve returns the Ref if this resolver can match, or (nil, nil) to
-	// pass to the next resolver.
-	Resolve(ctx context.Context, changeDir string) (*Ref, error)
+	// Resolve returns the LinkerResult if this resolver can match, or
+	// (nil, nil) to pass to the next resolver.
+	Resolve(ctx context.Context, changeDir string) (*LinkerResult, error)
 }
 
 // NewChainLinker creates a ChainLinker with the given resolvers in priority
@@ -41,28 +48,28 @@ func NewChainLinker(resolvers ...Resolver) *ChainLinker {
 	return &ChainLinker{resolvers: resolvers}
 }
 
-func (c *ChainLinker) Resolve(ctx context.Context, changeDir string) (*Ref, error) {
+func (c *ChainLinker) Resolve(ctx context.Context, changeDir string) (*LinkerResult, error) {
 	for _, r := range c.resolvers {
-		ref, err := r.Resolve(ctx, changeDir)
+		result, err := r.Resolve(ctx, changeDir)
 		if err != nil {
 			return nil, fmt.Errorf("resolver: %w", err)
 		}
-		if ref != nil {
-			return ref, nil
+		if result != nil && result.Ref != nil {
+			return result, nil
 		}
 	}
 	return nil, nil
 }
 
-func (c *ChainLinker) ResolveFromContext(ctx context.Context) (*Ref, error) {
+func (c *ChainLinker) ResolveFromContext(ctx context.Context) (*LinkerResult, error) {
 	for _, r := range c.resolvers {
 		if cr, ok := r.(contextResolver); ok {
-			ref, err := cr.ResolveFromContext(ctx)
+			result, err := cr.ResolveFromContext(ctx)
 			if err != nil {
 				return nil, fmt.Errorf("resolver: %w", err)
 			}
-			if ref != nil {
-				return ref, nil
+			if result != nil && result.Ref != nil {
+				return result, nil
 			}
 		}
 	}
@@ -71,11 +78,13 @@ func (c *ChainLinker) ResolveFromContext(ctx context.Context) (*Ref, error) {
 
 // contextResolver is a resolver that can resolve without a change directory.
 type contextResolver interface {
-	ResolveFromContext(ctx context.Context) (*Ref, error)
+	ResolveFromContext(ctx context.Context) (*LinkerResult, error)
 }
 
 // BranchResolver extracts an issue number from the current git branch name.
 // The pattern is configurable; default: `feat/(\d+)-.*` or `fix/(\d+)-.*`.
+// When given a changeDir, it verifies the slug matches the branch suffix
+// to avoid resolving all changes to the same issue.
 type BranchResolver struct {
 	repo string // "owner/name" — required to build the URL
 	pats []*regexp.Regexp
@@ -87,21 +96,13 @@ type BranchResolver struct {
 func NewBranchResolver(repo string, pats ...*regexp.Regexp) *BranchResolver {
 	if len(pats) == 0 {
 		pats = []*regexp.Regexp{
-			regexp.MustCompile(`^(?:feat|fix)/(\d+)-.*`),
+			regexp.MustCompile(`^(?:feat|fix)/(\d+)-(.+)$`),
 		}
 	}
 	return &BranchResolver{repo: repo, pats: pats}
 }
 
-func (b *BranchResolver) Resolve(_ context.Context, changeDir string) (*Ref, error) {
-	return b.resolveFromBranch()
-}
-
-func (b *BranchResolver) ResolveFromContext(_ context.Context) (*Ref, error) {
-	return b.resolveFromBranch()
-}
-
-func (b *BranchResolver) resolveFromBranch() (*Ref, error) {
+func (b *BranchResolver) Resolve(ctx context.Context, changeDir string) (*LinkerResult, error) {
 	if b.repo == "" {
 		return nil, nil
 	}
@@ -113,50 +114,63 @@ func (b *BranchResolver) resolveFromBranch() (*Ref, error) {
 
 	for _, pat := range b.pats {
 		matches := pat.FindStringSubmatch(branch)
-		if len(matches) < 2 {
+		if len(matches) < 3 {
 			continue
 		}
 		num := matches[1]
+		branchSuffix := matches[2]
+
+		// When resolving for a specific change, verify the slug matches
+		// the branch suffix. This prevents all changes from resolving to
+		// the same issue when syncing multiple changes at once.
+		if changeDir != "" {
+			slug := filepath.Base(changeDir)
+			if slug != branchSuffix {
+				continue
+			}
+		}
+
 		url := fmt.Sprintf("https://github.com/%s/issues/%s", b.repo, num)
-		return &Ref{
-			Provider: "github:" + b.repo,
-			ID:       num,
-			URL:      url,
+		return &LinkerResult{
+			Ref: &Ref{
+				Provider: "github:" + b.repo,
+				ID:       num,
+				URL:      url,
+			},
+			Source: "branch",
 		}, nil
 	}
 
 	return nil, nil
 }
 
-// MarkerResolver resolves via the <!-- specsync:change=<slug> --> marker in
-// an existing issue body. It uses the provider's Find method.
-type MarkerResolver struct {
-	provider WorkProvider
-}
-
-// NewMarkerResolver creates a MarkerResolver that uses the given provider's
-// Find method to search for the specsync marker.
-func NewMarkerResolver(provider WorkProvider) *MarkerResolver {
-	return &MarkerResolver{provider: provider}
-}
-
-func (m *MarkerResolver) Resolve(ctx context.Context, changeDir string) (*Ref, error) {
-	openspecDir := resolveOpenSpecDir(changeDir)
-	if openspecDir == "" {
+func (b *BranchResolver) ResolveFromContext(ctx context.Context) (*LinkerResult, error) {
+	if b.repo == "" {
 		return nil, nil
 	}
-	c, err := LoadChangeBySlug(openspecDir, filepath.Base(changeDir))
-	if err != nil {
+
+	branch, err := currentBranch()
+	if err != nil || branch == "" {
 		return nil, nil
 	}
-	ref, err := m.provider.Find(ctx, c.Slug)
-	if err != nil {
-		return nil, fmt.Errorf("marker find: %w", err)
+
+	for _, pat := range b.pats {
+		matches := pat.FindStringSubmatch(branch)
+		if len(matches) < 2 {
+			continue
+		}
+		num := matches[1]
+		url := fmt.Sprintf("https://github.com/%s/issues/%s", b.repo, num)
+		return &LinkerResult{
+			Ref: &Ref{
+				Provider: "github:" + b.repo,
+				ID:       num,
+				URL:      url,
+			},
+			Source: "branch",
+		}, nil
 	}
-	return ref, nil
-}
 
-func (m *MarkerResolver) ResolveFromContext(_ context.Context) (*Ref, error) {
 	return nil, nil
 }
 
@@ -170,74 +184,38 @@ func NewCacheResolver(providerName string) *CacheResolver {
 	return &CacheResolver{providerName: providerName}
 }
 
-func (c *CacheResolver) Resolve(_ context.Context, changeDir string) (*Ref, error) {
+func (c *CacheResolver) Resolve(_ context.Context, changeDir string) (*LinkerResult, error) {
 	refs, err := loadRefs(changeDir)
 	if err != nil {
 		return nil, fmt.Errorf("cache read: %w", err)
 	}
 
 	// Try the exact provider key first.
 	if ref, ok := refs[c.providerName]; ok {
-		return &ref, nil
+		return &LinkerResult{Ref: &ref, Source: "cache"}, nil
 	}
 
 	// Try the legacy bare "github" key for github: prefixed providers.
 	if strings.HasPrefix(c.providerName, "github:") {
 		if ref, ok := refs["github"]; ok {
-			return &ref, nil
+			return &LinkerResult{Ref: &ref, Source: "cache"}, nil
 		}
 	}
 
 	return nil, nil
 }
 
-func (c *CacheResolver) ResolveFromContext(_ context.Context) (*Ref, error) {
-	return nil, nil
-}
-
-// ExternalResolver is a configurable hook for external relation sources
-// (e.g. MCP, database, or custom logic).
-type ExternalResolver struct {
-	fn func(ctx context.Context, changeDir string) (*Ref, error)
-}
-
-// NewExternalResolver creates an ExternalResolver with the given function.
-func NewExternalResolver(fn func(ctx context.Context, changeDir string) (*Ref, error)) *ExternalResolver {
-	return &ExternalResolver{fn: fn}
-}
-
-func (e *ExternalResolver) Resolve(ctx context.Context, changeDir string) (*Ref, error) {
-	return e.fn(ctx, changeDir)
-}
-
-func (e *ExternalResolver) ResolveFromContext(_ context.Context) (*Ref, error) {
-	return nil, nil
-}
-
-// currentBranch returns the current git branch name, or "" if not on a branch.
-func currentBranch() (string, error) {
+// currentBranchFn is the function that returns the current git branch name.
+// It is a variable so it can be overridden in tests.
+var currentBranchFn = func() (string, error) {
 	out, err := runGit(context.Background(), "rev-parse", "--abbrev-ref", "HEAD")
 	if err != nil {
 		return "", err
 	}
 	return strings.TrimSpace(out), nil
 }
 
-// resolveOpenSpecDir returns the openspec/ directory that contains the given
-// change directory. It walks up from changeDir looking for a parent named
-// "changes" or "archive", then returns that parent.
-func resolveOpenSpecDir(changeDir string) string {
-	dir := changeDir
-	for {
-		parent := filepath.Dir(dir)
-		base := filepath.Base(dir)
-		if base == "changes" || base == "archive" {
-			return parent
-		}
-		dir = parent
-		if dir == "/" || dir == "" || dir == "." {
-			break
-		}
-	}
-	return ""
+// currentBranch returns the current git branch name, or "" if not on a branch.
+func currentBranch() (string, error) {
+	return currentBranchFn()
 }