Harden Hyper Run service-quality guards

README.md

@@ -150,6 +150,8 @@ For longer Codex Desktop sessions, start with an auto target:
 hyper run --auto --until service-quality "Keep upgrading this service"
 ```
 
+Use `--until sustained-service-quality` when the goal is to keep planning packets after Service Quality and focus on repeatable validators, operational handoff, and friction reduction.
+
 Auto mode does not skip proof or silently advance stages. It keeps the next packet command planned in `.hyper/next-packet.md`; stage changes still require explicit acceptance with `hyper advance`.
 
 In Codex Desktop you can use the same idea as a project command:
@@ -311,6 +313,22 @@ How do we know this stage is done?
 What should the next run improve?
 ```
 
+Short form also works:
+
+```markdown
+# Plan
+
+Project: Service Desk Lite
+Current Stage: Tiny MVP
+Build Style: Thin vertical slice first.
+
+Product brief:
+A teammate can create one support request, see it in a list, and mark it handled.
+
+Validation:
+One smoke command proves the create/list/handle flow.
+```
+
 If `plan.md` is sparse, Hyper Run may create `.hyper/plan-candidates.md` from README or docs so you can copy useful product context into `plan.md`.
 
 ## What `hyper run` Does
@@ -397,6 +415,7 @@ That updates `plan.md` from the current stage to the next stage, refreshes readi
 hyper init                  # install Hyper Run files in this project
 hyper run [focus]           # create the next runtime packet
 hyper run --auto --until service-quality [focus]
+hyper run --auto --until sustained-service-quality [focus]
 hyper complete              # run the finish gate, close the packet, and learn
 hyper advance               # apply an accepted stage change when the gate is ready
 hyper status                # show current stage, gaps, and readiness

README_ko.md

@@ -311,6 +311,22 @@ Web app
 다음 run에서 무엇을 개선해야 하나요?
 ```
 
+짧게 써도 됩니다.
+
+```markdown
+# Plan
+
+Project: Service Desk Lite
+Current Stage: Tiny MVP
+Build Style: Thin vertical slice first.
+
+Product brief:
+팀원이 지원 요청 하나를 만들고, 목록에서 보고, 처리 완료로 바꿀 수 있습니다.
+
+Validation:
+하나의 smoke command로 create/list/handle flow를 증명합니다.
+```
+
 `plan.md`가 너무 비어 있으면 Hyper Run이 README나 docs를 읽고 `.hyper/plan-candidates.md`를 만들 수 있습니다. 거기서 쓸 만한 제품 문맥을 `plan.md`로 옮기면 됩니다.
 
 ## `hyper run`이 하는 일

internal/app/advance.go

@@ -113,6 +113,11 @@ func advanceHyper(fsys fsRoot) (commandOutput, *hyperError) {
 		}
 	}
 
+	nextPlan, nextErr := writeNextPacketPlan(root, state, consistency.Derived, updatedReadiness, growth)
+	if nextErr != nil {
+		return commandOutput{}, nextErr
+	}
+
 	lines := []string{
 		"Hyper Run Stage Advance",
 		"",
@@ -125,14 +130,15 @@ func advanceHyper(fsys fsRoot) (commandOutput, *hyperError) {
 	lines = append(lines,
 		"Readiness gate: "+readinessGateSummary(updatedReadiness),
 		"Readiness pressure: "+readinessPressureSummary(updatedReadiness),
+		"Next action: "+nextPlan.Command,
+		"Why: "+nextPlan.Reason,
+		"Next packet plan: "+displayRelPath(hyperDir, "next-packet.md"),
 		"",
 		"Next:",
-		"  hyper status",
+		"  "+nextPlan.Command,
 	)
-	if updatedReadiness.NextPressure.RecommendedGoal != "" {
-		lines = append(lines, "  hyper run \""+compactText(updatedReadiness.NextPressure.RecommendedGoal, 120)+"\"")
-	} else {
-		lines = append(lines, "  hyper run [next focus]")
+	if nextPlan.Command != "hyper status --short" {
+		lines = append(lines, "  hyper status --short")
 	}
 	lines = append(lines, "")
 	return stdout(strings.Join(lines, "\n")), nil

internal/app/app.go

@@ -42,33 +42,66 @@ func runCLI(args []string, fsys fsRoot, updater updater) (commandOutput, *hyperE
 	case "", "help", "--help", "-h":
 		return stdout(usage()), nil
 	case "init":
+		if helpRequested(rest) {
+			return stdout(commandUsage("init")), nil
+		}
 		if len(rest) > 0 {
 			return commandOutput{}, newError("hyper init does not take an objective.\n\nRun `hyper init`, fill in plan.md, then use `hyper run [focus]`.", 2)
 		}
 		return initHyper(fsys)
 	case "run":
+		if helpRequested(rest) {
+			return stdout(commandUsage("run")), nil
+		}
 		opts, err := parseRunOptions(rest)
 		if err != nil {
 			return commandOutput{}, err
 		}
 		return runHyper(fsys, opts)
 	case "status":
+		if helpRequested(rest) {
+			return stdout(commandUsage("status")), nil
+		}
 		return statusHyper(fsys, rest)
 	case "doctor":
+		if helpRequested(rest) {
+			return stdout(commandUsage("doctor")), nil
+		}
 		return doctorHyper(fsys)
 	case "repair":
+		if helpRequested(rest) {
+			return stdout(commandUsage("repair")), nil
+		}
 		return repairHyper(fsys)
 	case "migrate":
+		if helpRequested(rest) {
+			return stdout(commandUsage("migrate")), nil
+		}
 		return migrateHyper(fsys)
 	case "resume":
+		if helpRequested(rest) {
+			return stdout(commandUsage("resume")), nil
+		}
 		return resumeHyper(fsys)
 	case "complete":
+		if helpRequested(rest) {
+			return stdout(commandUsage("complete")), nil
+		}
 		return completeHyper(fsys)
 	case "advance":
+		if helpRequested(rest) {
+			return stdout(commandUsage("advance")), nil
+		}
 		return advanceHyper(fsys)
 	case "version":
+		if helpRequested(rest) {
+			return stdout(commandUsage("version")), nil
+		}
 		return versionHyper()
 	case "update":
+		if helpRequested(rest) {
+			return stdout(commandUsage("update")), nil
+		}
 		source := ""
 		if len(rest) > 0 {
 			source = rest[0]
@@ -81,6 +114,18 @@ func runCLI(args []string, fsys fsRoot, updater updater) (commandOutput, *hyperE
 	}
 }
 
+func helpRequested(args []string) bool {
+	for i, arg := range args {
+		switch strings.TrimSpace(arg) {
+		case "--help", "-h":
+			return true
+		case "help":
+			return i == 0 && len(args) == 1
+		}
+	}
+	return false
+}
+
 func runInternal(args []string, fsys fsRoot) (commandOutput, *hyperError) {
 	if len(args) > 0 && args[0] == "learn" {
 		return learnCurrentGoal(fsys)
@@ -113,7 +158,7 @@ func usage() string {
 		"Primary flow:",
 		"  Run `hyper init` once in a project to install Hyper Run settings.",
 		"  Edit plan.md, then use `hyper run [focus]` to create the next runtime packet.",
-		"  Use `hyper run --auto --until service-quality [focus]` when Codex should keep planning the next packet until the target stage.",
+		"  Use `hyper run --auto --until service-quality [focus]` or `--until sustained-service-quality` when Codex should keep planning packets toward a target stage.",
 		"  After updating evidence.md and next.md, use `hyper complete` to turn evidence into pressure, candidates, and readiness.",
 		"  `hyper complete` runs the finish gate first; fix review.md findings in the same packet before continuing.",
 		"  When `hyper status` says the stage gate is ready, use `hyper advance` to apply the accepted stage change.",
@@ -132,6 +177,88 @@ func usage() string {
 	}, "\n")
 }
 
+func commandUsage(command string) string {
+	lines := map[string][]string{
+		"init": {
+			"Usage:",
+			"  hyper init",
+			"",
+			"Creates `plan.md`, `.hyper/`, and Codex Desktop routing files in the current project.",
+			"Use `hyper run [focus]` for the current work objective; do not pass the objective to `hyper init`.",
+		},
+		"run": {
+			"Usage:",
+			"  hyper run [--auto] [--until stage] [focus]",
+			"",
+			"Creates the next runtime packet from `plan.md`, prior evidence, pressure, and readiness.",
+			"Options:",
+			"  --auto              Continue packet-by-packet through the generated next-packet plan.",
+			"  --until <stage>     Plan auto continuation toward tiny-mvp, usable-mvp, beta, service-quality, or sustained-service-quality.",
+		},
+		"status": {
+			"Usage:",
+			"  hyper status",
+			"  hyper status --short",
+			"",
+			"Shows current stage, gate, proof, pressure, next action, and blocking gaps.",
+		},
+		"doctor": {
+			"Usage:",
+			"  hyper doctor",
+			"",
+			"Checks install path, version, project state, SQLite, migration freshness, and Codex Desktop routing.",
+		},
+		"repair": {
+			"Usage:",
+			"  hyper repair",
+			"",
+			"Refreshes generated project state when files are missing or stale.",
+		},
+		"migrate": {
+			"Usage:",
+			"  hyper migrate",
+			"",
+			"Refreshes project state, growth rules, readiness, and next-packet planning after a CLI update.",
+		},
+		"resume": {
+			"Usage:",
+			"  hyper resume",
+			"",
+			"Prints the current runtime packet handoff if an active packet exists.",
+		},
+		"complete": {
+			"Usage:",
+			"  hyper complete",
+			"",
+			"Runs the finish gate, learns from `evidence.md` and `next.md`, then refreshes growth and readiness.",
+		},
+		"advance": {
+			"Usage:",
+			"  hyper advance",
+			"",
+			"Updates `plan.md` to the next stage only when the readiness gate is ready and the user accepts the change.",
+		},
+		"version": {
+			"Usage:",
+			"  hyper version",
+			"",
+			"Shows build version, commit, build date, platform, executable path, and update source.",
+		},
+		"update": {
+			"Usage:",
+			"  hyper update [source]",
+			"",
+			"Installs the latest Hyper Run binary from the configured GitHub release or provided source.",
+		},
+	}
+	body := lines[command]
+	if len(body) == 0 {
+		return usage()
+	}
+	out := append([]string{"Hyper Run " + command, ""}, body...)
+	return strings.Join(out, "\n")
+}
+
 type fsRoot interface {
 	root() string
 }