feat: spinoff subcommand — spawn linked child changes from discoveries (#9)

Author: androidand

.claude/skills/specsync/SKILL.md

@@ -28,6 +28,10 @@ specsync [-dry-run] [-change <change>] [-repo owner/name] [-reconcile=false] [-c
 - `-close-completed` (default false): keep tracker open/closed state aligned with completion. Completing every task closes the item; adding new unchecked work reopens it. Without the flag, completion updates `stage:complete` but leaves tracker state alone. An explicit `.status` overrides task-derived stage, so only `.status` value `complete` closes with this flag.
 - `-repo owner/name`: override auto-detected repo from `git remote`.
 
+**Task states.** Beyond `[ ]` (todo) and `[x]` (done), tasks.md supports `[~]` (dropped — superseded or removed) and `[>]` (moved — relocated to another change). Dropped and moved tasks are excluded from progress; only todo and done are "live". The issue body shows a "Plan changes" footer with the breakdown: `+3 added · 2 done · 1 dropped · 1 moved`.
+
+**Discoveries.** Capture findings during implementation without scope decisions. `specsync note -change <slug> "<text>"` appends a line to `discoveries.md`, rendered as `## Discoveries` in the issue. On pull, the section is stripped (like `## Tasks`). The original issue body is saved as `original-ask.md` on first pull (write-once, never overwritten) and rendered as `## Original ask`.
+
 **Lifecycle stages.** specsync labels each issue `stage:<stage>`. The stage is derived automatically: `active` while any task is unchecked, `complete` once every task is checked (before archiving), and `archived` once the change moves under `changes/archive/`. A `.status` file in the change folder overrides the derived stage. This means finishing the last task flips the issue out of `stage:active` on the next sync — no manual bookkeeping.
 
 ### Pull an issue into a local change
@@ -70,6 +74,15 @@ specsync link [-dry-run] [-openspec <dir>] <change1> <change2> [<change3>...]
 
 At least 2 changes required. Writes `links.md` into each change directory and syncs them so a "## Related" section appears in each GitHub issue.
 
+### Spin off emergent work
+
+```
+specsync spinoff -from <slug> -task <n> [-kind bug|followup|task] [-repo owner/name] [-change <slug>] [-dry-run]
+specsync spinoff -from <slug> -text "<discovery>" [-kind bug|followup|task] [-repo owner/name] [-change <slug>] [-dry-run]
+```
+
+Spawns a new linked change from a discovery, keeping the parent scoped. `-task <n>` extracts text from the nth task line in the parent's `tasks.md` and marks it as moved (`[>] moved: <child-slug>`). `-text` provides free-form discovery text. `-kind` sets an issue label on the child. `-repo` for cross-repo spawn. `-change` overrides the auto-derived slug. The child `proposal.md` is seeded with the discovery text and a provenance line linking to the parent.
+
 ### Inspect release impact
 
 ```

README.md

@@ -91,14 +91,15 @@ specsync pull            # pull an issue into a local change
 specsync scan            # what already exists in an area?
 specsync trace           # print the raw spec<->commit<->issue link graph
 specsync link            # cross-link two or more changes
+specsync spinoff         # spawn emergent work as a linked sibling
 specsync release-plan    # shipped changes + advisory semver bump
 specsync changelog       # Keep a Changelog section from shipped changes
 specsync audit           # archived changes vs. merged PRs
 specsync install-skill   # install the bundled agent skill
 specsync version         # print the binary version
 ```
 
-**Dry-run flags** — `sync`, `pull`, and `link` support `-dry-run`. Beads can be
+**Dry-run flags** — `sync`, `pull`, `link`, and `spinoff` support `-dry-run`. Beads can be
 previewed through `specsync -dry-run -provider beads`. `scan`, `trace`,
 `release-plan`, and `changelog` (unless `-apply`) are read-only and do not take
 a dry-run flag.
@@ -156,6 +157,20 @@ specsync link -dry-run slug-a slug-b   # preview links.md + Related sections
 specsync link slug-a slug-b            # write links and update both issues
 ```
 
+### `spinoff` — spawn emergent work as a linked sibling
+
+When a discovery doesn't belong in the current change, spin it off into its own
+scoped change instead of scope-creep:
+
+```bash
+specsync spinoff -from my-change -task 3 -kind bug       # from task 3
+specsync spinoff -from my-change -text "fix X" -dry-run  # free text
+```
+
+Extracts text from the parent's task (or uses `-text`), scaffolds a new change
+with a seeded `proposal.md`, marks the parent task as moved (`[>] moved: <child>`),
+and links the two.
+
 ### `trace` — the raw link graph
 
 Prints the resolved trace graph — changes, commits, issues, and the links
@@ -338,6 +353,20 @@ WorkItem                          ->  issue       (via a pluggable provider)
   reverting un-pushed local progress. Spec still wins task *wording* and order;
   only the checkbox flips. Disable with `-reconcile=false`. Dry runs never read
   or write, so reconcile applies only on real syncs.
+- **Task states** — beyond `[ ]` (todo) and `[x]` (done), tasks.md supports
+  `[~]` (dropped — superseded or removed) and `[>]` (moved — relocated to
+  another change). Dropped and moved tasks are excluded from progress
+  calculations; only todo and done are "live". A compact "Plan changes" footer
+  in the issue body shows the breakdown: `+3 added · 2 done · 1 dropped · 1
+  moved`.
+- **Discoveries** — a `## Discoveries` section captures findings during
+  implementation without requiring scope decisions. Use `specsync note -change
+  <slug> "<text>"` to append a discovery. The section is rendered into the
+  issue and stripped on pull, keeping local and tracker state in sync.
+- **Original ask** — when you `specsync pull` an issue, the original body is
+  saved as `original-ask.md` (write-once, never overwritten). It renders as
+  `## Original ask` in the issue body, providing a stable reference to what was
+  requested before scope evolved.
 - **Stage** — each issue gets a `stage:<stage>` label, derived automatically:
   `active` while any task is unchecked, `complete` once every task is checked
   (before archiving), and `archived` once the change moves under

audit.go

@@ -1,7 +1,6 @@
 package specsync
 
 import (
-	"bufio"
 	"context"
 	"fmt"
 	"os"
@@ -155,19 +154,19 @@ func (r AuditResult) HasUnmerged() bool {
 
 // TaskAuditFinding represents the result of auditing a single change's tasks.
 type TaskAuditFinding struct {
-	Slug          string  // change slug
-	Unchecked     int     // number of unchecked tasks
-	Total         int     // total number of tasks
-	HasCode       bool    // whether code files reference this change
-	CodeRefs      int     // number of code references found
-	Progress      string  // task progress string
-	Stage         string  // current stage
-	Note          string  // additional note (e.g., "spun off", "external repo")
+	Slug      string // change slug
+	Unchecked int    // number of unchecked tasks
+	Total     int    // total number of tasks
+	HasCode   bool   // whether code files reference this change
+	CodeRefs  int    // number of code references found
+	Progress  string // task progress string
+	Stage     string // current stage
+	Note      string // additional note (e.g., "spun off", "external repo")
 }
 
 // TaskAuditResult holds the findings from a task audit run.
 type TaskAuditResult struct {
-	Findings []TaskAuditFinding
+	Findings   []TaskAuditFinding
 	Mismatches []TaskAuditFinding // subset: unchecked tasks but code exists
 }
 
@@ -177,21 +176,21 @@ func AuditTasks(changes []Change) TaskAuditResult {
 	var result TaskAuditResult
 
 	for _, c := range changes {
-		unchecked, total := countTasks(c.TasksMarkdown)
-		if total == 0 {
+		tc := countTaskStates(c.TasksMarkdown)
+		if tc.LiveTotal() == 0 {
 			continue
 		}
 
 		finding := TaskAuditFinding{
 			Slug:      c.Slug,
-			Unchecked: unchecked,
-			Total:     total,
+			Unchecked: tc.Todo,
+			Total:     tc.LiveTotal(),
 			Progress:  string(c.Progress),
 			Stage:     string(c.Stage),
 		}
 
 		// Check for implementation evidence
-		if unchecked > 0 {
+		if tc.Todo > 0 {
 			if hasImplementationEvidence(c.Dir) {
 				finding.HasCode = true
 				finding.CodeRefs = 1
@@ -201,7 +200,7 @@ func AuditTasks(changes []Change) TaskAuditResult {
 		result.Findings = append(result.Findings, finding)
 
 		// Flag as mismatch: unchecked tasks but code exists
-		if unchecked > 0 && finding.HasCode {
+		if tc.Todo > 0 && finding.HasCode {
 			result.Mismatches = append(result.Mismatches, finding)
 		}
 	}
@@ -215,20 +214,6 @@ func (r TaskAuditResult) HasMismatches() bool {
 }
 
 // countTasks returns (unchecked, total) from tasks.md markdown.
-func countTasks(markdown string) (unchecked, total int) {
-	scan := bufio.NewScanner(strings.NewReader(markdown))
-	for scan.Scan() {
-		line := scan.Text()
-		trimmed := strings.TrimSpace(line)
-		if strings.HasPrefix(trimmed, "- [ ]") {
-			unchecked++
-			total++
-		} else if strings.HasPrefix(trimmed, "- [x]") {
-			total++
-		}
-	}
-	return unchecked, total
-}
 
 // hasImplementationEvidence checks for strong evidence that code was written
 // for this change. Relies on .specsync/metadata.json with stage "complete"

beads.go

@@ -254,7 +254,7 @@ func (p *BeadsProvider) create(ctx context.Context, title, description, parent s
 // epicDescription is the proposal body with the identity marker appended — the
 // inverse of what splitBody strips on the way back in.
 func (p *BeadsProvider) epicDescription(item WorkItem) string {
-	proposal, _, _ := splitBody(item.Body, item.Title)
+	proposal, _, _, _, _ := splitBody(item.Body, item.Title)
 	return strings.TrimSpace(proposal) + "\n\n" + marker(item.Slug)
 }
 
@@ -269,7 +269,7 @@ type taskState struct {
 // WorkItem body, reusing the same body splitter and task-line parser the
 // reconcile path uses so child-bead titles match exactly what reconcile keys on.
 func itemTasks(item WorkItem) []taskState {
-	_, tasks, _ := splitBody(item.Body, item.Title)
+	_, tasks, _, _, _ := splitBody(item.Body, item.Title)
 	var out []taskState
 	for _, line := range strings.Split(tasks, "\n") {
 		if text, checked, ok := parseTaskLine(line); ok {

change.go

@@ -20,6 +20,57 @@ const (
 	TaskProgressComplete   TaskProgress = "complete"    // N/N tasks complete
 )
 
+// TaskState represents the state of a single task in tasks.md.
+// [ ] and [x] are live tasks that count toward progress.
+// [~] dropped tasks are superseded or removed — not counted.
+// [>] moved tasks have been migrated to another change — not counted.
+type TaskState int
+
+const (
+	TaskStateTodo    TaskState = iota // [ ]
+	TaskStateDone                     // [x]
+	TaskStateDropped                  // [~]
+	TaskStateMoved                    // [>]
+)
+
+func (s TaskState) String() string {
+	switch s {
+	case TaskStateTodo:
+		return "todo"
+	case TaskStateDone:
+		return "done"
+	case TaskStateDropped:
+		return "dropped"
+	case TaskStateMoved:
+		return "moved"
+	default:
+		return "unknown"
+	}
+}
+
+// TaskCounts summarizes the task states in a tasks.md file.
+type TaskCounts struct {
+	Todo    int
+	Done    int
+	Dropped int
+	Moved   int
+}
+
+// Total returns the total number of tasks including dropped and moved.
+func (c TaskCounts) Total() int {
+	return c.Todo + c.Done + c.Dropped + c.Moved
+}
+
+// LiveTotal returns the total number of live tasks (todo + done, excludes dropped/moved).
+func (c TaskCounts) LiveTotal() int {
+	return c.Todo + c.Done
+}
+
+// IsComplete returns true when all live tasks are done.
+func (c TaskCounts) IsComplete() bool {
+	return c.LiveTotal() > 0 && c.Todo == 0
+}
+
 // Stage is the workflow placement of a change. It is distinct from task progress.
 // Workflow stage can be explicitly set via .specsync/metadata.json or derived
 // from tasks/location.
@@ -69,9 +120,10 @@ func CanonicalStageOrder() []Stage {
 
 // ChangeMetadata holds shared workflow metadata from .specsync/metadata.json.
 type ChangeMetadata struct {
-	Version  int    `json:"version"`
-	Stage    *Stage `json:"stage,omitempty"`
-	Priority *int   `json:"priority,omitempty"`
+	Version           int    `json:"version"`
+	Stage             *Stage `json:"stage,omitempty"`
+	Priority          *int   `json:"priority,omitempty"`
+	BaselineTaskCount *int   `json:"baselineTaskCount,omitempty"`
 }
 
 // StageSource indicates how the current stage was derived.
@@ -94,11 +146,14 @@ type Change struct {
 	Body          string // proposal.md contents
 	TasksMarkdown string // tasks.md contents, may be ""
 	Links         []Ref  // resolved related issue refs from links.md
+	OriginalAsk   string // original-ask.md contents, may be ""
+	Discoveries   string // discoveries.md contents, may be ""
 	Archived      bool
 	Progress      TaskProgress // what the task checklist says
 	Stage         Stage        // current workflow placement
 	StageSource   StageSource  // how we arrived at Stage (default/tasks/metadata/legacy-status/folder)
 	Priority      *int         // optional 1-100; nil if unset
+	BaselineTasks *int         // task count at time of pull; nil if unknown
 }
 
 // LoadChanges reads every change under <openspecDir>/changes, including those
@@ -169,6 +224,16 @@ func LoadChange(dir string, archived bool, openspecDir string) (*Change, error)
 	if tasks, err := os.ReadFile(filepath.Join(dir, "tasks.md")); err == nil {
 		c.TasksMarkdown = string(tasks)
 	}
+	if ask, err := os.ReadFile(filepath.Join(dir, "original-ask.md")); err == nil {
+		c.OriginalAsk = string(ask)
+	}
+	if disc, err := os.ReadFile(filepath.Join(dir, "discoveries.md")); err == nil {
+		c.Discoveries = string(disc)
+	}
+	// Load baseline task count from metadata.json (set on pull).
+	if meta, err := LoadChangeMetadata(dir); err == nil && meta != nil && meta.BaselineTaskCount != nil {
+		c.BaselineTasks = meta.BaselineTaskCount
+	}
 
 	if err := refreshState(c); err != nil {
 		return nil, fmt.Errorf("load state for %s: %w", slug, err)
@@ -308,36 +373,15 @@ func refFromURL(url string) *Ref {
 // the "- [ ]"/"- [x]" lines reconcile does — other checkbox markers (living
 // plan's [~]/[>]) and prose are ignored. An empty or task-less list is not
 // "complete": there is nothing to have finished.
-// CountCheckboxes returns (total, completed) checkbox counts from markdown.
+// CountCheckboxes returns (liveTotal, completed) checkbox counts from markdown.
+// Only [ ] and [x] tasks are counted; [~] (dropped) and [>] (moved) are excluded.
 func CountCheckboxes(md string) (total, completed int) {
-	if strings.TrimSpace(md) == "" {
-		return 0, 0
-	}
-	for _, line := range strings.Split(md, "\n") {
-		if _, checked, ok := parseTaskLine(line); ok {
-			total++
-			if checked {
-				completed++
-			}
-		}
-	}
-	return total, completed
+	c := countTaskStates(md)
+	return c.LiveTotal(), c.Done
 }
 
 func tasksComplete(md string) bool {
-	if strings.TrimSpace(md) == "" {
-		return false
-	}
-	any := false
-	for _, line := range strings.Split(md, "\n") {
-		if _, checked, ok := parseTaskLine(line); ok {
-			if !checked {
-				return false
-			}
-			any = true
-		}
-	}
-	return any
+	return countTaskStates(md).IsComplete()
 }
 
 // refreshStage derives lifecycle from the change's current task state, then

cmd/specsync/SKILL.md

@@ -28,6 +28,10 @@ specsync [-dry-run] [-change <change>] [-repo owner/name] [-reconcile=false] [-c
 - `-close-completed` (default false): keep tracker open/closed state aligned with completion. Completing every task closes the item; adding new unchecked work reopens it. Without the flag, completion updates `stage:complete` but leaves tracker state alone. An explicit `.status` overrides task-derived stage, so only `.status` value `complete` closes with this flag.
 - `-repo owner/name`: override auto-detected repo from `git remote`.
 
+**Task states.** Beyond `[ ]` (todo) and `[x]` (done), tasks.md supports `[~]` (dropped — superseded or removed) and `[>]` (moved — relocated to another change). Dropped and moved tasks are excluded from progress; only todo and done are "live". The issue body shows a "Plan changes" footer with the breakdown: `+3 added · 2 done · 1 dropped · 1 moved`.
+
+**Discoveries.** Capture findings during implementation without scope decisions. `specsync note -change <slug> "<text>"` appends a line to `discoveries.md`, rendered as `## Discoveries` in the issue. On pull, the section is stripped (like `## Tasks`). The original issue body is saved as `original-ask.md` on first pull (write-once, never overwritten) and rendered as `## Original ask`.
+
 **Lifecycle stages.** specsync labels each issue `stage:<stage>`. The stage is derived automatically: `active` while any task is unchecked, `complete` once every task is checked (before archiving), and `archived` once the change moves under `changes/archive/`. A `.status` file in the change folder overrides the derived stage. This means finishing the last task flips the issue out of `stage:active` on the next sync — no manual bookkeeping.
 
 ### Pull an issue into a local change
@@ -70,6 +74,15 @@ specsync link [-dry-run] [-openspec <dir>] <change1> <change2> [<change3>...]
 
 At least 2 changes required. Writes `links.md` into each change directory and syncs them so a "## Related" section appears in each GitHub issue.
 
+### Spin off emergent work
+
+```
+specsync spinoff -from <slug> -task <n> [-kind bug|followup|task] [-repo owner/name] [-change <slug>] [-dry-run]
+specsync spinoff -from <slug> -text "<discovery>" [-kind bug|followup|task] [-repo owner/name] [-change <slug>] [-dry-run]
+```
+
+Spawns a new linked change from a discovery, keeping the parent scoped. `-task <n>` extracts text from the nth task line in the parent's `tasks.md` and marks it as moved (`[>] moved: <child-slug>`). `-text` provides free-form discovery text. `-kind` sets an issue label on the child. `-repo` for cross-repo spawn. `-change` overrides the auto-derived slug. The child `proposal.md` is seeded with the discovery text and a provenance line linking to the parent.
+
 ### Inspect release impact
 
 ```