refactor(voyage): S31 — V15 trim plan-export to headless-only (decompose alias)

Drop the pr/issue/markdown variants from `/trekplan --export`. Claude Code
reformats a plan into a PR body, issue comment, or stripped markdown ad-hoc
on request, so a dedicated export path added maintenance without value.
Keep `--export headless` as a backwards-compatible alias for `--decompose`
and relabel it as the decomposition entry it actually is.

- commands/trekplan.md: Phase 1 parse rejects non-headless formats and sets
  mode = decompose for headless; delete the Export phase; rename Phase 1.6 →
  Phase 1.5 (Decompose); update the mode enum, argument-hint, and usage block.
- docs/command-modes.md, README.md: export row relabeled as a --decompose alias.
- tests/commands/trekplan.test.mjs: +2 V15 pins (variants gone, headless kept).

Non-breaking (plan D-register). Tests 731 (729 pass / 2 skip / 0 fail), bar
`node --test`; `claude plugin validate` green (1 accepted warning).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB

README.md

@@ -236,7 +236,7 @@ Output:
 | **Foreground** | `/trekplan --project <dir> --fg` | No-op alias (foreground is default since v2.4.0) |
 | **Quick** | `/trekplan --project <dir> --quick` | No agent swarm, lightweight scan only |
 | **Decompose** | `/trekplan --decompose plan.md` | Split plan into headless session specs |
-| **Export** | `/trekplan --export pr plan.md` | PR description, issue comment, or clean markdown |
+| **Export** | `/trekplan --export headless plan.md` | Legacy alias for `--decompose` (the only remaining export format) |
 | **Profile** | `/trekplan --profile <name> --project <dir>` | (v4.1.0) Pin model profile; emitted as `profile:` in plan.md frontmatter. See [Profile system](#profile-system-v410). |
 
 `--brief` or `--project` is **required**. `/trekplan` with no brief exits with an error and a pointer to `/trekbrief`.

commands/trekplan.md

@@ -1,7 +1,7 @@
 ---
 name: trekplan
 description: Deep implementation planning from a task brief. Requires --brief or --project. Runs parallel specialized agents, optional external research, and adversarial review.
-argument-hint: "--brief <path> | --project <dir> [--fg | --quick | --research <brief> | --decompose <plan> | --export <fmt> <plan>]"
+argument-hint: "--brief <path> | --project <dir> [--fg | --quick | --research <brief> | --decompose <plan> | --export headless <plan>]"
 model: opus
 allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
 ---
@@ -30,13 +30,19 @@ Pipeline position:
 
 Parse `$ARGUMENTS` for mode flags. Order of precedence:
 
-1. **`--export <format> <plan-path>`** — extract `{format}` (first token after
+1. **`--export headless <plan-path>`** — extract `{format}` (first token after
-   `--export`) and `{plan-path}` (remainder). Valid formats: `pr`, `issue`,
+   `--export`) and `{plan-path}` (remainder). `headless` is the only export
-   `markdown`, `headless`. Set **mode = export**.
+   format; it is a backwards-compatible **alias for `--decompose`**. Set
+   **mode = decompose** and run the decomposition pipeline (Phase 1.5).
 
-   If format is not in the valid set:
+   The PR / issue / markdown export variants were removed — Claude Code
+   reformats a plan into a PR body, issue comment, or stripped markdown
+   ad-hoc on request, so a dedicated export path added maintenance without
+   value. If `{format}` is anything other than `headless`:
    ```
-   Error: unknown export format '{format}'. Valid: pr, issue, markdown, headless
+   Error: export format '{format}' is not supported. The only export is
+   'headless' (an alias for --decompose). For PR / issue / markdown output,
+   ask Claude to reformat the plan directly.
    ```
    If the plan file does not exist:
    ```
@@ -140,7 +146,7 @@ Usage: /trekplan --brief <path-to-brief.md>
        /trekplan --brief <path> --research <research-brief.md>
        /trekplan --project <dir> --fg
        /trekplan --project <dir> --quick
-       /trekplan --export <pr|issue|markdown|headless> <plan-path>
+       /trekplan --export headless <plan-path>
        /trekplan --decompose <plan-path>
 
 A brief is required. Produce one with /trekbrief first.
@@ -152,7 +158,7 @@ Modes:
   --fg          No-op alias (foreground is the only mode as of v2.4.0)
   --quick       Skip exploration agent swarm; plan directly
   --min-brief-version <ver>  Warn (never block) if the brief is older than <ver> (e.g. 2.2)
-  --export      Generate shareable output from an existing plan (no new planning)
+  --export headless  Legacy alias for --decompose (the only remaining export format)
   --decompose   Split an existing plan into self-contained headless sessions
 
 Examples:
@@ -160,7 +166,7 @@ Examples:
   /trekplan --brief .claude/projects/2026-04-18-jwt-auth/brief.md
   /trekplan --project .claude/projects/2026-04-18-jwt-auth --research extra.md
   /trekplan --project .claude/projects/2026-04-18-jwt-auth --fg
-  /trekplan --export pr .claude/plans/trekplan-2026-04-06-rate-limiting.md
+  /trekplan --export headless .claude/plans/trekplan-2026-04-06-rate-limiting.md
   /trekplan --decompose .claude/plans/trekplan-2026-04-06-rate-limiting.md
 
 Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
@@ -187,7 +193,7 @@ If `research_status == pending` and `research_topics > 0`:
 
 Report the detected mode:
 ```
-Mode:    {foreground | quick | export | decompose}
+Mode:    {foreground | quick | decompose}
 Brief:   {brief_path}
 Project: {project_dir or "-"}
 Research: {N local briefs, M extra via --research}
@@ -233,89 +239,10 @@ If `fm.type === 'trekreview'`:
 `type: brief` input simply omit the field. No `plan_version` bump is
 required for this addition (backwards compatible).
 
-## Phase 1.5 — Export (runs only when mode = export)
+## Phase 1.5 — Decompose (runs only when mode = decompose)
 
-**Skip this phase entirely unless mode = export.**
+**Skip this phase entirely unless mode = decompose.** (`--export headless` is a
-
+backwards-compatible alias that sets mode = decompose, so it lands here too.)
-Read the plan file. Extract these sections from the plan content:
-- Task description (from Context section)
-- Implementation steps (from Implementation Plan section)
-- Risks (from Risks and Mitigations section)
-- Test strategy (from Test Strategy section, if present)
-- Scope estimate (from Estimated Scope section)
-
-### Format: `pr`
-
-Output a markdown block formatted as a PR description:
-
-```
-## Summary
-
-{2–3 sentence summary of what this change does and why}
-
-## Changes
-
-{Bulleted list of implementation steps, one line each}
-
-## Test plan
-
-{Bulleted checklist from test strategy, formatted as - [ ] items}
-
-## Risks
-
-{Risks from plan, abbreviated to 1 line each}
-
----
-*Generated by trekplan from {plan filename}*
-```
-
-### Format: `issue`
-
-Output a markdown block formatted as an issue comment:
-
-```
-## Implementation plan summary
-
-**Task:** {task description}
-**Plan file:** {plan path}
-**Scope:** {N files, complexity}
-
-### Proposed approach
-{3–5 bullet points from key implementation steps}
-
-### Open questions / risks
-{Top 2–3 risks from plan}
-
----
-*Generated by trekplan*
-```
-
-### Format: `markdown`
-
-Output the plan content with internal metadata stripped:
-- Remove the "Revisions" section
-- Remove plan-critic and scope-guardian scores/verdicts
-- Remove `[ASSUMPTION]` markers (but keep the surrounding sentence)
-- Keep everything else verbatim
-
-### Format: `headless`
-
-This is a shortcut for `--decompose`. It runs the full session decomposition
-pipeline and is equivalent to `--decompose {plan-path}`. Proceed to
-Phase 1.6 (Decompose) below.
-
----
-
-After outputting the formatted block (for pr/issue/markdown), say:
-```
-Export complete ({format}). Copy the block above.
-```
-
-Then **stop**. Do not continue to any subsequent phase.
-
-## Phase 1.6 — Decompose (runs only when mode = decompose or export headless)
-
-**Skip this phase entirely unless mode = decompose or export format = headless.**
 
 Read the plan file. Verify it contains an Implementation Plan section with
 numbered steps. If no steps are found, report and stop:

docs/command-modes.md

@@ -39,7 +39,7 @@ Flags combine: `--project <dir> --local`, `--external --quick`.
 | `--fg` | No-op alias (foreground is default since v2.4.0) |
 | `--quick` | Plan directly (no agent swarm) |
 | `--min-brief-version <ver>` | (S18) Warn — never block — if the brief declares a version below `<ver>` (e.g. `2.2`), i.e. sidesteps framing enforcement |
-| `--export <pr\|issue\|markdown\|headless> <plan>` | Generate shareable output from existing plan |
+| `--export headless <plan>` | Legacy alias for `--decompose` — the only remaining export format (the `pr` / `issue` / `markdown` variants were removed; Claude reformats a plan ad-hoc on request) |
 | `--decompose <plan>` | Split plan into self-contained headless sessions |
 | `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
 | `--profile <name>` | (v4.1.0) Model profile for the plan phase (and others, since plan emits `profile:` to plan.md frontmatter). |

tests/commands/trekplan.test.mjs

@@ -71,3 +71,22 @@ test('trekplan — SC7: brief_version 2.1 + no phase_signals + no partial → BR
     `sequencing gate must fire; errors=${JSON.stringify(r.errors)}`,
   );
 });
+
+// --- S31 / V15: export trim — drop pr|issue|markdown, keep headless as a --decompose alias ---
+
+test('trekplan — V15: pr/issue/markdown export variants are removed', () => {
+  const text = read();
+  // No remaining `--export pr` usage/example anywhere in the command.
+  assert.equal(/--export\s+pr\b/.test(text), false, '`--export pr` must be gone');
+  // The per-format subsections of the old Export phase must be deleted.
+  assert.ok(!text.includes('Format: `pr`'), 'pr export-format section must be gone');
+  assert.ok(!text.includes('Format: `issue`'), 'issue export-format section must be gone');
+  assert.ok(!text.includes('Format: `markdown`'), 'markdown export-format section must be gone');
+});
+
+test('trekplan — V15: --export headless survives as a --decompose alias', () => {
+  const text = read();
+  assert.match(text, /--export\s+headless/, '`--export headless` must remain documented');
+  assert.match(text, /alias for [`*]*--decompose/i,
+    '`--export headless` must be labeled an alias for --decompose');
+});