fix: soft-wrap generated markdown and forward extra flow flags

skills/dev/SKILL.md

@@ -24,6 +24,7 @@ Pass your intent directly on the invocation line — `explore` and `plan` procee
 - **Step 0 always runs first** — no exceptions
 - **Unknown verb → run `help.md`** — never error silently
 - **Pass all remaining args through** — workflow receives `$REMAINING_ARGS` unchanged
+- **Markdown output: soft-wrap prose, never hard-wrap** — when any dev workflow or agent writes a `.md` artifact (proposals, research notes, docs, plans), write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences.
 
 ## Step 0: Parse Arguments
 

skills/dev/agents/proposal-writer.md

@@ -40,6 +40,8 @@ Your prompt tells you:
 
 **One-sentence verdict.** The opening `>` line must be a verdict a decision-maker can read in isolation and understand the approach's core trade-off. Not "this is a solid approach" — something like "Best when you need strong type safety at the cost of a heavier migration."
 
+**Soft-wrap prose — never hard-wrap.** Write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences.
+
 ## Output
 
 Before reporting, verify: does the proposal contain a concrete "How it comes together" section with at least one cited library API? If not, add it before writing the file.

skills/docs/SKILL.md

@@ -16,6 +16,7 @@ Triggers: "docs new", "docs update", "docs review", "docs retcon", "create docs"
 - **Never execute workflow logic here** — this file only parses args and dispatches
 - **Step 0 always runs first** — no exceptions
 - **Unknown verb → run `help.md`** — never error silently
+- **Markdown output: soft-wrap prose, never hard-wrap** — when any docs workflow writes a `.md` artifact, write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences. (Full guidance: `references/language-guide.md`.)
 
 ## Step 0: Parse Arguments
 

skills/docs/references/language-guide.md

@@ -85,3 +85,20 @@ just dev
 ### 10. Link; don't duplicate
 
 If auth.md already explains the session format, link to it — don't repeat it. Use the `## References` section. Duplication creates maintenance debt.
+
+### 11. Soft-wrap prose — never hard-wrap
+
+Write each paragraph as a single continuous line. Do not insert manual newlines to wrap prose at a fixed column width — on narrow screens and non-reflowing renderers, hard breaks wrap badly. Let the renderer handle wrapping.
+
+Bad (hard-wrapped at ~80 cols):
+```
+The session is stored in an HttpOnly cookie so JavaScript running in the
+browser cannot read it, which prevents XSS attacks from stealing sessions.
+```
+
+Good (one paragraph, one line):
+```
+The session is stored in an HttpOnly cookie so JavaScript running in the browser cannot read it, which prevents XSS attacks from stealing sessions.
+```
+
+Newlines still separate paragraphs, list items, headings, and code fences — only mid-paragraph line breaks are forbidden.

skills/ed/SKILL.md

@@ -29,6 +29,7 @@ Pass your intent directly:
 - **Step 0 always runs first** — no exceptions
 - **Unknown verb → run `help.md`** — never error silently
 - **Pass all remaining args through** — workflow receives `$REMAINING_ARGS` unchanged
+- **Markdown output: soft-wrap prose, never hard-wrap** — when any ed workflow writes a `.md` artifact (study notes, guides, syllabi, quizzes), write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences. (Full guidance: `references/pedagogy.md`.)
 
 ## Step 0: Parse Arguments
 

skills/ed/references/pedagogy.md

@@ -43,3 +43,8 @@ Prefer a diagram over a paragraph whenever a concept has spatial, structural, se
 
 - End each concept with a check: a question, a "predict the output", or a "why does this work?" prompt.
 - Prefer worked examples that show every intermediate step over stating a result.
+
+## 6. Soft-wrap prose — never hard-wrap
+
+- Write each paragraph as a single continuous line. Do not insert manual newlines to wrap prose at a fixed column width — hard breaks reflow badly on narrow screens and non-reflowing renderers. Let the renderer wrap.
+- Newlines still separate paragraphs, list items, headings, and code fences (and mermaid/LaTeX/ASCII blocks keep their own line structure) — only mid-paragraph line breaks in prose are forbidden.

skills/em/SKILL.md

@@ -25,6 +25,7 @@ Pass your intent directly on the invocation line — `plan` proceeds immediately
 - **Step 0 always runs first** — no exceptions
 - **Unknown verb → run `help.md`** — never error silently
 - **Pass all remaining args through** — workflow receives `$REMAINING_ARGS` unchanged
+- **Markdown output: soft-wrap prose, never hard-wrap** — when any em workflow or agent writes a `.md` artifact (epic plans, roadmaps, research notes), write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences.
 
 ## Step 0: Parse Arguments
 

skills/em/references/plan-template.md

@@ -2,6 +2,8 @@
 
 Use this template for `.codevoyant/em/plans/{slug}/plan.md`.
 
+**Markdown output:** Soft-wrap prose — never hard-wrap. Write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences.
+
 ---
 
 # {Project Name}

skills/flow/SKILL.md

@@ -41,6 +41,8 @@ Dispatch to: references/workflows/{VERB}.md
 
 The `--global` / `-g` flag (store or read a flow under `~/.codevoyant/flows` instead of the local `.codevoyant/flows`) is **not** a verb — pass it through unchanged; each workflow parses it via `references/flow-dir.md`.
 
+Any flag other than the flow-control flags (`--global`/`-g`, and `--set` for `go`) is **not** dropped: `references/flow-dir.md` collects it into `PASSTHROUGH_FLAGS`, and the `new`/`go` workflows forward it to the step commands. This is how `--branch feature/x` reaches the skills a flow runs (e.g. so `spec new` works on a separate branch).
+
 ## Workflow index
 
 | Verb | File | Purpose |
@@ -58,4 +60,4 @@ The `--global` / `-g` flag (store or read a flow under `~/.codevoyant/flows` ins
 2. Apply aliases (run/exec/start → go; ls → list; show/review → status; export/publish → save).
 3. If VERB is empty or unrecognized, default to `help`.
 4. Read and execute the corresponding workflow file from `references/workflows/{VERB}.md`.
-5. Pass all remaining arguments (including any `--global`/`-g` flag) to the workflow unchanged.
+5. Pass all remaining arguments (including any `--global`/`-g` flag and any other unrecognized flags such as `--branch`) to the workflow unchanged, **as a preserved argv array** — each original argument stays one element, so multi-word step strings (`/spec new {{objective}}`) and quoted flag values (`feature="add OAuth"`) survive intact. The workflow iterates this argv (`"$@"`) to parse flow-control flags and bucket the rest into `PASSTHROUGH_FLAGS` via `references/flow-dir.md`; it must never flatten the args into a single string and re-split them.

skills/flow/references/flow-dir.md

@@ -13,16 +13,58 @@ A flow is a directory `{slug}/` containing `flow.md` and `implementation/step-N.
 
 `--global` (alias `-g`) selects the global scope. Parse it out of the arguments in every workflow **before** reading the flow name, and strip it from the positional args.
 
+Work from the **preserved argv** the dispatcher forwarded (each original argument is one array element — a multi-word step string like `/spec new {{objective}}` is a single element, and a quoted flag value like `feature="add OAuth"` stays attached to its flag). Never flatten argv into a string and re-split it: iterate `"$@"` directly.
+
+This minimal loop below sets `GLOBAL` only — it is enough for `status`/`list`/`save`, which do not forward flags. `new`/`go` need the fuller argv walker in [Pass-through flags](#pass-through-flags-branch-and-any-other-unrecognized-flag) below, which sets `GLOBAL` **and** buckets `PASSTHROUGH_FLAGS`/`POSITIONALS`. The two must agree on how `--global` is detected: **if you change the `--global`/`-g` handling in one, change it in the other.**
+
 ```bash
 GLOBAL=false
-case " $ARGS " in *" --global "*|*" -g "*) GLOBAL=true ;; esac
+for a in "$@"; do
+  case "$a" in --global|-g) GLOBAL=true ;; esac
+done
 FLOW_ROOT="$( [ "$GLOBAL" = true ] && echo "$HOME/.codevoyant" || echo ".codevoyant" )"
 FLOWS_DIR="$FLOW_ROOT/flows"
 ```
 
 - `~` always means the real home directory — use `"$HOME"` in bash, never a literal `~` inside quotes.
 - Create the global root on demand: `mkdir -p "$HOME/.codevoyant/flows"` (safe if it already exists).
 
+## Pass-through flags (`--branch` and any other unrecognized flag)
+
+Flow recognizes exactly these **flow-control** flags: `--global`/`-g` (all verbs) and `--set key=value` (`go` only; parsed in `go.md`). **Every other flag must be preserved, not dropped** — for example `--branch feature/x`, which callers use to run a flow's steps on a separate branch.
+
+While stripping the flow-control flags, collect all remaining flags (any element starting with `-`, plus its value element when the following element does not itself start with `-`) into an ordered list `PASSTHROUGH_FLAGS`, and leave the true positionals in `POSITIONALS`. Boolean flags (no value) are kept as-is; `--flag=value` forms are kept whole.
+
+**Iterate the preserved argv, never a re-split string.** The block below walks `"$@"` — the array the dispatcher forwarded — so each element stays intact: a multi-word step command (`/spec new {{objective}}`) remains one `POSITIONALS` entry, and a flag value carried as one shell word (`feature="add OAuth"`) is not shredded. Do **not** write `set -- $ARGS` (or any unquoted re-split): that word-splits every step string and quoted value on whitespace and corrupts both `POSITIONALS` and `PASSTHROUGH_FLAGS`.
+
+This walker is the **superset** of the minimal `--global`-only loop under [The `--global` flag](#the-global-flag): it detects `--global`/`-g` identically and additionally buckets pass-through flags. `new`/`go` use this one; `status`/`list`/`save` use the minimal loop. Keep the `--global`/`-g` case in the two in sync.
+
+```bash
+# Walk argv "$@" left→right; peel flow-control flags, bucket the rest into PASSTHROUGH_FLAGS,
+# leave true positionals (flow name, steps, input) in POSITIONALS. Each "$@" element is
+# preserved whole — no re-splitting.
+GLOBAL=false
+PASSTHROUGH_FLAGS=()   # e.g. (--branch feature/x)
+POSITIONALS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --global|-g) GLOBAL=true; shift ;;
+    --set) PASSTHROUGH_FLAGS+=("$1" "$2"); shift 2 ;;   # go.md re-reads --set; new.md drops it before baking
+    --*|-*)
+      if [ $# -ge 2 ] && [ "${2#-}" = "$2" ]; then       # next element is a value (does not start with -)
+        PASSTHROUGH_FLAGS+=("$1" "$2"); shift 2
+      else
+        PASSTHROUGH_FLAGS+=("$1"); shift                 # boolean, --flag=value, or value-less trailing flag
+      fi ;;
+    *) POSITIONALS+=("$1"); shift ;;
+  esac
+done
+```
+
+- **`--set` handling is verb-specific.** `go.md` parses `--set key=value` out of `PASSTHROUGH_FLAGS` into `PARAMS` and forwards the remainder. For `new`, `--set` is **not** a step flag and must **not** be baked into stored steps: `new.md` explicitly drops any `--set key=value` pair from `PASSTHROUGH_FLAGS` before writing step commands (see new.md Step 2). For `status`/`list`, `--set` is inert and simply ignored.
+- **Caveat — flag values starting with `-`.** The `[ "${2#-}" = "$2" ]` test treats any following element that starts with `-` as *not* this flag's value, so a legitimate value beginning with `-` (e.g. `--message "-n"`) is read as a value-less flag and the `-n` falls through to `POSITIONALS`. This is acceptable for the `--branch feature/x`-style forwarding flow actually uses; **flag values beginning with `-` are not supported** — pass them in `--flag=value` form (kept whole) if ever needed.
+- `PASSTHROUGH_FLAGS` is what `new` bakes into stored step commands (minus `--set`) and what `go` merges into each resolved step command at run time (see those workflows). At `go` time, run-time flags **override** any same-named flag baked into the step — the explicit run-time value wins, and a flag never appears twice (see go.md Step 2).
+
 ## Resolving a flow by name (for `go`, `status`, `save`)
 
 When the user names an existing flow to run/inspect, resolve which scope holds it:

skills/flow/references/workflows/go.md

@@ -9,10 +9,13 @@ Steps run **non-interactively** — a subagent cannot prompt the user. When a st
 ```
 --global / -g   → read the flow from ~/.codevoyant/flows (see references/flow-dir.md)
 --set key=value → bind a named parameter (repeatable, e.g. --set feature="add OAuth" --set env=staging)
-FLOW_NAME = first non-flag positional arg (required)
-INPUT     = all remaining bare (non-flag, non-name) positional text, joined with spaces → the {{input}} parameter
+--branch, etc.  → any other flag → PASSTHROUGH_FLAGS (see references/flow-dir.md), appended to every step this run
+FLOW_NAME = first positional arg (POSITIONALS[0]; required)
+INPUT     = all remaining positional text (POSITIONALS[1..]), joined with spaces → the {{input}} parameter
 ```
 
+Parse flags via `references/flow-dir.md`, iterating the **preserved argv** (`"$@"`) — never re-split a flattened string. From the resulting `PASSTHROUGH_FLAGS`, pull out any `--set key=value` pairs into `PARAMS` (below); the remainder (e.g. `--branch feature/x`) stays in `PASSTHROUGH_FLAGS` and is appended to every step command this run (Step 2).
+
 If `FLOW_NAME` is missing, error: "Usage: /flow go <name> [input text] [--set k=v] [--global]. A flow name is required."
 
 Build the parameter map `PARAMS`:
@@ -42,7 +45,12 @@ Initialize the **flow context** accumulator `CONTEXT`. **On resume:** if `FLOW_D
 
 For each pending step in order:
 
-1. **Substitute parameters** in the step command: replace every `{{name}}` with `PARAMS[name]`. Call the result `RESOLVED_COMMAND`. Report: `▶ Step {N}: {RESOLVED_COMMAND}`
+1. **Substitute parameters** in the step command: replace every `{{name}}` with `PARAMS[name]`, then merge this run's `PASSTHROUGH_FLAGS` (e.g. `--branch feature/x`) into the command string. **Run-time flags override baked ones (deterministic merge):** a step may already carry a flag baked in at `new` time (e.g. `/spec new {{objective}} --branch feature/x`). For each flag in `PASSTHROUGH_FLAGS`, key on its flag name (the token before any `=`, e.g. `--branch`):
+   - If that flag name already appears as a whole-word token in the step command **and** the run-time value differs, **replace** the baked flag (and its value) with the run-time one — the explicit run-time value wins. Report the override: `ℹ Step {N}: --branch overridden by run-time value (baked '{old}' → '{new}')`.
+   - If it appears with the **same** value, leave the single baked copy (no duplicate).
+   - If it does not appear, append the run-time flag (and its value).
+
+   This makes precedence deterministic: run-time `PASSTHROUGH_FLAGS` always take effect, and a flag never appears twice. Call the result `RESOLVED_COMMAND`. Report: `▶ Step {N}: {RESOLVED_COMMAND}`
 
 2. Read `FLOW_DIR/implementation/step-N.md` to get the agent prompt. Prepare the prompt for this run by filling its injection points:
    - Replace `{step-command}` occurrences with `RESOLVED_COMMAND` (substitute `{{placeholders}}` here too).

skills/flow/references/workflows/help.md

@@ -25,6 +25,12 @@ Storage:
   local  (default)   .codevoyant/flows/<slug>/       — this project only
   global (--global)  ~/.codevoyant/flows/<slug>/      — reusable across all projects
 
+Forwarding flags to steps:
+  Any flag other than --global/-g (and --set for `go`) is forwarded to every step
+  command — e.g. run a flow's steps on a branch:
+    /flow new ship "/spec new {{input}}" "/spec go" --branch feature/x   (bakes it in)
+    /flow go ship "add OAuth" --branch feature/x                          (one-off run)
+
 Parameters (dynamic input):
   Put {{placeholders}} in any step. At run time:
     • bare text after the name binds to {{input}}