ktg-plugin-marketplace/plugins/voyage/CLAUDE.md

trekplan

Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execute, review, continue. Deep implementation planning and research with specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support.

Design principle: Context Engineering — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes.

v3.0.0 — architect step extracted from this plugin. The plan command still auto-discovers architecture/overview.md if present, so any compatible producer (architect plugin no longer publicly distributed; the architecture/overview.md slot remains available for any compatible producer) plugs into the same slot. See CHANGELOG.md for migration history.

Commands

Command	Description	Model
/trekbrief	Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline	opus
/trekresearch	Research — deep local + external research, produces structured research brief	opus
/trekplan	Plan — brief-reviewer, explore, plan, review. Requires --brief or --project. Auto-discovers architecture/overview.md if present	opus
/trekexecute	Execute — disciplined plan/session-spec executor with failure recovery	opus
/trekreview	Review — independent post-hoc review of delivered code against the brief. Produces review.md with severity-tagged findings (Handover 6)	opus
/trekcontinue	Continue — resumes the next session of a multi-session voyage project. Reads .session-state.local.json (Handover 7) and immediately begins executing	opus
/trekendsession	End-session — mark the current session complete and write session-state pointing at the next session. Helper for informal multi-session flows	sonnet

/trekbrief modes

Flag	Behavior
(default)	Dynamic interview until quality gates pass → brief.md with research plan
--quick	Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile: economy / balanced / premium / <custom>. Sets phase_models for the brief phase. See ## Profile system below.

Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a brief-reviewer stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).

/trekresearch modes

Flag	Behavior
(default)	Interview + research (local + external) + synthesis + brief (foreground)
--project <dir>	Write brief to {dir}/research/{NN}-{slug}.md (auto-incremented)
--quick	Interview (short) + inline research (no agent swarm)
--local	Only codebase analysis agents (skip external + Gemini)
--external	Only external research agents (skip codebase analysis)
--fg	No-op alias (foreground is default since v2.4.0)
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile for the research phase. See ## Profile system below.

Flags combine: --project <dir> --local, --external --quick.

/trekplan modes

Flag	Behavior
--project <dir>	Required path A — read {dir}/brief.md, auto-discover {dir}/research/*.md, write {dir}/plan.md
--brief <path>	Required path B — plan from a specific brief file; write to .claude/plans/trekplan-{date}-{slug}.md
--research <brief> [brief2]	Enrich with extra research briefs beyond what is in {project_dir}/research/
--fg	No-op alias (foreground is default since v2.4.0)
--quick	Plan directly (no agent swarm)
--export <pr|issue|markdown|headless> <plan>	Generate shareable output from existing plan
--decompose <plan>	Split plan into self-contained headless sessions
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile for the plan phase (and others, since plan emits profile: to plan.md frontmatter). See ## Profile system below.

Breaking change (v2.0): one of --brief or --project is required. There is no interview inside /trekplan. The --spec flag has been removed — use /trekbrief to produce a brief instead.

If {project_dir}/architecture/overview.md exists (typically produced by an opt-in upstream architect plugin, not bundled), the plan command auto-discovers it and treats cc_features_proposed as priors. Missing file is fine — discovery is additive, not required.

/trekexecute modes

Flag	Behavior
(default)	Execute plan — auto-detects Execution Strategy for multi-session
--project <dir>	Read {dir}/plan.md, write {dir}/progress.json
--resume	Resume from last progress checkpoint
--dry-run	Validate plan structure without executing
--validate	Schema-only check — parse steps + manifests, report READY | FAIL, no execution
--step N	Execute only step N
--fg	Force foreground — run all steps sequentially, ignore Execution Strategy
--session N	Execute only session N from plan's Execution Strategy
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile for the execute phase. Inherited from plan.md frontmatter profile: if present. See ## Profile system below.

/trekreview modes

Flag	Behavior
(default)	Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write {project_dir}/review.md
--project <dir>	Required. Path to trekplan project folder containing brief.md. Review is written to {dir}/review.md
--since <ref>	Override "before" SHA for the diff range. Validated via git rev-parse --verify
--quick	Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass
--validate	Schema-only check on existing {dir}/review.md. No LLM calls
--dry-run	Print discovered scope + triage map; skip writes
--fg	No-op alias (foreground is default)
--profile <name>	(v4.1.0) Model profile for the review phase. See ## Profile system below.

/trekcontinue modes

Flag	Behavior
(default)	Auto-discover active project's .session-state.local.json and resume
<project-dir>	Resume the next session of an explicit project directory
--profile <name>	(v4.1.0) Model profile for the resumed session. Inherited from the previous session's plan.md frontmatter when absent. See ## Profile system below.

The triage gate is deterministic — path-pattern classifier produces {file → deep-review|summary-only|skip}. Hard refuse-with-suggestion above 100 files / 100K diff tokens.

Agents

Agent	Model	Role
planning-orchestrator	opus	Inline reference documentation for the planning pipeline workflow (brief-driven)
research-orchestrator	opus	Inline reference documentation for the research pipeline workflow
review-orchestrator	opus	Inline reference documentation for the review pipeline workflow
architecture-mapper	sonnet	Codebase structure, tech stack, patterns
dependency-tracer	sonnet	Import chains, data flow, side effects
task-finder	sonnet	Task-relevant files, functions, reuse candidates
risk-assessor	sonnet	Risks, edge cases, failure modes
test-strategist	sonnet	Test patterns, coverage gaps, strategy
git-historian	sonnet	Recent changes, ownership, hot files
research-scout	sonnet	External docs for unfamiliar tech (conditional, planning only)
convention-scanner	sonnet	Coding conventions: naming, style, error handling, test patterns
brief-reviewer	sonnet	Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity)
brief-conformance-reviewer	sonnet	Brief conformance review (SC + Non-Goal traceability)
code-correctness-reviewer	sonnet	Code correctness review (7 dimensions)
review-coordinator	sonnet	Judge Agent — dedup + reasonableness filter + verdict
plan-critic	sonnet	Adversarial plan review (9 dimensions)
scope-guardian	sonnet	Scope alignment (creep + gaps)
session-decomposer	sonnet	Splits plans into headless sessions with dependency graph
docs-researcher	sonnet	Official documentation, RFCs, vendor docs (Tavily, MS Learn)
community-researcher	sonnet	Community experience: issues, blogs, discussions
security-researcher	sonnet	CVEs, audit history, supply chain risks
contrarian-researcher	sonnet	Counter-evidence, overlooked alternatives
gemini-bridge	sonnet	Gemini Deep Research second opinion (conditional)

Quality infrastructure (v3.4.0)

lib/ contains zero-dep validators, parsers, and autonomy primitives wired into the four commands:

• lib/util/{frontmatter,result,atomic-write,autonomy-gate}.mjs — shared YAML-frontmatter parser + Result helpers + atomicWriteJson(path, obj) for tmp+rename writes + autonomy-gate state machine (v3.4.0)
• lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize,jaccard,finding-id}.mjs — pure parsers (no I/O), unit-tested. manifest-yaml extended in v3.4.0 with additive skip_commit_check + memory_write flags (forward-compat: unknown keys ignored)
• lib/review/{rule-catalogue,plan-review-dedup}.mjs — version-pinned rule catalogue (12 keys) + Phase 9 inline dedup helpers (v3.4.0)
• lib/stats/event-emit.mjs — single-source stats event emitter for autonomy-gate transitions and main-merge-gate (v3.4.0)
• lib/validators/{brief,research,plan,progress,session-state}-validator.mjs — schema validators with CLI shims (node lib/validators/X.mjs --json <path>)
• lib/validators/architecture-discovery.mjs — drift-WARN external-contract discovery for architecture/overview.md

Wiring points (replaces previous prose-grep instructions):

• /trekbrief Phase 4g → brief-validator (post-write sanity check)
• /trekplan Phase 1 → brief-validator --soft, research-validator --dir, architecture-discovery
• planning-orchestrator Phase 5.5 → plan-validator --strict (replaces 3 grep -cE calls)
• /trekexecute --validate → plan-validator --strict + progress-validator

Tests under tests/**/*.test.mjs (~290 tests, 0 deps). npm test is the fork-readiness gate. v3.4.0 adds: synthetic determinism fixtures (tests/synthetic/plan-run-*.md + review-run-*.md + companion *-determinism.test.mjs enforcing Jaccard ≥ 0.833 SC7 floor) and hook baseline regression pins (tests/hooks/{path-guard,bash-guard}.test.mjs exercising pre-write-executor.mjs + pre-bash-executor.mjs denylist BLOCK paths).

Doc-consistency test at tests/lib/doc-consistency.test.mjs pins agent-table count, command-table coverage, plan_version invariant, settings.json scope cleanliness, Handover 7 presence, and session-state-validator CLI shim.

docs/HANDOVER-CONTRACTS.md is the single source of truth for the 7 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume, review→plan, .session-state.local.json). Read it before changing any artifact format.

hooks/scripts/pre-compact-flush.mjs (PreCompact event, CC v2.1.105+) fixes the documented P0 in docs/trekexecute-v2-observations-from-config-audit-v4.md: keeps progress.json in sync with git history before context compaction so --resume works after long conversations. Atomic write, monotonic only, never blocks compaction.

hooks/scripts/session-title.mjs (UserPromptSubmit, CC v2.1.94+) sets sessionTitle to voyage:<command>:<slug> for voyage-command invocations. Helps multi-session headless runs identify themselves in process lists.

hooks/scripts/post-bash-stats.mjs (PostToolUse, CC v2.1.97+) appends duration_ms for each Bash call into ${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl. Useful for finding long-running verify or checkpoint commands.

hooks/scripts/post-compact-flush.mjs (PostCompact event, v3.4.0) re-injects .session-state.local.json after context compaction so multi-session work survives a compaction boundary. Companion to pre-compact-flush.mjs (which writes the state file before compaction); together they form the rehydrate cycle that keeps /trekcontinue reliable across long-running multi-session work.

Autonomy mode (--gates, v3.4.0)

All four pipeline commands accept --gates {open|closed|adaptive}:

Value	Behavior
open	Skip optional checkpoints; trust manifests + verify gates only
closed	Stop at every autonomy boundary; operator confirms each transition
adaptive (default)	Stop only at meaningful boundaries (manifest-audit FAIL, plan-critic BLOCKER, main-merge gate)

Under the hood: lib/util/autonomy-gate.mjs runs the state machine idle → approved → executing → merge-pending → main-merged. lib/stats/event-emit.mjs records each transition to ${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl. The main-merge gate is the final autonomy boundary before HEAD lands on main.

Path A/B/C decision (v3.4.0; Path C closed 2026-05-05)

Three architectural options were considered for the speedup work:

• Path A — cache-first (drop --allowedTools per child to recover cross-phase cache sharing): REJECTED. Inverts the security model; plugin hooks don't fire reliably in claude -p (research/06 GH #36071).
• Path B — sequential --no-ff parallel waves with manifest-driven failure recovery: CHOSEN. Ships in v3.4.0. Phase 2.6 of /trekexecute runs the wave executor with hardenings for plugin-in-monorepo + gitignored-state topology.
• Path C — hybrid (cache-warm sentinel + identical-tool parallel): CLOSED 2026-05-05. Q3 experiment measured median cache_creation_input_tokens = 163,903 across 3 fork-children at 186K parent context (CC v2.1.128, Sonnet 4.6). Master-plan thresholds: ≤ 1,500 POSITIVE / ≥ 3,500 NEGATIVE. Result is solidly NEGATIVE — CLAUDE_CODE_FORK_SUBAGENT does not preserve cache prefix across identical-tool children at our context size. Path C migration is deferred indefinitely; reassessment is appropriate when CC v2.2.xxx ships fork-cache-relevant features. Harness: scripts/q3-cache-prefix-experiment.mjs. Companion analyser: lib/stats/cache-analyzer.mjs.

A revived Path C (post-v2.2.xxx) would require: (1) re-architecting tool-list to be identical across all wave children, (2) cache-telemetry analysis confirming the new fork-cache behaviour holds, (3) prompt-level deny re-enablement to compensate for tool scoping rollback.

Profile system (--profile, v4.1.0)

Three built-in model profiles plus operator-defined <custom>.yaml. Each profile pins phase_models for the six pipeline phases (brief, research, plan, execute, review, continue). Profile is recorded in plan.md frontmatter as profile: <name> and emitted to ${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl for cost-attribution.

Profile	Brief	Research	Plan	Execute	Review	Continue	Use case
economy	sonnet	sonnet	sonnet	sonnet	sonnet	sonnet	Lowest cost; high-confidence small-scope tasks
balanced (default)	sonnet	sonnet	opus	sonnet	opus	sonnet	Default — opus where reasoning depth pays off
premium	opus	sonnet	opus	sonnet	opus	sonnet	Critical-path planning + review when budget allows

Lookup order

1. Explicit --profile <name> flag passed to the command
2. Plan-file frontmatter profile: (when resuming via /trekexecute --resume or /trekcontinue)
3. VOYAGE_PROFILE environment variable
4. Default balanced

Custom profiles

Create lib/profiles/<custom>.yaml to define a new tier. The validator (lib/validators/profile-validator.mjs) enforces: every phase_models[].phase must be a known phase enum; every phase_models[].model must match ^(opus|sonnet)(\b|-).* or one of the canonical short names. Custom profiles override built-ins of the same name (lookup is alphabetical with <custom> taking precedence).

Drift between plan-frontmatter profile: and step-manifest profile_used: emits a MANIFEST_PROFILE_DRIFT warning from plan-validator --strict (Step 20). Plan remains valid; the warning surfaces accidental tier-mismatch.

Observability (Stop hook, v4.1.0)

The Stop hook in hooks/hooks.json runs hooks/scripts/otel-export.mjs at session-end. The hook is opt-in — when VOYAGE_EXPORT_MODE is unset or off, no work is done.

Mode	Output	Endpoint env-var
off (default)	(no export)	—
textfile	voyage.prom (Prometheus exposition format)	VOYAGE_TEXTFILE_DIR
otlp	OTLP/JSON POST	VOYAGE_OTEL_ENDPOINT

Endpoint validation: VOYAGE_OTEL_ALLOW_PRIVATE=1 is required to send to loopback or RFC1918 destinations (CWE-918 SSRF mitigation). Allowlist lib/exporters/field-allowlist.mjs redacts records before export (CWE-212). Path validation (lib/exporters/path-validator.mjs) rejects symlink + traversal (CWE-22).

Local Docker Compose stack: examples/observability/. Operator docs: docs/observability.md. Both pin minimum versions per CVE history (prom/prometheus:v3.0.1, grafana/grafana:11.4.0, otel/opentelemetry-collector-contrib:0.115.0).

Architecture

Brief: 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 4 draft/review/revise with brief-reviewer as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (brief.md on pass, or brief_quality: partial on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode runs research + plan inline in the main context (v2.4.0).

Research: Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With --project, writes to {dir}/research/NN-slug.md.

Plan: Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (brief-reviewer) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (plan-critic + scope-guardian) → Present/refine → Handoff. With --project, writes to {dir}/plan.md and auto-detects {dir}/architecture/overview.md (produced by an opt-in upstream architect plugin if installed; not bundled).

Decompose: Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.

Execute: Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via claude -p with scoped --allowedTools) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes progress.json + .session-state.local.json (Handover 7) → Report. With --project, reads {dir}/plan.md. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write .session-state.local.json so /trekcontinue can surface the stop and prompt for next steps.

Continue: /trekcontinue reads {dir}/.session-state.local.json (Handover 7), validates schema-v1 via session-state-validator, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under .claude/projects/*/.session-state.local.json if no explicit <project-dir> argument. Operator-invoked only — never auto-loaded via SessionStart. The /trekendsession helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through /trekexecute.

Operator-annotation HTML (v5.0.2): the last step of /trekbrief, /trekplan, and /trekreview runs scripts/annotate.mjs against the just-written .md and prints the resulting file://<abs path> link. The HTML is self-contained (zero npm deps, zero external network, design-system-styled, light + dark + print), and built around the operator. The operator opens the file, clicks any line of the document, writes their own note in an inline textarea, hits Save. The sidebar collects every note (editable + deletable, sorted by line). Notes persist in localStorage per artifact path — refresh or browser-close doesn't lose work. A "Copy Prompt" button at the bottom assembles every note into one structured prompt; the operator copies it and pastes it back into Claude, and Claude revises the .md freehand from the notes. The operator drives every annotation. Claude does not pre-generate suggestions in this flow — that was the v5.0.1 path (via /playground document-critique), which inverted the direction the operator actually wanted. v5.0.2 makes the loop OPERATOR-LEADS, CLAUDE-REACTS, which is what was asked for all along. The v5.0.0 standalone .html render (scripts/render-artifact.mjs) was a read-only view that didn't afford annotation; the v4.2/v4.3 bespoke playground SPA + /trekrevise + Handover 8 were 388 KB of broken UX. Both stay removed. See CHANGELOG.md § v5.0.2.

Security: 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped --allowedTools replacing --dangerously-skip-permissions. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.

Pipeline: /trekbrief produces the task brief. /trekresearch --project <dir> fills in {dir}/research/. /trekplan --project <dir> reads brief + research to produce {dir}/plan.md (and auto-discovers {dir}/architecture/overview.md if an opt-in upstream architect plugin produced one). /trekexecute --project <dir> executes and writes {dir}/progress.json. /trekreview --project <dir> produces {dir}/review.md. /trekbrief, /trekplan, and /trekreview each end by running scripts/annotate.mjs on the just-written artifact, producing {dir}/{artifact}.html — a self-contained operator-annotation surface — and printing the file:// link. The operator opens it, clicks lines, writes their own notes, copies a structured prompt, pastes back, Claude revises the .md. All artifacts live in one project directory.

Project-directory contract (v3.0.0): trekplan owns the directory layout below. The architecture/ subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the architecture/overview.md slot remains available for any compatible producer.

.claude/projects/{YYYY-MM-DD}-{slug}/
  brief.md           ← trekbrief writes; everyone reads
  brief.html         ← trekbrief annotates (operator-annotation HTML, gitignored, re-buildable from brief.md)
  research/*.md      ← trekresearch writes; plan + architect read
  architecture/      ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled)
    overview.md
    gaps.md
  plan.md            ← trekplan writes; trekexecute reads
  plan.html          ← trekplan annotates
  progress.json      ← trekexecute writes
  review.md          ← trekreview writes; trekplan reads (Handover 6)
  review.html        ← trekreview annotates

The .html files (brief.html, plan.html, review.html) are produced by scripts/annotate.mjs and live alongside their .md siblings in the project directory. They are re-buildable from the .md source at any time (deterministic, byte-identical output on re-run), so they are conventionally gitignored along with the rest of .claude/projects/. Operator annotations live in browser localStorage keyed on the absolute artifact path — they survive refresh and browser-close, but are local to the operator's machine.

No code-level dependency between plugins — the contract is filesystem-level only.

State

All artifacts in one project directory (default):

• Project root: .claude/projects/{YYYY-MM-DD}-{slug}/
  • brief.md + brief.html (task brief from /trekbrief; .html is the operator-annotation surface from scripts/annotate.mjs)
  • research/{NN}-{slug}.md (research briefs from /trekresearch --project)
  • architecture/overview.md + architecture/gaps.md (opt-in, produced by an opt-in upstream architect plugin, not bundled)
  • plan.md + plan.html (from /trekplan --project)
  • sessions/session-*.md (from --decompose)
  • progress.json (from /trekexecute --project)
  • review.md + review.html (from /trekreview --project)
  • .session-state.local.json (Handover 7 — gitignored via *.local.json; written by /trekexecute Phase 8/2.55/4 or /trekendsession; read by /trekcontinue)

Legacy paths (still work without --project):

• Research briefs: .claude/research/trekresearch-{date}-{slug}.md
• Plans: .claude/plans/trekplan-{date}-{slug}.md
• Sessions: .claude/trekplan-sessions/{slug}/session-*.md
• Launch scripts: .claude/trekplan-sessions/{slug}/launch.sh
• Progress: {plan-dir}/.trekexecute-progress-{slug}.json

Stats:

• Brief stats: ${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl
• Plan stats: ${CLAUDE_PLUGIN_DATA}/trekplan-stats.jsonl
• Exec stats: ${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl
• Research stats: ${CLAUDE_PLUGIN_DATA}/trekresearch-stats.jsonl
• Continue stats: ${CLAUDE_PLUGIN_DATA}/trekcontinue-stats.jsonl

Terminology

• Task brief — produced by /trekbrief. Declares intent, goal, and research plan. Drives planning.
• Research brief — produced by /trekresearch. Answers a specific research question. Feeds planning.
• Architecture note — opt-in, produced by an opt-in upstream architect plugin (not bundled; the architect plugin is no longer publicly distributed, but the architecture/overview.md filesystem slot remains available for any compatible producer). Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning.
• Review — produced by /trekreview. Independent post-hoc review of delivered code against the task brief. Handover 6 (review → plan) routes BLOCKER + MAJOR findings into /trekplan --brief review.md for a remediation plan. The plan's optional source_findings: frontmatter list is the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
• Session state — .session-state.local.json per project. Handover 7 — produced by any session-end mechanism (/trekexecute Phase 8/2.55/4, /trekendsession helper, future graceful-handoff v2.2). Consumed by /trekcontinue to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via *.local.json).

A project typically has 1 task brief, 0–N research briefs, 0 or 1 architecture note, 0–N reviews (one per review iteration), and 0 or 1 session-state file (overwritten on every session-end).