@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/guides/planner.md

@@ -1,220 +0,0 @@
-# Planner Guide
-
-The planner foundation is the first structured authoring layer on top of the existing wave runtime.
-
-If you want the full author-to-launch workflow, start with [author-and-run-waves.md](./author-and-run-waves.md). This page stays focused on planner-specific behavior.
-
-It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
-
-The published `0.8.9` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
-
-## What Ships Today
-
-- `wave project setup`
-- `wave project show`
-- interactive `wave draft --wave <n>`
-- agentic `wave draft --agentic --task "..."`
-- planner run review via `wave draft --show-run <run-id>`
-- explicit materialization via `wave draft --apply-run <run-id>`
-- worker role kinds including optional `design`
-- persistent project memory in `.wave/project-profile.json`
-- transient planner packets in `.wave/planner/runs/<run-id>/`
-- planner-run Context7 injection via `planner.agentic.context7Bundle`
-- JSON specs in `docs/plans/waves/specs/wave-<n>.json`
-- rendered markdown waves in `docs/plans/waves/wave-<n>.md`
-- candidate matrix previews plus canonical component matrix updates on apply
-
-## Upgrading Adopted 0.6.x Repos
-
-`wave upgrade` updates the installed runtime and records `.wave/install-state.json`, but it does not copy newer planner starter files into an already-adopted repo.
-
-If `pnpm exec wave doctor` starts failing after a `0.7.x` upgrade, sync these repo-owned planner surfaces from the packaged release:
-
-- `docs/agents/wave-planner-role.md`
-- `skills/role-planner/`
-- `docs/context7/planner-agent/`
-- `docs/reference/wave-planning-lessons.md`
-- the `planner-agentic` bundle entry in `docs/context7/bundles.json`
-
-Then rerun:
-
-```bash
-pnpm exec wave doctor
-pnpm exec wave launch --lane main --dry-run --no-dashboard
-```
-
-## What The Planner Does Not Yet Ship
-
-- forward replanning of later waves
-- separate runtime enforcement for oversight vs dark-factory
-
-Those remain roadmap work. The planner foundation is about better structured authoring, not a second execution engine.
-
-## Project Profile
-
-Run:
-
-```bash
-pnpm exec wave project setup
-pnpm exec wave project show --json
-```
-
-The saved profile remembers:
-
-- whether the repo is a new project
-- default oversight mode
-- default terminal surface for live runs (`vscode` or `tmux`; `none` remains dry-run only)
-- default draft template
-- default lane
-- typed deploy environments
-
-This lets later drafts inherit repo-specific defaults instead of asking the same bootstrap questions every time.
-
-## Drafting A Wave
-
-Interactive draft:
-
-```bash
-pnpm exec wave draft --wave 1 --template implementation
-```
-
-Agentic draft:
-
-```bash
-pnpm exec wave draft --agentic --task "Add X according to the current architecture" --from-wave 3 --max-waves 2
-pnpm exec wave draft --show-run <run-id> --json
-pnpm exec wave draft --apply-run <run-id> --waves all
-```
-
-The planner agent reads repo-local planning sources directly, and it can also
-prefetch a planner-specific Context7 bundle when
-`planner.agentic.context7Bundle` points at a published library. The tracked
-source corpus for that library lives under `docs/context7/planner-agent/`.
-This repo keeps that bundle as a local-only placeholder until a published
-Context7 library exists and its exact `libraryId` is known.
-
-Supported templates today:
-
-- `implementation`
-- `qa`
-- `infra`
-- `release`
-
-Supported worker role kinds today:
-
-- `design`
-- `implementation`
-- `qa`
-- `infra`
-- `deploy`
-- `research`
-- `security`
-
-The interactive draft flow now offers `design` as a first-class worker role. Agentic planner payloads also accept `workerAgents[].roleKind = "design"`.
-
-`design` uses the `design-pass` executor profile by default and scaffolds the docs-first packet path before coding starts. The normal starter packet path is:
-
-- `docs/plans/waves/design/wave-<n>-<agentId>.md`
-
-If you want a hybrid design steward, keep the same design packet path but explicitly add implementation-owned paths and the normal implementation contract sections in the authored wave or agentic planner payload. Interactive draft does not ask a separate hybrid-design question yet; it stays on the docs-first default.
-
-Interactive draft writes canonical waves immediately:
-
-- `docs/plans/waves/specs/wave-<n>.json`
-- `docs/plans/waves/wave-<n>.md`
-
-Agentic draft writes a transient review packet first:
-
-- `.wave/planner/runs/<run-id>/request.json`
-- `.wave/planner/runs/<run-id>/sources.json`
-- `.wave/planner/runs/<run-id>/plan.json`
-- `.wave/planner/runs/<run-id>/verification.json`
-- `.wave/planner/runs/<run-id>/candidate/specs/wave-<n>.json`
-- `.wave/planner/runs/<run-id>/candidate/waves/wave-<n>.md`
-
-Canonical `docs/plans/waves/` files are only written by `--apply-run`.
-
-The transient packet also includes the exact planner prompt and the resolved
-planner Context7 selection, so review can see which external planning corpus was
-attached before the planner drafted waves.
-
-## What The Planner Asks For
-
-The draft flow asks for structured inputs such as:
-
-- wave title and commit message
-- sequencing notes and reference rules
-- oversight mode
-- deploy environments in scope
-- component promotions and target levels
-- worker count and worker roles
-- whether a wave needs a pre-implementation design steward
-- executor profiles
-- file ownership
-- Context7 defaults and per-agent bundles
-- validation commands
-- exit contracts
-
-That gives you a wave that is much closer to launch-ready than a blank markdown template.
-
-## When To Use `design`
-
-Use a design worker when the wave is heavy on:
-
-- architecture or sequencing decisions
-- interface or contract changes across multiple owners
-- ambiguous requirements that should become explicit assumptions and open questions
-- decision-lineage that downstream implementers should not have to rediscover
-
-Do not use a design worker just because the wave is large. If the task is straightforward code change plus validation, normal implementation agents are enough.
-
-A design worker should usually:
-
-- import `docs/agents/wave-design-role.md`
-- own one design packet under `docs/plans/waves/design/`
-- stay docs/spec-only unless the wave explicitly assigns code ownership
-- add `tui-design` in `### Skills` when the packet owns terminal UX, dashboards, or other operator surfaces
-- emit a final `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> ...` marker
-
-If the wave does explicitly assign code ownership, the same design agent becomes a hybrid design steward: it runs the design pass first, then rejoins implementation with the normal implementation proof contract while still keeping the packet current and re-emitting `[wave-design]`.
-
-## Planner And Skills
-
-The planner does not auto-discover every possible skill bundle yet, but it supports explicit per-agent `### Skills` in the rendered output.
-
-Interactive `wave draft --wave <n>` now resolves bundle names from
-`docs/context7/bundles.json`, so wave-level and per-agent Context7 selections
-can use any configured bundle instead of only `none`.
-
-The more important interaction is indirect:
-
-- project profile remembers deploy environments
-- planner-generated waves carry `## Deploy environments`
-- deploy-kind skill attachment uses the wave's default deploy environment kind
-
-So planner structure and skill resolution already reinforce each other.
-
-## Recommended Workflow
-
-1. Run `pnpm exec wave project setup` once for the repo.
-2. Use either `pnpm exec wave draft --wave <n> --template <template>` or `pnpm exec wave draft --agentic --task "..." --from-wave <n>`.
-3. Review the generated JSON spec, markdown wave, or agentic run packet.
-4. Adjust repo-specific prompts, file ownership, deliverables, proof artifacts, skills, and validation commands.
-5. If you used agentic draft, materialize only the accepted waves with `pnpm exec wave draft --apply-run <run-id>`.
-6. Run `pnpm exec wave launch --lane <lane> --start-wave <n> --end-wave <n> --dry-run --no-dashboard`.
-7. Only launch live once the dry-run artifacts look correct.
-
-If you want concrete authored examples after the planner baseline, see [docs/reference/sample-waves.md](../reference/sample-waves.md).
-
-## Best Practices
-
-- Treat the generated draft as a strong starting point, not untouchable output.
-- Tighten validation commands before launch.
-- Keep file ownership narrow and explicit.
-- Treat `### Deliverables` and `### Proof artifacts` as part of the plan contract, not optional polish.
-- Keep `docs/context7/planner-agent/` in sync with the selected planning cache slice before publishing the planner bundle to Context7.
-- Add explicit `### Skills` only when the lane, role, runtime, and deploy-kind defaults are not enough.
-- Use `design` when you need a reusable handoff packet; keep straightforward implementation slices on `implementation`.
-- Use the component matrix as a planning contract, not just a reporting surface.
-- Prefer updating the project profile when the same answers recur across waves.
-- Use [docs/reference/sample-waves.md](../reference/sample-waves.md) when you want examples of denser human-authored waves that combine multiple modern surfaces such as `cont-EVAL`, delegated benchmark families, or proof-first live validation.

package/docs/guides/recommendations-0.8.9.md

@@ -1,133 +0,0 @@
----
-title: "0.8.9 Recommendations"
-summary: "How to use 0.8.9's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
----
-
-# 0.8.9 Recommendations
-
-Use this guide when you are adopting `0.8.9` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
-
-## Recommended Default
-
-For most repos, the safest `0.8.9` default is:
-
-- bound work with `budget.minutes`
-- leave generic `budget.turns` as advisory metadata
-- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
-- use `resolve-policy` when the answer already exists in repo policy or shipped docs
-- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
-
-That recommendation matches the runtime:
-
-- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
-- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
-- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
-
-## 1. Budgets
-
-Treat the two budget knobs differently:
-
-- `budget.minutes` is the primary attempt budget
-- generic `budget.turns` is only a planning hint
-- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
-
-Recommended pattern for synthesis-heavy implementation or closure work:
-
-```json
-{
-  "executors": {
-    "profiles": {
-      "implementation-default": {
-        "id": "claude",
-        "model": "claude-sonnet-4-6",
-        "budget": {
-          "minutes": 35,
-          "turns": 12
-        }
-      }
-    }
-  }
-}
-```
-
-In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
-
-Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
-
-```json
-{
-  "executors": {
-    "profiles": {
-      "bounded-closure": {
-        "id": "claude",
-        "model": "claude-sonnet-4-6",
-        "budget": {
-          "minutes": 20
-        },
-        "claude": {
-          "maxTurns": 6
-        }
-      }
-    }
-  }
-}
-```
-
-## 2. Softer Coordination States
-
-`0.8.9` keeps “still visible” separate from “still blocking”.
-
-Use these states intentionally:
-
-| State | Use it for | What the runtime does |
-| --- | --- | --- |
-| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
-| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
-| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
-
-Practical command paths:
-
-```bash
-pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
-pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
-pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
-pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
-```
-
-Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
-
-## 3. What Should Stay Hard
-
-Do not relax everything.
-
-Keep these hard or closure-critical unless you are intentionally changing wave policy:
-
-- missing proof or required deliverables
-- failed integration, documentation, or cont-QA closure gates
-- real human-feedback or escalation requirements that block safe continuation
-- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
-
-If the current wave cannot truthfully close without the answer, keep it blocking.
-
-## 4. Recovery Recommendation
-
-My recommendation after reviewing the current `0.8.9` code path is:
-
-- let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
-- inspect the queued rerun or resume request before manually relaunching the whole wave
-- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
-
-That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
-
-## 5. Suggested Operator Policy
-
-For most repo-owned runbooks:
-
-- teach authors to use `budget.minutes` first
-- teach operators to downgrade only non-proof follow-up
-- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
-- escalate to a full-wave rerun only after targeted recovery proves insufficient
-
-If you want a single sentence policy:
-
-> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.

package/docs/guides/signal-wrappers.md

@@ -1,165 +0,0 @@
-# Signal Wrappers And Long-Running Wake Loops
-
-Use this guide when you want shell-friendly monitoring, external automation hooks, or intentionally long-running agents that should wake only when the orchestrator publishes a new signal version.
-
-If you want the broader tmux or VS Code operator flow, read [terminal-surfaces.md](./terminal-surfaces.md). This page stays focused on the signal snapshots, wrapper scripts, and ack-loop contract.
-
-## What The Runtime Writes
-
-Wave now publishes versioned signal snapshots under:
-
-- `.tmp/<lane>-wave-launcher/signals/wave-<n>.json`
-  Wave-level signal for the whole wave.
-- `.tmp/<lane>-wave-launcher/signals/wave-<n>/<agentId>.json`
-  Per-agent signal state.
-- `.tmp/<lane>-wave-launcher/signals/wave-<n>/acks/<agentId>.json`
-  Per-agent acknowledgement file written by a long-running watcher after it observes a new signal version.
-
-The resident orchestrator uses the same pattern with `resident-orchestrator` as the agent id.
-
-Signal snapshots are derived projections, not canonical decision state. They are machine-friendly wake surfaces built from `wave control status --json`.
-
-## Signal Kinds
-
-The shipped signal vocabulary is:
-
-- `stable`
-- `waiting`
-- `feedback-requested`
-- `feedback-answered`
-- `coordination-action`
-- `resume-ready`
-- `completed`
-- `failed`
-
-`completed` and `failed` are terminal. Long-running watchers should stop waiting once either one appears.
-
-## Wrapper Scripts
-
-Starter repos now include two thin helper scripts:
-
-- `scripts/wave-status.sh`
-- `scripts/wave-watch.sh`
-
-They read `wave control status --json`. They do not recompute status independently.
-
-### `wave-status.sh`
-
-Examples:
-
-```bash
-scripts/wave-status.sh --lane main --wave 3
-scripts/wave-status.sh --lane main --wave 3 --agent A1
-scripts/wave-status.sh --lane main --wave 3 --agent A1 --json
-```
-
-Exit codes:
-
-- `0`
-  Terminal success (`signal=completed`)
-- `10`
-  Still active or waiting (`stable`, `waiting`, `feedback-answered`, `coordination-action`, `resume-ready`)
-- `20`
-  Input required (`signal=feedback-requested`)
-- `40`
-  Terminal failure (`signal=failed`)
-
-The printed machine line includes `signal`, `phase`, `status`, `version`, `blocking`, and `should_wake`.
-
-### `wave-watch.sh`
-
-Examples:
-
-```bash
-scripts/wave-watch.sh --lane main --wave 3 --agent A1 --follow
-scripts/wave-watch.sh --lane main --wave 3 --agent A1 --until-change --refresh-ms 500
-```
-
-Modes:
-
-- `--follow`
-  Keep polling until the signal becomes terminal or input-required.
-- `--until-change`
-  Exit as soon as the watched signal version changes.
-
-Exit codes:
-
-- `0`
-  Terminal success
-- `20`
-  Input required
-- `30`
-  The watched signal version changed, but the wave is still active
-- `40`
-  Terminal failure
-
-Use `--until-change` when an outer supervisor or CI job should re-enter only after a new signal is published.
-
-## Long-Running Agents
-
-For non-resident agents, opt in explicitly with:
-
-```md
-### Skills
-
-- signal-hygiene
-```
-
-That skill is only for intentionally long-running agents. Do not attach it to normal one-shot implementation agents.
-
-When `signal-hygiene` is active, the runtime injects two prompt-visible paths:
-
-- the signal-state JSON path
-- the signal-ack JSON path
-
-The watcher loop is:
-
-1. Read the signal state.
-2. Compare its `version` with the version already recorded in the ack file.
-3. If the version did not change, stay idle.
-4. If the version increased, write the ack file immediately.
-5. Re-read the inbox, shared summary, message board, and any referenced artifacts.
-6. Act once for that version.
-7. Stop entirely when the signal becomes `completed` or `failed`.
-
-Ack payload shape:
-
-```json
-{
-  "agentId": "A1",
-  "version": 4,
-  "signal": "coordination-action",
-  "observedAt": "2026-03-25T19:00:00.000Z"
-}
-```
-
-## Resident Orchestrator Behavior
-
-The resident orchestrator does not need the `signal-hygiene` skill. It always receives the same signal-state and ack-path contract when `--resident-orchestrator` is enabled.
-
-That lets the launcher know whether the resident monitor actually observed a reroute, feedback answer, or terminal state change.
-
-## External Automation Pattern
-
-Typical shell loop:
-
-```bash
-while true; do
-  scripts/wave-watch.sh --lane main --wave 3 --agent A1 --until-change --refresh-ms 500
-  code=$?
-  if [ "$code" -eq 0 ]; then
-    echo "wave completed"
-    break
-  fi
-  if [ "$code" -eq 20 ]; then
-    echo "human input required"
-    break
-  fi
-  if [ "$code" -eq 40 ]; then
-    echo "wave failed"
-    break
-  fi
-done
-```
-
-Use `wave control status --json` directly when you need the full structured payload. Use the wrapper scripts when you want stable exit codes and a single machine-readable line.

package/docs/guides/terminal-surfaces.md

@@ -1,96 +0,0 @@
-# Terminal Surfaces And Dashboards
-
-If you want the end-to-end drafting and live-run workflow, start with [author-and-run-waves.md](./author-and-run-waves.md). This page stays focused on terminal-surface details.
-
-Wave has separate concepts for execution substrate and operator surface.
-
-The important detail is:
-
-- live runs use `tmux` sessions
-- terminal surfaces control how operators attach to those sessions
-
-## The Three Terminal Surfaces
-
-- `vscode`
-  The launcher writes temporary entries to `.vscode/terminals.json` so VS Code can attach to the tmux sessions.
-- `tmux`
-  The launcher uses tmux only and never touches `.vscode/terminals.json`.
-- `none`
-  Dry-run only. No live terminal surface is allowed in this mode.
-
-## What `vscode` Really Means
-
-`vscode` is not a second process host. It is a convenience attachment surface.
-
-The actual live sessions still run in tmux. The VS Code terminal registry just exposes stable attach commands for those tmux sessions.
-
-Use `vscode` when:
-
-- your main operator flow is inside VS Code
-- you want one-click attach behavior for agent sessions and dashboards
-- touching `.vscode/terminals.json` is acceptable in the repo
-
-## What `tmux` Really Means
-
-`tmux` is the cleanest fully terminal-native operator surface.
-
-Use `tmux` when:
-
-- you are on a remote shell or devbox
-- you want zero VS Code coupling
-- you want a headless or low-friction terminal operator workflow
-- the repo should never be mutated with temporary VS Code terminal entries
-
-## Dashboard Behavior
-
-By default the launcher can start per-wave dashboard sessions in tmux.
-
-Wave now maintains stable tmux attach targets for both the current-wave dashboard and the global dashboard on the lane socket.
-
-Use:
-
-```bash
-pnpm exec wave dashboard --lane main --attach current
-pnpm exec wave dashboard --lane main --attach global
-```
-
-Those commands work for both `tmux` and `vscode` terminal surfaces because the live sessions still run on the lane tmux socket.
-
-When `--terminal-surface vscode` is active, Wave also maintains a stable current-wave dashboard terminal entry instead of creating a new wave-numbered dashboard attach target for every wave transition.
-
-Important flags:
-
-- `--no-dashboard`
-  Disable the per-wave tmux dashboard session.
-- `--cleanup-sessions`
-  Kill lane tmux sessions after each wave. This is the default.
-- `--keep-sessions`
-  Preserve tmux sessions after the wave for inspection.
-- `--keep-terminals`
-  Keep temporary VS Code terminal entries instead of cleaning them up.
-
-## Best Practices
-
-- Use `vscode` for local interactive operator work when the temporary terminal registry is useful.
-- Use `tmux` for remote, CI-like, or editor-independent operation.
-- Use `none` only with `--dry-run`.
-- Prefer `wave dashboard --attach current|global` over manual `tmux -L <socket> attach ...` lookups.
-- Pair `--keep-sessions` with incident review or deep debugging, not as a default steady-state mode.
-- Pair `--no-dashboard` with scripted dry-runs or when the board and summaries are sufficient.
-
-## Suggested Defaults
-
-- Local development:
-  `vscode`
-- Remote shell or devbox:
-  `tmux`
-- CI validation:
-  `none` with `--dry-run`
-
-## Example Commands
-
-```bash
-pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --terminal-surface vscode
-pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --terminal-surface tmux --keep-sessions
-pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --dry-run --no-dashboard --terminal-surface none
-```