devrites 7.3.4 → 7.3.6

package/engine/internal/lib/context.go

@@ -40,7 +40,7 @@ type loadsManifest struct {
 
 const loadsMarker = "<!-- loads:"
 
-const contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--slice <SLICE-###>] [--recheck <inventory>] [--trigger a,b] [--inline-contract] [--whole] [--skills-root <dir>] [--out <path>]
+const contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--prepare-for <parent-source> | --sequence-research] [--slice <SLICE-###>] [--recheck <inventory>] [--trigger a,b] [--inline-contract] [--whole] [--skills-root <dir>] [--out <path>]
 
 Emits one deduplicated context bundle for a phase or standalone skill
 (+ optional dispatch role) into .devrites/work/<slug>/ctx/ so an agent
@@ -65,6 +65,12 @@ build or autocomplete bundle (no --role, no --slice) defaults to --slice
 bounded recheck bundle: the inventory file (relative to the workspace)
 and core.md are inlined; every other pack file becomes a by-reference
 index plus the sections the inventory cites as "<file>.md § <heading>".
+Autocomplete at effective cap>1 gates Temper/Define/Plan/Vet bundles, including
+--skill rite-<phase>, on immediate-successor preparation before writing.
+--prepare-for binds native preparation to its exact immediate parent; roleless
+controlling-root context is allowed. --sequence-research permits only exact
+evidence-scout investigation of sequence authority. Neither creates an account
+or grants product-write authority; research does not satisfy successor preparation.
 `
 
 // coreStandard is the universal floor every bundle inlines whole.
@@ -73,12 +79,27 @@ const coreStandard = "devrites-lib/reference/standards/core.md"
 // RunContext emits one deduplicated context bundle for a phase (+ optional
 // dispatch role) so an agent reads a single file instead of selecting files.
 //
-//	context <slug> --phase <p> [--role <r>] [--slice <SLICE-###>] [--recheck <inventory>] [--trigger a,b] [--skills-root <dir>] [--out <path>]
+//	context <slug> --phase <p> [--role <r>] [--prepare-for <parent-source> | --sequence-research] [--slice <SLICE-###>] [--recheck <inventory>] [--trigger a,b] [--skills-root <dir>] [--out <path>]
 func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 	opts, code := parseContextArgs(args, stderr)
 	if code != 0 {
 		return code
 	}
+	phase := opts.phase
+	if opts.skill != "" {
+		phase = ""
+		if strings.HasPrefix(opts.skill, "rite-") {
+			phase = strings.TrimPrefix(opts.skill, "rite-")
+		}
+	}
+	var roles []string
+	if opts.role != "" {
+		roles = []string{opts.role}
+	}
+	if err := opts.purpose.validate(phase, roles, true); err != nil {
+		fmt.Fprintf(stderr, "context: %v\n", err)
+		return 2
+	}
 	// A Build reviewer judges one slice; an unscoped bundle inlines whole
 	// plan/tasks/architecture into every dispatch.
 	if opts.phase == "build" && opts.role != "" && roleBase(opts.role) != "slice-wright" && opts.slice == "" {
@@ -94,6 +115,19 @@ func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 			return 2
 		}
 	}
+	if opts.slug != "" {
+		notices, err := preparationAdmission(root, opts.slug, phase, opts.purpose, nil)
+		if err != nil {
+			fmt.Fprintf(stderr, "context: BLOCKED: %v\n", err)
+			return 3
+		}
+		for _, notice := range notices {
+			fmt.Fprintln(stdout, notice)
+		}
+	} else if opts.purpose.parent != "" || opts.purpose.research {
+		fmt.Fprintln(stderr, "context: preparation purpose requires an exact existing source")
+		return 2
+	}
 	sources := contextSources{dir: featureDir}
 	// One active slice per bundle, except a parallel batch: the root has to
 	// see the other slices to start them. Whole tasks/plan/decisions ride
@@ -791,6 +825,7 @@ type contextOpts struct {
 	recheck        string
 	inlineContract bool
 	whole          bool
+	purpose        preparationPurpose
 }
 
 func parseContextArgs(args []string, stderr io.Writer) (contextOpts, int) {
@@ -799,6 +834,19 @@ func parseContextArgs(args []string, stderr io.Writer) (contextOpts, int) {
 	for i := 0; i < len(args); i++ {
 		value := argAt(args, i+1)
 		switch args[i] {
+		case "--prepare-for":
+			if opts.purpose.parent != "" {
+				fmt.Fprintln(stderr, "context: duplicate --prepare-for")
+				return opts, 2
+			}
+			if value == "" || strings.HasPrefix(value, "-") {
+				fmt.Fprintln(stderr, "context: --prepare-for requires a parent source")
+				return opts, 2
+			}
+			opts.purpose.parent = value
+		case "--sequence-research":
+			opts.purpose.research = true
+			continue
 		case "--phase":
 			opts.phase = value
 		case "--skill":

package/engine/internal/lib/continuation.go

@@ -40,6 +40,11 @@ func RunCheckContinuation(root string, args []string, stdout, stderr io.Writer)
 		}
 		return code
 	}
+	mode, err := autocompleteMode(root)
+	if err != nil {
+		fmt.Fprintf(stderr, "check continuation: %v\n", err)
+		return 2
+	}
 	verdict, err := classifyContinuation(root, slug)
 	if err != nil {
 		fmt.Fprintf(stderr, "check continuation: %v\n", err)
@@ -52,8 +57,10 @@ func RunCheckContinuation(root string, args []string, stdout, stderr io.Writer)
 			fmt.Fprintf(stderr, "check continuation: frontier: %v\n", err)
 			return 2
 		}
-		if !verdict.Required && len(frontier) > 0 && frontier[0] == "frontier: actionable" {
+		if mode && frontierGlobalPriority(slug, frontier) || !mode && !verdict.Required && len(frontier) > 0 && frontier[0] == "frontier: actionable" {
 			verdict = continuationVerdict{Required: true, Invoke: "/rite-autocomplete", Source: slug, Reason: "global frontier requires native preparation, authority review, or selection; no Ship approval"}
+		} else if mode && frontierSourcePreparationWait(slug, frontier) {
+			verdict = continuationVerdict{Reason: frontierInheritedPreparationWait}
 		}
 	}
 	writeContinuation(stdout, verdict)

package/engine/internal/lib/dispatch.go

@@ -27,9 +27,9 @@ import (
 // fan-out cannot silently degrade to serial (open -> every role started ->
 // seal -> returns -> complete). start/return also auto-record metrics events.
 //
-//	devrites-engine dispatch <slug> <sub> [--phase p] [--wave w] [--role r] [--handle h] [--reason s] [--slice SLICE-###] [--reslice-review <DRIFT-ID>] [--contract <file>] [--packet <file>] [--outcome findings|no-findings|gap] [--result <file>] [--all] [--claim-session <id> --claim <path>... [--claim-ttl <minutes>]] [--release] [--path <path>...]
+//	devrites-engine dispatch <slug> <sub> [--phase p] [--wave w] [--role r] [--prepare-for <parent-source> | --sequence-research] [--handle h] [--reason s] [--slice SLICE-###] [--reslice-review <DRIFT-ID>] [--contract <file>] [--packet <file>] [--outcome findings|no-findings|gap] [--result <file>] [--all] [--claim-session <id> --claim <path>... [--claim-ttl <minutes>]] [--release] [--path <path>...]
 
-const dispatchUsage = `usage: devrites-engine dispatch <slug> <open|start|seal|return|status|abandon|attribute> [--phase p] [--wave w] [--role r] [--handle h] [--reason s] [--slice SLICE-###] [--reslice-review <DRIFT-ID>] [--contract <file>] [--packet <file>] [--outcome findings|no-findings|gap] [--result <file>] [--all] [--claim-session <id> --claim <path>... [--claim-ttl <minutes>]] [--release] [--path <path>...]
+const dispatchUsage = `usage: devrites-engine dispatch <slug> <open|start|seal|return|status|abandon|attribute> [--phase p] [--wave w] [--role r] [--prepare-for <parent-source> | --sequence-research] [--handle h] [--reason s] [--slice SLICE-###] [--reslice-review <DRIFT-ID>] [--contract <file>] [--packet <file>] [--outcome findings|no-findings|gap] [--result <file>] [--all] [--claim-session <id> --claim <path>... [--claim-ttl <minutes>]] [--release] [--path <path>...]
 
 Wave barrier for parallel agent dispatch: seal fails until every declared
 role has a distinct handle; return fails before seal. The start that gives
@@ -40,6 +40,12 @@ completes the wave releases it, and abandon keeps it unless --release (any
 host-confirmed terminal path without a completing return, such as a stop or a
 refused launch). Wave IDs are single-use, including abandoned waves; retries
 need a fresh ID and never inherit or release an earlier wave's claim.
+Autocomplete at effective cap>1 checks immediate-successor preparation before
+ordinary Temper/Define/Plan/Vet open writes. Open-only --prepare-for binds allowed
+native preparation roles to an exact immediate parent without recursively
+requiring another successor. Open-only --sequence-research admits exact
+evidence-scout authority investigation, never successor preparation or writers.
+Both require an existing source and persist their purpose on the wave.
 Native starts, returns and abandonment retain subsecond timestamps. abandon
 --release also retains host-terminal confirmation, even without a claim or when
 its owned claim was already released; a failed release does not certify termination.
@@ -105,18 +111,22 @@ type dispatchFile struct {
 }
 
 type dispatchWave struct {
-	Phase           string                   `json:"phase"`
-	State           string                   `json:"state"` // open, sealed, abandoned, complete
-	Reason          string                   `json:"reason,omitempty"`
-	AbandonedAt     string                   `json:"abandoned_at,omitempty"`
-	TerminalAt      string                   `json:"terminal_at,omitempty"`
-	Roles           map[string]*dispatchRole `json:"roles"`
-	Slices          []string                 `json:"slices,omitempty"`
-	ResliceReview   string                   `json:"reslice_review,omitempty"`
-	ResliceReviewed []string                 `json:"reslice_reviewed,omitempty"`
-	Claim           string                   `json:"claim,omitempty"`
-	ClaimSession    string                   `json:"claim_session,omitempty"`
-	Tree            string                   `json:"tree,omitempty"` // work tree at a build wright open, for check windows --since-dispatch
+	Phase            string                   `json:"phase"`
+	State            string                   `json:"state"` // open, sealed, abandoned, complete
+	Reason           string                   `json:"reason,omitempty"`
+	AbandonedAt      string                   `json:"abandoned_at,omitempty"`
+	TerminalAt       string                   `json:"terminal_at,omitempty"`
+	Roles            map[string]*dispatchRole `json:"roles"`
+	Slices           []string                 `json:"slices,omitempty"`
+	ResliceReview    string                   `json:"reslice_review,omitempty"`
+	ResliceReviewed  []string                 `json:"reslice_reviewed,omitempty"`
+	Claim            string                   `json:"claim,omitempty"`
+	ClaimSession     string                   `json:"claim_session,omitempty"`
+	Tree             string                   `json:"tree,omitempty"`             // work tree at a build wright open, for check windows --since-dispatch
+	ControllerBatch  string                   `json:"controller_batch,omitempty"` // cohort admission identity, not evidence of actor checkout
+	AdmittedPaths    map[string][]string      `json:"admitted_paths,omitempty"`   // immutable normalized write sets, keyed by source-local slice
+	PreparationFor   string                   `json:"preparation_for,omitempty"`
+	SequenceResearch bool                     `json:"sequence_research,omitempty"`
 }
 
 // dispatchClaim carries the wave-claim flags; ttl 0 means unset.
@@ -177,6 +187,16 @@ func decodeDispatch(data []byte) (*dispatchFile, error) {
 			!slices.Contains([]string{"open", "sealed", "complete", "abandoned"}, w.State) {
 			return nil, fmt.Errorf("wave %q is malformed (invalid phase, state or roles)", name)
 		}
+		purpose := preparationPurpose{parent: w.PreparationFor, research: w.SequenceResearch}
+		if purpose.parent != "" || purpose.research {
+			roles := make([]string, 0, len(w.Roles))
+			for role := range w.Roles {
+				roles = append(roles, role)
+			}
+			if err := purpose.validate(w.Phase, roles, false); err != nil {
+				return nil, fmt.Errorf("wave %q has invalid preparation purpose: %w", name, err)
+			}
+		}
 		handles := map[string]bool{}
 		allStarted, allReturned := true, true
 		for role, r := range w.Roles {
@@ -252,16 +272,33 @@ func saveDispatch(path string, f *dispatchFile) error {
 func nowStamp() string { return time.Now().UTC().Format(time.RFC3339Nano) }
 
 // RunDispatch implements the dispatch wave state machine.
+//
+// Preparation-purpose flags apply to open only; ordinary early-phase admission
+// and context generation share immediate-successor validation.
 func RunDispatch(root string, args []string, stdout, stderr io.Writer) int {
 	var slug, sub, phase, wave, role, handle, reason, review, contract, packet, outcome, result string
 	var roles, sliceIDs []string
 	var positional []string
 	all := false
+	var purpose preparationPurpose
 	var claim dispatchClaim
 	var attributed []string
 	for i := 0; i < len(args); i++ {
 		value := argAt(args, i+1)
 		switch args[i] {
+		case "--prepare-for":
+			if purpose.parent != "" {
+				fmt.Fprintln(stderr, "dispatch: duplicate --prepare-for")
+				return 2
+			}
+			if value == "" || strings.HasPrefix(value, "-") {
+				fmt.Fprintln(stderr, "dispatch: --prepare-for requires a parent source")
+				return 2
+			}
+			purpose.parent = value
+		case "--sequence-research":
+			purpose.research = true
+			continue
 		case "--phase":
 			phase = value
 		case "--wave":
@@ -319,6 +356,16 @@ func RunDispatch(root string, args []string, stdout, stderr io.Writer) int {
 		return 2
 	}
 	slug, sub = positional[0], positional[1]
+	if purpose.parent != "" || purpose.research {
+		if sub != "open" {
+			fmt.Fprintln(stderr, "dispatch: preparation purpose applies to open only")
+			return 2
+		}
+		if err := purpose.validate(phase, roles, false); err != nil {
+			fmt.Fprintf(stderr, "dispatch: %v\n", err)
+			return 2
+		}
+	}
 	if sub != "open" && (claim.session != "" || len(claim.paths) > 0 || claim.ttl != 0) {
 		fmt.Fprintln(stderr, "dispatch: --claim-session, --claim, and --claim-ttl apply to open only")
 		return 2
@@ -341,20 +388,64 @@ func RunDispatch(root string, args []string, stdout, stderr io.Writer) int {
 	// Serialize load-modify-save so concurrent start/return calls never lose
 	// an update and strand the wave short of complete.
 	code := 0
-	if err := state.WithFeatureLock(root, slug, func() error {
-		// Feature → claims is the lock order; never acquire another feature.
-		return state.WithLock(claimsPath(root)+".lock", func() error {
-			code = dispatchLocked(root, slug, sub, phase, wave, role, handle, reason, roles, sliceIDs, review, contract, packet, outcome, result, all, claim, stdout, stderr)
-			return nil
+	recordedReturn := false
+	mutate := func() error {
+		return state.WithFeatureLock(root, slug, func() error {
+			// Controller → feature → claims; never acquire another feature.
+			return state.WithLock(claimsPath(root)+".lock", func() error {
+				code = dispatchLocked(root, slug, sub, phase, wave, role, handle, reason, roles, sliceIDs, review, contract, packet, outcome, result, all, claim, purpose, stdout, stderr, &recordedReturn)
+				return nil
+			})
 		})
-	}); err != nil {
+	}
+	controllerOpen := false
+	if sub == "open" && strings.EqualFold(phase, "build") {
+		for _, candidate := range roles {
+			controllerOpen = controllerOpen || strings.Contains(candidate, "wright")
+		}
+	}
+	if sub == "open" && (earlyPreparationPhase(phase) || purpose.parent != "" || purpose.research) {
+		controllerOpen = true
+	}
+	if controllerOpen {
+		mode, err := autocompleteMode(root)
+		if err != nil {
+			fmt.Fprintf(stderr, "dispatch: BLOCKED: %v\n", err)
+			return 3
+		}
+		controllerOpen = mode || purpose.parent != "" || purpose.research
+	}
+	var lockErr error
+	if controllerOpen {
+		lockErr = parallel.WithControlLock(root, mutate)
+	} else {
+		lockErr = mutate()
+	}
+	if err := lockErr; err != nil {
 		fmt.Fprintf(stderr, "dispatch: %v\n", err)
 		return 3
 	}
+	if recordedReturn {
+		mode, err := autocompleteMode(root)
+		if err != nil {
+			fmt.Fprintf(stderr, "dispatch: return recorded; global scheduling: %v\n", err)
+			return 3
+		}
+		if mode {
+			lines, err := FrontierLines(root, slug)
+			if err != nil {
+				fmt.Fprintf(stderr, "dispatch: return recorded; global scheduling: %v\n", err)
+				return 3
+			}
+			for _, line := range lines {
+				fmt.Fprintln(stdout, line)
+			}
+		}
+	}
 	return code
 }
 
-func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, roles, sliceIDs []string, review, contract, packet, outcome, result string, all bool, claim dispatchClaim, stdout, stderr io.Writer) int {
+func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, roles, sliceIDs []string, review, contract, packet, outcome, result string, all bool, claim dispatchClaim, purpose preparationPurpose, stdout, stderr io.Writer, recordedReturn *bool) int {
 	f, path, err := loadDispatch(root, slug)
 	if err != nil {
 		fmt.Fprintf(stderr, "dispatch: %v\n", err)
@@ -382,7 +473,7 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 		if prev := getWave(); prev != nil {
 			return fail("wave %q already exists (state %s)", wave, prev.State)
 		}
-		w := &dispatchWave{Phase: phase, State: "open", Roles: map[string]*dispatchRole{}, Slices: sliceIDs}
+		w := &dispatchWave{Phase: phase, State: "open", Roles: map[string]*dispatchRole{}, Slices: sliceIDs, PreparationFor: purpose.parent, SequenceResearch: purpose.research}
 		for _, r := range roles {
 			if w.Roles[r] != nil {
 				return fail("duplicate role %q in wave", r)
@@ -392,6 +483,23 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 		if err := lintKnownRoles(root, phase, roles); err != nil {
 			return fail("BLOCKED: %v", err)
 		}
+		notices, err := preparationAdmission(root, slug, phase, purpose, f)
+		if err != nil {
+			return fail("BLOCKED: %v", err)
+		}
+		for _, notice := range notices {
+			fmt.Fprintln(stdout, notice)
+		}
+		if isBuildWrightWave(w) {
+			binding, notices, err := autocompleteWriterAdmission(root, slug, w, f)
+			if err != nil {
+				return fail("BLOCKED: %v", err)
+			}
+			w.ControllerBatch = binding
+			for _, notice := range notices {
+				fmt.Fprintln(stdout, notice)
+			}
+		}
 		rounds, code := admitWrightRounds(root, slug, f, w, review, stderr)
 		if code != 0 {
 			return code
@@ -428,10 +536,16 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 		}
 		admissionPaths := slices.Clone(claimPaths)
 		if isWrightWave(w) {
-			admissionPaths = append(admissionPaths, sliceWriteSet(root, slug, w.Slices)...)
+			if len(w.AdmittedPaths) > 0 {
+				for _, id := range w.Slices {
+					admissionPaths = append(admissionPaths, w.AdmittedPaths[id]...)
+				}
+			} else {
+				admissionPaths = append(admissionPaths, sliceWriteSet(root, slug, w.Slices)...)
+			}
 		}
 		if len(claimPaths) == 0 {
-			if err := checkAbandonedWriterClaims(root, admissionPaths); err != nil {
+			if err := checkWriterClaimsLocked(root, claim.session, admissionPaths); err != nil {
 				return fail("BLOCKED: %v", err)
 			}
 		}
@@ -566,6 +680,7 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 			if !releaseWaveClaim(root, wave, w, stdout, stderr) {
 				return 3
 			}
+			*recordedReturn = true
 			return 0
 		}
 		if r.Returned {
@@ -604,6 +719,7 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 			}
 			return fail("%v", err)
 		}
+		*recordedReturn = true
 		recordMetricNote(root, slug, w.Phase, "return", role, note)
 		fmt.Fprintf(stdout, "dispatch: %s returned (wave %s %s)\n", role, wave, w.State)
 		if all {
@@ -714,28 +830,6 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 	return 2
 }
 
-// Caller holds the repository claims lock through new-wave publication.
-func checkAbandonedWriterClaims(root string, paths []string) error {
-	if len(paths) == 0 {
-		return nil
-	}
-	latest, _, bad, err := readClaims(claimsPath(root))
-	if err != nil {
-		return err
-	}
-	if bad > 0 {
-		return fmt.Errorf("%d unparsed ledger line(s); cannot rule out an abandoned writer claim", bad)
-	}
-	conflicts, err := retainedWriterConflicts(root, latest, paths, newHolderProbe())
-	if err != nil {
-		return err
-	}
-	if len(conflicts) > 0 {
-		return fmt.Errorf("abandoned writer still holds claim %s on %s; confirm host termination and use dispatch abandon --release before retrying", conflicts[0].ID, strings.Join(conflicts[0].Paths, ","))
-	}
-	return nil
-}
-
 // releaseWaveClaim releases w's claim or reconciles a verified prior release.
 // Callers surface failure without undoing the recorded return or abandonment.
 func releaseWaveClaim(root, wave string, w *dispatchWave, stdout, stderr io.Writer) bool {
@@ -1039,6 +1133,13 @@ func wrightLane(role string) (string, bool) {
 // errors are never refused: the check widens the batch, it never stops a
 // wave that already starts every remaining pick.
 func widerBatchRefusal(root, slug string, wave []string) string {
+	mode, modeErr := autocompleteMode(root)
+	if modeErr != nil {
+		return fmt.Sprintf("dispatch: BLOCKED: %v", modeErr)
+	}
+	if mode {
+		return ""
+	}
 	capN := min(afkMaxParallel(root), parallel.MaxParallelSlices)
 	if capN < 2 {
 		return ""