devrites 7.3.3 → 7.3.5

package/engine/internal/lib/frontier_roadmap.go

@@ -0,0 +1,168 @@
+package lib
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/markdowntext"
+)
+
+// frontierCanonicalRoadmap reads current authority from the full related sequence.
+// A nil map without an error leaves headerless historical maps to legacy parsing.
+func frontierCanonicalRoadmap(nodes map[string]*frontierWorkspace, ordered []string) (mapping map[int]string, artifacts []string, err error) {
+	var owner *frontierWorkspace
+	var lines []string
+	for _, slug := range ordered {
+		n := nodes[slug]
+		if n == nil || n.dir == "" {
+			continue
+		}
+		path := filepath.Join(n.dir, "roadmap.md")
+		raw, readErr := readBoundedRegularFile(path, workspaceArtifactLimit)
+		if os.IsNotExist(readErr) {
+			continue
+		}
+		if readErr != nil {
+			return nil, append(artifacts, path), fmt.Errorf("roadmap %s unreadable: %w", path, readErr)
+		}
+		structural, parseErr := markdowntext.Structural(raw)
+		if parseErr != nil {
+			return nil, append(artifacts, path), fmt.Errorf("roadmap %s malformed: %w", path, parseErr)
+		}
+		candidate := strings.Split(string(structural), "\n")
+		explicit := false
+		for _, line := range candidate {
+			line = strings.TrimSpace(line)
+			if strings.HasPrefix(line, "Sequence root:") || strings.HasPrefix(line, "Decision:") {
+				explicit = true
+				break
+			}
+		}
+		if !explicit {
+			continue
+		}
+		artifacts = append(artifacts, path)
+		if owner != nil {
+			return nil, artifacts, fmt.Errorf("multiple canonical roadmap owners: %s and %s", owner.slug, slug)
+		}
+		owner, lines = n, candidate
+	}
+	if owner == nil {
+		return nil, nil, nil
+	}
+	root, decision := "", ""
+	rootCount, decisionCount := 0, 0
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if value, ok := strings.CutPrefix(line, "Sequence root:"); ok {
+			root, rootCount = strings.TrimSpace(value), rootCount+1
+		}
+		if value, ok := strings.CutPrefix(line, "Decision:"); ok {
+			decision, decisionCount = strings.TrimSpace(value), decisionCount+1
+		}
+	}
+	if rootCount != 1 || decisionCount != 1 || !devritespaths.ValidSlug(root) || strings.ContainsAny(root, " \t") || strings.HasPrefix(root, "-") {
+		return nil, artifacts, fmt.Errorf("canonical roadmap requires one valid Sequence root and Decision header")
+	}
+	if len(decision) != 7 || !strings.HasPrefix(decision, "DEC-") || strings.Trim(decision[4:], "0123456789") != "" {
+		return nil, artifacts, fmt.Errorf("canonical roadmap Decision must be DEC-NNN")
+	}
+	decisionPath := filepath.Join(owner.dir, "decisions.md")
+	artifacts = append(artifacts, decisionPath)
+	raw, readErr := readBoundedRegularFile(decisionPath, workspaceArtifactLimit)
+	if readErr != nil {
+		return nil, artifacts, fmt.Errorf("canonical roadmap decision unreadable: %w", readErr)
+	}
+	structural, parseErr := markdowntext.Structural(raw)
+	if parseErr != nil {
+		return nil, artifacts, fmt.Errorf("canonical roadmap decision malformed: %w", parseErr)
+	}
+	headings := 0
+	for _, line := range strings.Split(string(structural), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) >= 2 && fields[0] == "##" && fields[1] == decision {
+			headings++
+		}
+	}
+	if headings != 1 {
+		return nil, artifacts, fmt.Errorf("canonical roadmap Decision %s requires one exact owner-local heading, found %d", decision, headings)
+	}
+	mapping = map[int]string{}
+	positions := map[string]int{}
+	tables := 0
+	for i := 0; i < len(lines); i++ {
+		cells := frontierCells(lines[i])
+		if len(cells) != 0 && (len(cells) != 2 || cells[0] != "Position" || cells[1] != "Workspace") {
+			return nil, artifacts, fmt.Errorf("canonical roadmap contains an unexpected table")
+		}
+		if len(cells) != 2 || cells[0] != "Position" || cells[1] != "Workspace" {
+			continue
+		}
+		tables++
+		if tables != 1 || i+1 >= len(lines) {
+			return nil, artifacts, fmt.Errorf("canonical roadmap requires exactly one Position/Workspace table")
+		}
+		separator := frontierCells(lines[i+1])
+		if len(separator) != 2 {
+			return nil, artifacts, fmt.Errorf("canonical roadmap table separator malformed")
+		}
+		for _, cell := range separator {
+			if len(strings.Trim(cell, ":")) < 3 || strings.Trim(cell, "-:") != "" {
+				return nil, artifacts, fmt.Errorf("canonical roadmap table separator malformed")
+			}
+		}
+		i += 2
+		for ; i < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i]), "|"); i++ {
+			row := frontierCells(lines[i])
+			if len(row) != 2 {
+				return nil, artifacts, fmt.Errorf("canonical roadmap table row malformed")
+			}
+			position, numberErr := strconv.Atoi(row[0])
+			slug := row[1]
+			if numberErr != nil || position != len(mapping)+1 || strconv.Itoa(position) != row[0] {
+				return nil, artifacts, fmt.Errorf("canonical roadmap positions must be unique and contiguous from 1")
+			}
+			if !devritespaths.ValidSlug(slug) || strings.ContainsAny(slug, " \t") || strings.HasPrefix(slug, "-") || positions[slug] != 0 {
+				return nil, artifacts, fmt.Errorf("canonical roadmap requires unique valid workspace slugs")
+			}
+			mapping[position], positions[slug] = slug, position
+		}
+		i--
+	}
+	if tables != 1 || len(mapping) == 0 || mapping[1] != root {
+		return nil, artifacts, fmt.Errorf("canonical roadmap requires one nonempty table rooted at Sequence root")
+	}
+	for _, slug := range ordered {
+		n := nodes[slug]
+		chain, chainErr := frontierChain(nodes, slug)
+		if chainErr != nil {
+			return nil, artifacts, fmt.Errorf("canonical roadmap recorded chain invalid: %w", chainErr)
+		}
+		if chain[len(chain)-1] != root {
+			return nil, artifacts, fmt.Errorf("canonical roadmap root %s does not match actual chain anchor", root)
+		}
+		position := positions[slug]
+		if position == 0 || n.hasPosition && n.position != position {
+			return nil, artifacts, fmt.Errorf("canonical roadmap conflicts with recorded position for %s", slug)
+		}
+		if n.parent != mapping[position-1] {
+			return nil, artifacts, fmt.Errorf("canonical roadmap conflicts with recorded predecessor for %s", slug)
+		}
+		if target := frontierSpecTarget(n); target != "" && mapping[position+1] != target {
+			return nil, artifacts, fmt.Errorf("canonical roadmap conflicts with next Spec for %s", slug)
+		}
+	}
+	for _, slug := range mapping {
+		if n := nodes[slug]; n != nil {
+			position := positions[slug]
+			if n.problem != nil || n.hasPosition && n.position != position || n.parent != mapping[position-1] {
+				return nil, artifacts, fmt.Errorf("canonical roadmap workspace %s is not bound to its recorded sequence position", slug)
+			}
+		}
+	}
+	return mapping, artifacts, nil
+}

package/engine/internal/lib/handoff.go

@@ -89,12 +89,9 @@ func RunHandoff(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stdout, "missing_required: %s\n", strings.Join(report.MissingFiles, ", "))
 	}
 	fmt.Fprintf(stdout, "read_next: %s\n", strings.Join(readNext(featureDir), ", "))
-	verdict, err := classifyContinuation(root, slug)
-	if err != nil {
-		fmt.Fprintf(stderr, "handoff: continuation: %v\n", err)
-		return 2
+	if code := RunCheckContinuation(root, []string{slug}, stdout, stderr); code != 0 {
+		return code
 	}
-	writeContinuation(stdout, verdict)
 	if resume {
 		recordMetric(root, slug, string(report.Phase), "resume", "root", 0)
 	}

package/engine/internal/lib/next.go

@@ -73,6 +73,25 @@ func RunNext(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stdout, "blocked: %s\n", unattributedMessage(slug, flagged))
 		exit = 3
 	}
+	if afkPresent(root) {
+		lines, err := FrontierLines(root, slug)
+		if err != nil {
+			fmt.Fprintf(stderr, "next: frontier: %v\n", err)
+			return 2
+		}
+		for _, line := range lines {
+			fmt.Fprintln(stdout, line)
+		}
+		mode, err := autocompleteMode(root)
+		if err != nil {
+			fmt.Fprintf(stderr, "next: %v\n", err)
+			return 2
+		}
+		if mode && frontierGlobalPriority(slug, lines) {
+			fmt.Fprintln(stdout, "next-command: /rite-autocomplete")
+			return exit
+		}
+	}
 	if report.Phase == state.PhaseBuild {
 		printPlanBatch(stdout, root, slug)
 	}

package/engine/internal/parallel/cli.go

@@ -73,6 +73,10 @@ func runPathDisjoint(args []string, stdin io.Reader, stdout, stderr io.Writer) i
 	return ExitOK
 }
 
+// FrontierNotices exposes related work without broadening source-local selection.
+// main wires it from lib to avoid an import cycle.
+var FrontierNotices func(root, slug string) ([]string, error)
+
 func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	root := ""
 	slug := ""
@@ -148,21 +152,18 @@ func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 			return ExitUsage
 		}
 		if sawWorkspaces {
-			order := []string{slug}
+			order := strings.Split(workspaces, ",")
 			seen := make(map[string]bool)
 			if err := validateSlug(slug); err != nil {
 				fmt.Fprintf(stderr, "parallel select: %v\n", err)
 				return ExitUsage
 			}
-			for _, target := range strings.Split(workspaces, ",") {
+			for _, target := range order {
 				if err := validateSlug(target); err != nil || seen[target] {
 					fmt.Fprintf(stderr, "parallel select: invalid or duplicate workspace %q\n", target)
 					return ExitUsage
 				}
 				seen[target] = true
-				if target != slug {
-					order = append(order, target)
-				}
 			}
 			if _, err := controllerLease(root, slug); err != nil {
 				fmt.Fprintf(stderr, "parallel select: %v\n", err)
@@ -199,6 +200,16 @@ func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 				slices = append(slices, ready...)
 			}
 		} else {
+			if FrontierNotices != nil {
+				notices, err := FrontierNotices(root, slug)
+				for _, notice := range notices {
+					fmt.Fprintln(stderr, notice)
+				}
+				if err != nil {
+					fmt.Fprintf(stderr, "parallel select: frontier: %v\n", err)
+					return ExitBlocked
+				}
+			}
 			if PlanReady == nil {
 				fmt.Fprintln(stderr, "parallel select: --from-plan is unavailable in this build")
 				return ExitBlocked

package/engine/internal/parallel/ops.go

@@ -217,8 +217,8 @@ type AddOpts struct {
 	Capacity int
 }
 
-// Add refills freed slots of a running lease: each new slice gets a worktree
-// from the current control tip, under the same path-disjoint and cap rules as
+// Add refills freed slots of a running, integrate-failed, or complete lease:
+// each new slice gets a worktree from the current control tip, under the same path-disjoint and cap rules as
 // the slices still active. Landed (integrated) slices no longer claim paths.
 // An explicit Capacity with no Slices changes only the bound, not lease status.
 func Add(opts AddOpts) (lease *Lease, err error) {
@@ -262,8 +262,8 @@ func addLocked(opts AddOpts) (*Lease, error) {
 	if opts.Capacity == 0 {
 		opts.Capacity = leaseCapacity(lease)
 	}
-	if lease.Status != StatusRunning && lease.Status != StatusComplete {
-		return nil, fmt.Errorf("add requires status=running|complete (have %s)", lease.Status)
+	if lease.Status != StatusRunning && lease.Status != StatusIntegrateFailed && lease.Status != StatusComplete {
+		return nil, fmt.Errorf("add requires status=running|integrate-failed|complete (have %s)", lease.Status)
 	}
 	head, err := revParse(opts.Root, expectedControl(lease))
 	if err != nil {
@@ -329,7 +329,9 @@ func addLocked(opts AddOpts) (*Lease, error) {
 	lease.Slices = append(lease.Slices, made...)
 	lease.N = len(lease.Slices)
 	lease.Capacity = opts.Capacity
-	lease.Status = StatusRunning
+	if lease.Status == StatusComplete {
+		lease.Status = StatusRunning
+	}
 	if err := WriteLease(leasePath, lease); err != nil {
 		rollback()
 		return nil, err

package/engine/internal/parallel/repository.go

@@ -167,6 +167,29 @@ func controllerLease(root, controller string) (*repositoryLease, error) {
 	return found, nil
 }
 
+// ControllerLease returns the retained repository controller without changing its lease.
+// A lease in another checkout requires recovery at that explicit control root.
+// Recorded checkout/ref identity must still match; legacy leases lack that evidence.
+// Active reservations must remain path-disjoint; integrated history holds no slot.
+func ControllerLease(repoRoot string) (string, *Lease, error) {
+	found, err := controllerLease(repoRoot, "")
+	if err != nil || found == nil {
+		return "", nil, err
+	}
+	if found.root != resolvedPath(repoRoot) {
+		return "", nil, fmt.Errorf("repository controller lease retained by %s at %s; recover at its explicit root", found.controller, found.root)
+	}
+	if err := ensureControllerIdentity(repoRoot, found.lease); err != nil {
+		return "", nil, err
+	}
+	if active := activeSlices(found.lease); len(active) >= 2 {
+		if _, err := CheckPathDisjoint(active, repoRoot); err != nil {
+			return "", nil, err
+		}
+	}
+	return found.controller, found.lease, nil
+}
+
 // WorkspaceLeased protects both controller and source workspaces until cleanup.
 // devritesRoot is explicit; closeout holds WithControlLock through its rename.
 func WorkspaceLeased(devritesRoot, workspace string) (bool, error) {

package/engine/internal/release/release.go

@@ -16,10 +16,12 @@ import (
 	"net/netip"
 	"net/url"
 	"os"
+	"os/exec"
 	"path"
 	"path/filepath"
 	"regexp"
 	"runtime"
+	"strconv"
 	"strings"
 	"time"
 )
@@ -162,13 +164,13 @@ func binaryNameFor(goos, goarch string) (string, error) {
 }
 
 func fetchJSON(ctx context.Context, rawURL string, out any) error {
-	resp, err := get(ctx, rawURL)
+	resp, err := get(ctx, rawURL, true)
 	if err != nil {
 		return err
 	}
 	defer func() { _ = resp.Body.Close() }()
 	if resp.StatusCode < 200 || resp.StatusCode > 299 {
-		return fmt.Errorf("%s returned %s", resp.Request.URL.Redacted(), resp.Status)
+		return responseError(resp)
 	}
 	if resp.ContentLength > maxJSONBytes {
 		return fmt.Errorf("JSON response exceeds %d bytes", maxJSONBytes)
@@ -228,13 +230,13 @@ func downloadVerified(ctx context.Context, rawURL, destination, filename string,
 }
 
 func download(ctx context.Context, rawURL, destination string, maxBytes int64, mode fs.FileMode) error {
-	resp, err := get(ctx, rawURL)
+	resp, err := get(ctx, rawURL, false)
 	if err != nil {
 		return err
 	}
 	defer func() { _ = resp.Body.Close() }()
 	if resp.StatusCode < 200 || resp.StatusCode > 299 {
-		return fmt.Errorf("%s returned %s", resp.Request.URL.Redacted(), resp.Status)
+		return responseError(resp)
 	}
 	if resp.ContentLength > maxBytes {
 		return fmt.Errorf("download exceeds %d bytes", maxBytes)
@@ -274,7 +276,7 @@ func download(ctx context.Context, rawURL, destination string, maxBytes int64, m
 	return nil
 }
 
-func get(ctx context.Context, rawURL string) (*http.Response, error) {
+func get(ctx context.Context, rawURL string, authenticate bool) (*http.Response, error) {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("build release request: %w", err)
@@ -284,9 +286,94 @@ func get(ctx context.Context, rawURL string) (*http.Response, error) {
 	}
 	req.Header.Set("Accept", "application/vnd.github+json")
 	req.Header.Set("User-Agent", "devrites-engine")
+	if authenticate && isGitHubAPI(req.URL) {
+		token, err := githubToken(ctx)
+		if err != nil {
+			return nil, err
+		}
+		if token != "" {
+			req.Header.Set("Authorization", "Bearer "+token)
+		}
+	}
 	return httpClient.Do(req)
 }
 
+func isGitHubAPI(u *url.URL) bool {
+	return u != nil && u.User == nil && strings.EqualFold(u.Scheme, "https") &&
+		(strings.EqualFold(u.Host, "api.github.com") || strings.EqualFold(u.Host, "api.github.com:443"))
+}
+
+// credentialOutput bounds untrusted helper output without accepting a truncated token.
+type credentialOutput struct {
+	data [4096]byte
+	n    int
+}
+
+func (out *credentialOutput) Write(p []byte) (int, error) {
+	if len(p) > len(out.data)-out.n {
+		return 0, errors.New("GitHub credential helper output exceeds limit")
+	}
+	out.n += copy(out.data[out.n:], p)
+	return len(p), nil
+}
+
+// githubToken follows gh's environment precedence without requiring gh to be installed.
+func githubToken(ctx context.Context) (string, error) {
+	token := os.Getenv("GH_TOKEN")
+	if token == "" {
+		token = os.Getenv("GITHUB_TOKEN")
+	}
+	if token == "" {
+		lookupCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
+		defer cancel()
+		cmd := exec.CommandContext(lookupCtx, "gh", "auth", "token", "--hostname", "github.com")
+		cmd.Env = append(os.Environ(), "GH_PROMPT_DISABLED=1", "GIT_TERMINAL_PROMPT=0")
+		cmd.Stderr = io.Discard
+		cmd.WaitDelay = 100 * time.Millisecond
+		var output credentialOutput
+		cmd.Stdout = &output
+		err := cmd.Run()
+		if ctx.Err() != nil {
+			return "", ctx.Err()
+		}
+		if err != nil {
+			return "", nil
+		}
+		token = strings.TrimSpace(string(output.data[:output.n]))
+	}
+	for _, char := range token {
+		if char < '!' || char > '~' {
+			return "", errors.New("invalid GitHub credential; check GH_TOKEN, GITHUB_TOKEN, or gh auth login --hostname github.com")
+		}
+	}
+	return token, nil
+}
+
+func responseError(resp *http.Response) error {
+	message := fmt.Sprintf("release request returned HTTP %d %s", resp.StatusCode, http.StatusText(resp.StatusCode))
+	switch resp.StatusCode {
+	case http.StatusUnauthorized, http.StatusForbidden:
+		message += "; check GH_TOKEN/GITHUB_TOKEN (environment tokens take precedence) or run gh auth login --hostname github.com"
+	case http.StatusTooManyRequests:
+		message += "; GitHub API rate limit reached; use GH_TOKEN/GITHUB_TOKEN or gh auth login --hostname github.com, or wait before retrying"
+	}
+	if resp.StatusCode == http.StatusForbidden && resp.Header.Get("X-RateLimit-Remaining") == "0" {
+		message += "; GitHub API rate limit reached"
+	}
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden || resp.StatusCode == http.StatusTooManyRequests {
+		if reset, err := strconv.ParseInt(resp.Header.Get("X-RateLimit-Reset"), 10, 64); err == nil && reset >= 0 && reset <= 253402300799 {
+			message += "; rate limit resets at " + time.Unix(reset, 0).UTC().Format(time.RFC3339)
+		}
+		retry := resp.Header.Get("Retry-After")
+		if seconds, err := strconv.ParseUint(retry, 10, 32); err == nil {
+			message += fmt.Sprintf("; retry after %d seconds", seconds)
+		} else if date, err := http.ParseTime(retry); err == nil {
+			message += "; retry after " + date.UTC().Format(time.RFC3339)
+		}
+	}
+	return errors.New(message)
+}
+
 func validateURL(u *url.URL) error {
 	if u == nil || u.Hostname() == "" {
 		return errors.New("release URL has no host")
@@ -303,6 +390,10 @@ func validateURL(u *url.URL) error {
 }
 
 func checkRedirect(req *http.Request, via []*http.Request) error {
+	// net/http forwards sensitive headers to subdomains; GitHub tokens must not follow.
+	if !isGitHubAPI(req.URL) {
+		req.Header.Del("Authorization")
+	}
 	if len(via) >= 10 {
 		return errors.New("stopped after 10 redirects")
 	}

package/engine/main.go

@@ -26,6 +26,7 @@ Usage:
   devrites-engine install [flags]          Install DevRites skills, agents, and host configuration
   devrites-engine update [flags]           Update an existing DevRites install in place
   devrites-engine uninstall [flags]        Remove a DevRites install, preserving runtime state
+  devrites-engine frontier [slug]          Discover related ready work and native preparation without writes
   devrites-engine check candidate <slug>   Validate and hash the closed project candidate
   devrites-engine check readiness <slug>   Check required files, tasks.md graph, and Build-input binding
   devrites-engine check readiness --emit-binding <slug>  Emit the stable Build-input binding for Vet
@@ -126,6 +127,7 @@ func init() {
 	// parallel cannot import lib (lib imports it), so `parallel select --from-plan` gets the plan-derived ready set through this hook.
 	parallel.PlanReady = lib.PlanReady
 	parallel.WorkspaceReady = lib.WorkspaceReady
+	parallel.FrontierNotices = lib.FrontierNotices
 	// `gates precheck` runs `check windows` through this hook for the same reason.
 	acceptance.WindowsCheck = lib.RunCheckWindows
 	// ...and `gates precheck --slice` learns which writer gates to skip.
@@ -169,6 +171,8 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return cmdOrient(root, args[1:], stdout, stderr)
 	case "next":
 		return lib.RunNext(root, args[1:], stdout, stderr)
+	case "frontier":
+		return lib.RunFrontier(root, args[1:], stdout, stderr)
 	case "handoff":
 		return lib.RunHandoff(root, args[1:], stdout, stderr)
 	case "recall":