devrites 3.0.5 → 3.0.7

package/engine/internal/lib/specparse.go

@@ -12,7 +12,7 @@ import (
 // — capability: <c>" section they sit under. It is the shared reader behind two
 // consumers: the spec-validate `--against` ledger cross-check (specvalidate.go)
 // and the capability-ledger fold (ledger.go). The grammar linter (lintSpec) is
-// deliberately left untouched — delta H2 headers are transparent to it — so this
+// deliberately left untouched (delta H2 headers are transparent to it) so this
 // parser adds delta-awareness without perturbing the flat-spec lint contract.
 
 // Delta kinds, lower-cased. A requirement outside any delta section has kind "".
@@ -35,7 +35,7 @@ var (
 // Requirement is one "### Requirement: <name>" block with its delta context.
 type Requirement struct {
 	Name       string // header text after "Requirement:", trailing space trimmed
-	Key        string // strings.ToLower(Name) — the identity used to match across specs
+	Key        string // strings.ToLower(Name): the identity used to match across specs
 	Kind       string // added | modified | removed | "" (flat, no delta section)
 	Capability string // from the section tag; "" when untagged
 	HeaderLine int    // 1-based line of the "### Requirement:" header
@@ -48,7 +48,7 @@ type SpecDoc struct {
 	HasDelta     bool // at least one "## … Requirements" delta section was seen
 }
 
-// ParseSpec reads and structures a spec.md. It never fails on grammar problems —
+// ParseSpec reads and structures a spec.md. It never fails on grammar problems:
 // that is lintSpec's job; ParseSpec only extracts blocks and their delta context.
 func ParseSpec(file string) (*SpecDoc, error) {
 	f, err := os.Open(file)
@@ -109,7 +109,7 @@ func ParseSpec(file string) (*SpecDoc, error) {
 }
 
 // requirementKeys returns the set of lower-cased requirement names present in a
-// spec file — the identity index a cross-spec existence check consults. A missing
+// spec file: the identity index a cross-spec existence check consults. A missing
 // or unreadable file yields an empty set (the caller decides whether that is an
 // error), matching how the ledger treats an unseeded capability.
 func requirementKeys(file string) map[string]bool {

package/engine/internal/lib/specskeleton.go

@@ -45,11 +45,11 @@ func SpecSkeleton(arg, cwd string, stdout, stderr io.Writer) int {
 		}
 	}
 	if len(missing) > 0 {
-		fmt.Fprintf(stdout, "spec-skeleton: BLOCKED — %s: missing top-level section(s): %s\n", rel, strings.Join(missing, ", "))
+		fmt.Fprintf(stdout, "spec-skeleton: BLOCKED: %s: missing top-level section(s): %s\n", rel, strings.Join(missing, ", "))
 		return 3
 	}
 
-	fmt.Fprintf(stdout, "spec-skeleton: OK — %s: all required top-level sections present\n", rel)
+	fmt.Fprintf(stdout, "spec-skeleton: OK: %s: all required top-level sections present\n", rel)
 	return 0
 }
 

package/engine/internal/lib/specvalidate.go

@@ -1,6 +1,6 @@
 // Package lib holds native Go implementations of the deterministic, zero-token
 // workflow checks DevRites used to run as individual .sh helpers. Each exported
-// function owns its logic outright — it does not shell out — and reproduces the
+// function owns its logic outright (it does not shell out) and reproduces the
 // legacy behavior (stdout + exit code) exactly, verified in the CLI test suite
 // by golden assertions or, transitionally, a bash-parity comparison.
 package lib
@@ -15,11 +15,11 @@ import (
 	"strings"
 )
 
-// Spec-grammar validator — deterministic lint of the structured
+// Spec-grammar validator: deterministic lint of the structured
 // Requirement/Scenario acceptance grammar in a spec.md. A port of
 // spec-validate.sh; see standards/spec-grammar.md for the grammar.
 //
-// Exit codes: 0 valid (or no structured requirements — nothing to lint) ·
+// Exit codes: 0 valid (or no structured requirements: nothing to lint) ·
 // 1 grammar violation(s) · 2 usage · 5 missing spec.md.
 var (
 	reqHeaderRe  = regexp.MustCompile(`^[[:space:]]*###[[:space:]]+[Rr]equirement:`)
@@ -57,13 +57,13 @@ func SpecValidate(arg, against, cwd string, stdout, stderr io.Writer) int {
 	rel := strings.TrimPrefix(spec, cwd+"/")
 
 	if reqs == 0 && len(findings) == 0 {
-		fmt.Fprintf(stdout, "spec-validate: %s uses the simple acceptance form (no \"### Requirement:\" blocks) — nothing to lint\n", rel)
+		fmt.Fprintf(stdout, "spec-validate: %s uses the simple acceptance form (no \"### Requirement:\" blocks): nothing to lint\n", rel)
 		return 0
 	}
 
 	// Delta cross-check (opt-in via --against): a spec written as deltas against a
 	// living ledger must classify each requirement correctly. Skipped for a flat
-	// snapshot (no delta sections) — there is nothing to reconcile.
+	// snapshot (no delta sections): there is nothing to reconcile.
 	if against != "" {
 		findings = append(findings, checkAgainstLedger(spec, against, defaultCapability(arg))...)
 	}
@@ -72,12 +72,12 @@ func SpecValidate(arg, against, cwd string, stdout, stderr io.Writer) int {
 		for _, f := range findings {
 			fmt.Fprintln(stderr, f)
 		}
-		fmt.Fprintf(stderr, "spec-validate: %s — %d requirement(s) / %d scenario(s); %d grammar error(s) (see standards/spec-grammar.md)\n",
+		fmt.Fprintf(stderr, "spec-validate: %s: %d requirement(s) / %d scenario(s); %d grammar error(s) (see standards/spec-grammar.md)\n",
 			rel, reqs, scens, len(findings))
 		return 1
 	}
 
-	fmt.Fprintf(stdout, "spec-validate: OK — %s: %d requirement(s) / %d scenario(s) well-formed (SHALL + WHEN/THEN, unique headers)\n",
+	fmt.Fprintf(stdout, "spec-validate: OK: %s: %d requirement(s) / %d scenario(s) well-formed (SHALL + WHEN/THEN, unique headers)\n",
 		rel, reqs, scens)
 	return 0
 }
@@ -220,7 +220,7 @@ func lintSpec(file string) (reqCount, scenCount int, findings []string, err erro
 			}
 			if scenInReq == 0 {
 				if looseWhenThen {
-					findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" (line %d) has WHEN/THEN lines but no \"#### Scenario:\" header — wrap them in a scenario", file, curReq, reqLine))
+					findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" (line %d) has WHEN/THEN lines but no \"#### Scenario:\" header: wrap them in a scenario", file, curReq, reqLine))
 				} else {
 					findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" (line %d) has no \"#### Scenario:\" block", file, curReq, reqLine))
 				}
@@ -245,7 +245,7 @@ func lintSpec(file string) (reqCount, scenCount int, findings []string, err erro
 			looseWhenThen = false
 			key := strings.ToLower(name)
 			if first, dup := seen[key]; dup {
-				findings = append(findings, fmt.Sprintf("ERROR:%s: duplicate Requirement header \"%s\" (lines %d and %d) — headers must be unique", file, name, first, nr))
+				findings = append(findings, fmt.Sprintf("ERROR:%s: duplicate Requirement header \"%s\" (lines %d and %d): headers must be unique", file, name, first, nr))
 			} else {
 				seen[key] = nr
 			}
@@ -311,7 +311,7 @@ func resolveSpecPath(command, arg string, stderr io.Writer) (string, int, bool)
 	var spec string
 	switch {
 	case isDir(arg):
-		spec = arg + "/spec.md" // string concat, not filepath.Join — preserve the exact path bytes
+		spec = arg + "/spec.md" // string concat, not filepath.Join: preserve the exact path bytes
 	case isFile(arg):
 		spec = arg
 	default:
@@ -359,11 +359,11 @@ func checkAgainstLedger(spec, ledgerRoot, defaultCap string) []string {
 		switch r.Kind {
 		case DeltaAdded:
 			if exists {
-				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement %q (line %d) is marked ADDED but already exists in ledger capability %q — use MODIFIED, or drop the delta", spec, r.Name, r.HeaderLine, capability))
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement %q (line %d) is marked ADDED but already exists in ledger capability %q: use MODIFIED, or drop the delta", spec, r.Name, r.HeaderLine, capability))
 			}
 		case DeltaModified, DeltaRemoved:
 			if !exists {
-				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement %q (line %d) is marked %s but is absent from ledger capability %q — use ADDED, or fix the capability tag", spec, r.Name, r.HeaderLine, strings.ToUpper(r.Kind), capability))
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement %q (line %d) is marked %s but is absent from ledger capability %q: use ADDED, or fix the capability tag", spec, r.Name, r.HeaderLine, strings.ToUpper(r.Kind), capability))
 			}
 		}
 	}
@@ -371,7 +371,7 @@ func checkAgainstLedger(spec, ledgerRoot, defaultCap string) []string {
 }
 
 // defaultCapability derives the fallback capability for an untagged delta section:
-// the workspace slug — the basename of the workspace dir, or of the spec.md's
+// the workspace slug: the basename of the workspace dir, or of the spec.md's
 // parent directory when a bare file path was given.
 func defaultCapability(arg string) string {
 	if isDir(arg) {

package/engine/internal/lib/stuck.go

@@ -14,7 +14,7 @@ import (
 )
 
 // awkNumRe recognises an awk "numeric string" (optional surrounding blanks, sign,
-// int/float/exponent) — the class that makes a comparison numeric. awkLeadNumRe
+// int/float/exponent): the class that makes a comparison numeric. awkLeadNumRe
 // captures the leading numeric prefix strtod would convert (so "4x" → 4).
 var (
 	awkNumRe     = regexp.MustCompile(`^[ \t\n]*[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?[ \t\n]*$`)
@@ -62,9 +62,9 @@ func sameWindow(h []string, winVal float64) bool {
 // Matching is by (tool,target) sha1, timestamps ignored. root is the .devrites
 // directory; the log lives at <root>/features/<slug>/action.log.
 //
-//	0  ok — not stuck (or logging, or no workspace: never fail the caller on log)
+//	0  ok: not stuck (or logging, or no workspace: never fail the caller on log)
 //	2  bad args
-//	3  STUCK — the recent window is a loop
+//	3  STUCK: the recent window is a loop
 func Stuck(root string, args []string, stdout, stderr io.Writer) int {
 	cmd := argAt(args, 0)
 	slug := argAt(args, 1)
@@ -84,7 +84,7 @@ func Stuck(root string, args []string, stdout, stderr io.Writer) int {
 			return 2
 		}
 		if !isDir(dir) {
-			return 0 // no workspace — never fail the caller
+			return 0 // no workspace: never fail the caller
 		}
 		record := fmt.Sprintf("%d %s %s\n", time.Now().Unix(), tool, sha1Hex(tool+"|"+target))
 		f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
@@ -102,7 +102,7 @@ func Stuck(root string, args []string, stdout, stderr io.Writer) int {
 		}
 		data, err := os.ReadFile(logPath)
 		if err != nil {
-			fmt.Fprintln(stdout, "stuck: no actions logged — not stuck.")
+			fmt.Fprintln(stdout, "stuck: no actions logged: not stuck.")
 			return 0
 		}
 		return checkStuck(actionHashes(data), rawWin, stdout)
@@ -128,14 +128,14 @@ func actionHashes(data []byte) []string {
 
 // checkStuck evaluates the hash column for identical-repeat,
 // A<->B ping-pong (last 6), and one-action-dominates (≥6 of last 8). The window
-// arg is handled with awk-compatible semantics — see awkNum / sameWindow — because
+// arg is handled with awk-compatible semantics (see awkNum / sameWindow) because
 // the prior shell helper passed it verbatim to `awk -v win=`.
 func checkStuck(h []string, rawWin string, stdout io.Writer) int {
 	n := len(h)
 	winVal, isNumericString := awkNum(rawWin)
 
 	// `NR < win`: a numeric comparison when the token is a numeric string, else a
-	// string comparison of str(NR) against the raw token — awk's comparison rule.
+	// string comparison of str(NR) against the raw token: awk's comparison rule.
 	tooFew := false
 	if isNumericString {
 		tooFew = float64(n) < winVal
@@ -143,13 +143,13 @@ func checkStuck(h []string, rawWin string, stdout io.Writer) int {
 		tooFew = strconv.Itoa(n) < rawWin
 	}
 	if tooFew {
-		fmt.Fprintf(stdout, "stuck: only %d action(s) — not stuck.\n", n)
+		fmt.Fprintf(stdout, "stuck: only %d action(s): not stuck.\n", n)
 		return 0
 	}
 	// The last `win` actions are identical. The message echoes the raw token, as
 	// awk prints the `win` variable verbatim (so "04"/"+4" render unchanged).
 	if sameWindow(h, winVal) {
-		fmt.Fprintf(stdout, "stuck: last %s actions identical — STUCK.\n", rawWin)
+		fmt.Fprintf(stdout, "stuck: last %s actions identical: STUCK.\n", rawWin)
 		return 3
 	}
 	// A<->B ping-pong over the last 6 actions.
@@ -166,7 +166,7 @@ func checkStuck(h []string, rawWin string, stdout io.Writer) int {
 			}
 		}
 		if pp && h[n-1] != h[n-2] {
-			fmt.Fprintln(stdout, "stuck: A<->B ping-pong over last 6 — STUCK.")
+			fmt.Fprintln(stdout, "stuck: A<->B ping-pong over last 6: STUCK.")
 			return 3
 		}
 	}
@@ -183,11 +183,11 @@ func checkStuck(h []string, rawWin string, stdout io.Writer) int {
 			}
 		}
 		if top >= 6 {
-			fmt.Fprintf(stdout, "stuck: one action %d/8 of recent window — STUCK.\n", top)
+			fmt.Fprintf(stdout, "stuck: one action %d/8 of recent window: STUCK.\n", top)
 			return 3
 		}
 	}
-	fmt.Fprintln(stdout, "stuck: recent window varied — not stuck.")
+	fmt.Fprintln(stdout, "stuck: recent window varied: not stuck.")
 	return 0
 }
 
@@ -197,7 +197,7 @@ func sha1Hex(s string) string {
 	return hex.EncodeToString(sum[:])
 }
 
-// argAt returns args[i] or "" — the Go analogue of bash's ${N:-} positional reads.
+// argAt returns args[i] or "": the Go analogue of bash's ${N:-} positional reads.
 func argAt(args []string, i int) string {
 	if i < len(args) {
 		return args[i]

package/engine/internal/lib/templates/conventions_ledger_header.md

@@ -2,5 +2,5 @@
 
 Conventions proven by sealed slices on this project. **Local, gitignored, advisory.**
 The confidence band is earned: it reflects how many independent sealed slices corroborated
-the convention — it is not a model's guess. A high band is still untrusted data; a fresh
+the convention. It is not a model's guess. A high band is still untrusted data; a fresh
 observation of the live code always wins over a stale entry here.

package/engine/internal/lib/templates/conventions_orient_header.txt

@@ -1 +1 @@
-# Conventions ledger — proven priors (live code always overrides)
+# Conventions ledger: proven priors (live code always overrides)

package/engine/internal/lib/testintegrity.go

@@ -10,7 +10,7 @@ import (
 	"strings"
 )
 
-// skipMarkers matches a test that has been muted — a skip/focus/ignore marker
+// skipMarkers matches a test that has been muted: a skip/focus/ignore marker
 // across the common test frameworks. assertMarkers matches an assertion. Both are
 // counted per file to detect a test being weakened rather than fixed.
 var (
@@ -26,7 +26,7 @@ var (
 //
 //	0  clean, or skipped because this is not a git repo
 //	2  no active workspace / bad args
-//	3  WEAKENED — a test was deleted, skipped, or de-asserted since the base
+//	3  WEAKENED: a test was deleted, skipped, or de-asserted since the base
 func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 	// Accept both `test-integrity [slug]` and the `check [slug]` alias; a leading
 	// dash is treated as "no slug".
@@ -56,7 +56,7 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 	cwd, _ := os.Getwd()
 	gitRoot := gitToplevel(cwd)
 	if gitRoot == "" {
-		fmt.Fprintln(stderr, "test-integrity: not a git repo — gate skipped, eyeball the test diff by hand.")
+		fmt.Fprintln(stderr, "test-integrity: not a git repo: gate skipped, eyeball the test diff by hand.")
 		return 0
 	}
 
@@ -85,7 +85,7 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 		testChanged++
 		old, ok := gitShow(gitRoot, ref+":"+f)
 		if !ok || old == "" {
-			continue // new test file — adding tests is never a weakening
+			continue // new test file: adding tests is never a weakening
 		}
 		if !isFile(filepath.Join(gitRoot, f)) {
 			weak++
@@ -110,17 +110,17 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 	}
 
 	// Verification-gap advisory: source changed but no test file did. Not a
-	// weakening and never a verdict on its own — a pointer to run the
+	// weakening and never a verdict on its own: a pointer to run the
 	// verification-gap trace (testing.md), since a green suite can pass identically
 	// with the change reverted. Printed on both the clean and weakened paths.
 	gapAdvisory := ""
 	if srcChanged > 0 && testChanged == 0 {
-		gapAdvisory = fmt.Sprintf("test-integrity: advisory — %d source file(s) changed, 0 test file(s) touched; "+
+		gapAdvisory = fmt.Sprintf("test-integrity: advisory: %d source file(s) changed, 0 test file(s) touched; "+
 			"run the verification-gap trace (testing.md) to confirm each changed behavior is asserted.", srcChanged)
 	}
 
 	if weak > 0 {
-		fmt.Fprintf(stderr, "test-integrity: WEAKENED — %d test file(s) lost coverage since the slice base:\n", weak)
+		fmt.Fprintf(stderr, "test-integrity: WEAKENED: %d test file(s) lost coverage since the slice base:\n", weak)
 		fmt.Fprint(stderr, report.String())
 		fmt.Fprintln(stderr, "A test weakened to pass a gate is a Critical finding. Revert it; fix the code or raise a blocking question.")
 		if gapAdvisory != "" {
@@ -128,14 +128,14 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 		}
 		return 3
 	}
-	fmt.Fprintln(stdout, "test-integrity: OK — no test deleted, skipped, or de-asserted since the base.")
+	fmt.Fprintln(stdout, "test-integrity: OK: no test deleted, skipped, or de-asserted since the base.")
 	if gapAdvisory != "" {
 		fmt.Fprintln(stdout, gapAdvisory)
 	}
 	return 0
 }
 
-// isSourceFile recognises a path as project source worth pairing with a test —
+// isSourceFile recognises a path as project source worth pairing with a test:
 // a code file that is not itself a test. It filters out the common non-code
 // changes (docs, config, lockfiles) so the verification-gap advisory keys on
 // behavior-bearing edits, not a README or a manifest bump.

package/engine/internal/lib/tickafk.go

@@ -19,7 +19,7 @@ import (
 // any workspace. Exit codes:
 //
 //	0  a slice was spent and budget remains, or no budget is set (nothing to do)
-//	3  the budget is now exhausted — the caller must stop and hand back to a human
+//	3  the budget is now exhausted: the caller must stop and hand back to a human
 //	5  the file is missing, or the field holds a non-numeric value
 func TickAfk(args []string, stdout, stderr io.Writer) int {
 	path := argAt(args, 0)
@@ -37,7 +37,7 @@ func TickAfk(args []string, stdout, stderr io.Writer) int {
 
 	remaining, found := readBudget(lines)
 	if !found || remaining == "none" {
-		fmt.Fprintf(stdout, "tick-afk: no \"AFK slices remaining\" budget set in %s — no-op\n", path)
+		fmt.Fprintf(stdout, "tick-afk: no \"AFK slices remaining\" budget set in %s: no-op\n", path)
 		return 0
 	}
 	if !isAllDigits(remaining) {
@@ -62,8 +62,8 @@ func TickAfk(args []string, stdout, stderr io.Writer) int {
 	return 0
 }
 
-// readBudget returns the current "AFK slices remaining" value — the first blank-
-// delimited token after the field — and whether the field is present at all.
+// readBudget returns the current "AFK slices remaining" value: the first blank-
+// delimited token after the field, and whether the field is present at all.
 func readBudget(lines []string) (value string, found bool) {
 	value, found = state.CursorField(lines, state.CursorAFKSlicesRemaining)
 	if !found {

package/engine/internal/migrate/migrate.go

@@ -148,7 +148,7 @@ Normalized by DevRites migration.
 
 // derivePhase reads state.md in either canonical cursor-table or legacy form and
 // maps its recorded phase/status onto the current lifecycle. An unreadable or
-// unrecognised state defaults to build — the safe middle of the arc, from which
+// unrecognised state defaults to build: the safe middle of the arc, from which
 // the completeness gates re-derive what's missing.
 func derivePhase(statePath string) state.Phase {
 	raw, err := os.ReadFile(statePath)
@@ -169,7 +169,7 @@ func derivePhase(statePath string) state.Phase {
 // mapLegacyPhase maps a current or legacy phase/status word onto the lifecycle.
 func mapLegacyPhase(word string) (state.Phase, bool) {
 	word = strings.ToLower(strings.TrimSpace(word))
-	// Take the first token, so "done — shipped 2024" maps on "done".
+	// Take the first token, so a legacy "done" status with trailing notes still maps to "done".
 	if i := strings.IndexAny(word, " \t—-"); i > 0 {
 		word = word[:i]
 	}

package/engine/internal/migrate/migrate_test.go

@@ -104,6 +104,7 @@ func TestMapLegacyPhase(t *testing.T) {
 		{word: "in-progress", want: state.PhaseBuild, ok: true},
 		{word: "reviewing", want: state.PhaseReview, ok: true},
 		{word: "done - shipped", want: state.PhaseDone, ok: true},
+		{word: "done — shipped", want: state.PhaseDone, ok: true},
 		{word: "mystery"},
 	} {
 		got, ok := mapLegacyPhase(tc.word)

package/engine/internal/orient/firstrun.go

@@ -14,21 +14,21 @@ const FirstRunFile = ".first-run-shown"
 
 // firstRunNudges maps each first-task token to the single orientation line shown
 // on the first-ever session with no active feature. A token missing here (or a
-// future new token) stays silent — the nudge is an enhancement, never a
+// future new token) stays silent: the nudge is an enhancement, never a
 // dependency, and prose is owned here rather than in the classifier.
 var firstRunNudges = map[string]string{
-	"greenfield":           "Greenfield project — start with /rite-spec <feature> to spec the first feature.",
-	"brownfield-unadopted": "Existing codebase with no DevRites history — start with /rite-adopt to onboard it.",
-	"dirty-worktree":       "Uncommitted changes in the worktree — /rite-frame the work in flight, or /rite-quick for a small fix.",
-	"branch-ahead":         "Branch is ahead of its upstream — /rite-review then /rite-ship the unshipped work.",
-	"clean-default":        "No active feature — /rite-spec <feature> starts the next one; /rite shows the menu.",
+	"greenfield":           "Greenfield project: start with /rite-spec <feature> to spec the first feature.",
+	"brownfield-unadopted": "Existing codebase with no DevRites history: start with /rite-adopt to onboard it.",
+	"dirty-worktree":       "Uncommitted changes in the worktree: /rite-frame the work in flight, or /rite-quick for a small fix.",
+	"branch-ahead":         "Branch is ahead of its upstream: /rite-review then /rite-ship the unshipped work.",
+	"clean-default":        "No active feature: /rite-spec <feature> starts the next one; /rite shows the menu.",
 }
 
 // FirstRunDigest returns the one-time blank-slate orientation for a workspace
 // with no active feature. It fires at most once per project: the marker is
 // written before the text is returned, and a marker that cannot be written
 // keeps the digest silent so a broken filesystem never turns into a per-session
-// nag. Fail-open throughout — every non-happy path is ("", false).
+// nag. Fail-open throughout: every non-happy path is ("", false).
 func FirstRunDigest(root string) (text string, has bool) {
 	marker := filepath.Join(root, FirstRunFile)
 	if _, err := os.Stat(marker); err == nil {
@@ -40,7 +40,7 @@ func FirstRunDigest(root string) (text string, has bool) {
 	}
 	f, err := os.OpenFile(marker, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
 	if err != nil {
-		return "", false // marker unwritable (or raced) — silent rather than nagging
+		return "", false // marker unwritable (or raced): silent rather than nagging
 	}
 	if err := f.Close(); err != nil {
 		return "", false

package/engine/internal/orient/orient.go

@@ -20,7 +20,7 @@ import (
 const ActiveFile = "ACTIVE"
 
 // Digest returns the orientation text for the workspace at root and whether
-// there is anything to say. It returns ("", false, nil) — silent, not an error —
+// there is anything to say. It returns ("", false, nil): silent, not an error:
 // when no feature is active or the active pointer is stale, so a session is never
 // disrupted by a missing or half-set-up workspace.
 func Digest(root string) (text string, has bool, err error) {
@@ -33,21 +33,21 @@ func Digest(root string) (text string, has bool, err error) {
 	}
 
 	// A stale pointer (names a feature that no longer exists) stays silent
-	// rather than erroring — orientation must never be a session dependency.
+	// rather than erroring: orientation must never be a session dependency.
 	report, err := state.Status(root, slug)
 	if err != nil {
 		return "", false, nil
 	}
 
 	var b strings.Builder
-	fmt.Fprintf(&b, "DevRites workflow active — feature %q at phase %q.\n\n", report.Slug, report.Phase)
+	fmt.Fprintf(&b, "DevRites workflow active: feature %q at phase %q.\n\n", report.Slug, report.Phase)
 	b.WriteString(report.Render())
 
 	// Surface only the high-confidence, human-promoted learnings, capped so a
 	// growing ledger never bloats the session. Bounds come from
 	// DEVRITES_LEARNING_CONFIDENCE_THRESHOLD / DEVRITES_MAX_INJECTED_LEARNINGS.
 	if picks := lib.TopLearnings(root, lib.InjectMax(), lib.InjectThreshold()); len(picks) > 0 {
-		b.WriteString("\n\nHigh-confidence learnings (untrusted prior — live code always wins):\n")
+		b.WriteString("\n\nHigh-confidence learnings (untrusted prior: live code always wins):\n")
 		for _, p := range picks {
 			b.WriteString(p)
 			b.WriteByte('\n')
@@ -59,7 +59,7 @@ func Digest(root string) (text string, has bool, err error) {
 }
 
 // ActiveSlug reads and trims the active-feature pointer. A missing pointer file
-// is not an error — it yields the empty slug (no active feature).
+// is not an error: it yields the empty slug (no active feature).
 func ActiveSlug(root string) (string, error) {
 	return devritespaths.ActiveSlug(root)
 }

package/engine/internal/state/concurrency_test.go

@@ -18,7 +18,7 @@ import (
 
 // TestAppendLogConcurrentNoInterleaveNoLoss spawns many concurrent appenders,
 // each writing a distinct small record, and asserts every record landed exactly
-// once and intact — no interleaving, no lost writes.
+// once and intact: no interleaving, no lost writes.
 func TestAppendLogConcurrentNoInterleaveNoLoss(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "events.log")
 	const n = 64
@@ -57,8 +57,8 @@ func TestAppendLogConcurrentNoInterleaveNoLoss(t *testing.T) {
 
 // TestAtomicWriteReaderNeverSeesPartial has many writers overwrite one path with
 // distinct full-size contents while readers read concurrently. A reader must
-// always observe a complete, self-consistent file — never a half-written or
-// mixed one — which is exactly what temp-file + atomic rename guarantees.
+// always observe a complete, self-consistent file: never a half-written or
+// mixed one: which is exactly what temp-file + atomic rename guarantees.
 func TestAtomicWriteReaderNeverSeesPartial(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("Windows does not allow replacing a file while another handle is reading it")
@@ -166,7 +166,7 @@ func TestWithFeatureLockSerializesReadModifyWrite(t *testing.T) {
 
 	raw, _ := os.ReadFile(counter)
 	if got := strings.TrimSpace(string(raw)); got != strconv.Itoa(n) {
-		t.Fatalf("counter = %s, want %d — lost updates under contention", got, n)
+		t.Fatalf("counter = %s, want %d: lost updates under contention", got, n)
 	}
 }
 

package/engine/internal/state/feature.go

@@ -64,8 +64,8 @@ func featureDir(root, slug string) string {
 	return devritespaths.FeatureDir(root, slug)
 }
 
-// ListFeatures returns the slugs of every feature under root — directories under
-// canonical work/ plus compatibility features/ recognized as a feature — sorted.
+// ListFeatures returns the slugs of every feature under root: directories under
+// canonical work/ plus compatibility features/ recognized as a feature: sorted.
 // A directory is a feature if it has a workspace map OR the working-state
 // ledger (state.md), so a live workspace the pack created without a map
 // still lists. Missing layout directories yield an empty list, not an error.
@@ -178,7 +178,7 @@ func LoadFeature(root, slug string) (*Feature, error) {
 }
 
 // sectionPresentAny reports whether any file that can satisfy section s has real
-// content — the canonical name or a transitional alias.
+// content: the canonical name or a transitional alias.
 func sectionPresentAny(dir string, s Section) bool {
 	for _, name := range sectionFiles[s] {
 		if sectionPresent(filepath.Join(dir, name)) {
@@ -207,7 +207,7 @@ func declaredPhaseFromLedger(path string) (Phase, bool) {
 // ReadDeclaredSchemaVersion returns the schemaVersion declared in a feature's
 // feature.md frontmatter, or 0 if the file, frontmatter, or field is
 // absent/unparseable. Unlike LoadFeature it does NOT refuse a version newer than
-// the engine supports — doctor needs to observe a newer version to report skew,
+// the engine supports: doctor needs to observe a newer version to report skew,
 // not fail on it.
 func ReadDeclaredSchemaVersion(root, slug string) int {
 	raw, err := os.ReadFile(filepath.Join(featureDir(root, slug), "feature.md"))
@@ -239,7 +239,7 @@ func MaxDeclaredSchemaVersion(root string) (int, error) {
 	return max, nil
 }
 
-// blankOrHash reports whether a trimmed line carries no meaningful content —
+// blankOrHash reports whether a trimmed line carries no meaningful content:
 // it is empty or starts with '#' (a Markdown ATX heading, or a comment inside a
 // frontmatter block). Both the section-content scan and the frontmatter parser
 // skip such lines.
@@ -285,7 +285,7 @@ func splitFrontmatter(raw []byte) (map[string]string, []byte) {
 		}
 	}
 	if end < 0 {
-		return fm, raw // no closing fence — treat as if there were no frontmatter
+		return fm, raw // no closing fence: treat as if there were no frontmatter
 	}
 	for _, line := range lines[:end] {
 		t := strings.TrimSpace(line)

package/engine/internal/state/lock_unix.go

@@ -10,7 +10,7 @@ import (
 
 // fileLock is an exclusive advisory lock held on an open lock file. On unix it
 // uses flock(2), which the kernel releases automatically when the file is closed
-// or the process exits — so a crashed writer never strands the lock.
+// or the process exits, so a crashed writer never strands the lock.
 type fileLock struct{ f *os.File }
 
 func acquireLock(path string) (*fileLock, error) {

package/engine/internal/state/schema.go

@@ -45,7 +45,7 @@ var Sections = []Section{
 }
 
 // sectionFiles lists the filenames that can satisfy each section, canonical name
-// first, then supported aliases — the same mapping `devrites-engine migrate`
+// first, then supported aliases: the same mapping `devrites-engine migrate`
 // normalizes (proof→evidence, status→state). A section
 // counts as present if ANY of its files has real content, so the engine reads a
 // live workspace before the pack sweep converges the filenames. The workspace

package/engine/internal/state/snapshot.go

@@ -28,8 +28,8 @@ var (
 )
 
 // WorkspaceSnapshot is the machine-readable DevRites workspace/status contract.
-// It models DevRites' native unit of work — a feature workspace at a phase with
-// section completeness — rather than a generic harness session/worker shape.
+// It models DevRites' native unit of work: a feature workspace at a phase with
+// section completeness: rather than a generic harness session/worker shape.
 type WorkspaceSnapshot struct {
 	SchemaVersion   string               `json:"schemaVersion"`
 	Slug            string               `json:"slug"`

package/engine/internal/state/write.go

@@ -10,7 +10,7 @@ import (
 )
 
 // AtomicWrite writes data to path via a temp file in the same directory followed
-// by an atomic rename, so a concurrent reader — or a writer killed mid-write —
+// by an atomic rename, so a concurrent reader, or a writer killed mid-write:
 // never observes a half-written structured file. The temp file is fsync'd before
 // the rename so the content is durable before it becomes visible.
 func AtomicWrite(path string, data []byte, perm os.FileMode) error {

package/engine/internal/version/version.go

@@ -16,7 +16,7 @@ var Version = "dev"
 // Compare returns -1, 0, or +1 as semantic version a is less than, equal to, or
 // greater than b, and ok=false when either side is not a plain dotted-number
 // version (e.g. "dev"). A leading "v" is tolerated; pre-release/build suffixes
-// are ignored. Callers use ok=false to mean "not comparable — do not warn".
+// are ignored. Callers use ok=false to mean "not comparable: do not warn".
 func Compare(a, b string) (cmp int, ok bool) {
 	pa, oka := parse(a)
 	pb, okb := parse(b)