@beyondwork/docx-react-component 1.0.0

package/docs/reference/coordination-and-closure.md

@@ -0,0 +1,487 @@
+---
+title: "Coordination And Closure"
+summary: "How agent-to-agent work, deliverables, integration, and final closure behave end to end in the Wave runtime."
+---
+
+# Coordination And Closure
+
+This page explains the runtime model behind Wave coordination, helper work, integration, and final closure.
+
+The short version is:
+
+- `exit 0` means an agent process finished
+- it does not mean the wave is ready to close
+- closure is based on durable coordination state plus the staged closure gates
+
+## Core Model
+
+Wave distinguishes three different things:
+
+1. an agent finishing its own owned work
+2. an agent asking another agent or lane for follow-up work
+3. the wave being globally coherent enough to pass integration, documentation, and cont-QA closure
+
+Those are related, but they are not the same.
+
+An implementation agent can be locally complete and still leave the wave blocked if it created open helper work, unresolved clarification chains, or required dependencies.
+
+At runtime, those distinctions map onto separate modules:
+
+- `implementation-engine.mjs` selects implementation work
+- `derived-state-engine.mjs` rebuilds the blackboard projections
+- `gate-engine.mjs` evaluates closure and barrier state from envelopes plus canonical logs
+- `retry-engine.mjs` decides what can safely resume
+- `closure-engine.mjs` sequences the staged closeout
+- `session-supervisor.mjs` only launches sessions and records observed facts
+
+Closure roles are resolved from the wave definition first, then from starter defaults. In other words, integration, documentation, `cont-QA`, `cont-EVAL`, and security review keep the same semantics even when a wave overrides the default role ids such as `A8`, `A9`, `A0`, `E0`, or `A7`.
+
+## Durable State Surfaces
+
+The runtime writes several different artifacts, but they do different jobs:
+
+- canonical coordination log:
+  `.tmp/<lane>-wave-launcher/coordination/wave-<n>.jsonl`
+- canonical control-plane log:
+  `.tmp/<lane>-wave-launcher/control-plane/wave-<n>.jsonl`
+- result envelopes:
+  `.tmp/<lane>-wave-launcher/results/wave-<n>/attempt-<a>/<agent>.json`
+- helper-assignment snapshot:
+  `.tmp/<lane>-wave-launcher/assignments/wave-<n>.json`
+- dependency snapshot:
+  `.tmp/<lane>-wave-launcher/dependencies/wave-<n>.json`
+- shared summary:
+  `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/shared-summary.md`
+- per-agent inboxes:
+  `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/<agent>.md`
+- integration summary:
+  `.tmp/<lane>-wave-launcher/integration/wave-<n>.json`
+- wave dashboard:
+  `.tmp/<lane>-wave-launcher/dashboards/wave-<n>.json`
+- run-state:
+  `.tmp/<lane>-wave-launcher/run-state.json`
+
+The important rule is that decisions come from the canonical authority set: wave definitions, the coordination log, the control-plane log, and immutable result envelopes. The markdown board is a projection for humans. See [wave-orchestrator.md](../plans/wave-orchestrator.md).
+
+That control-plane log also carries observed `wave_run`, `attempt`, and `agent_run` lifecycle facts from `session-supervisor.mjs`. When human feedback or escalation remains open, the reducer materializes the wave as `clarifying` with blocked `waveState` instead of flattening it into generic progress.
+
+Live waves now keep refreshing that derived state while agents are still running. Shared summaries, inboxes, dashboard coordination metrics, and clarification routing are not only recomputed at attempt boundaries; they are also refreshed during active wave execution so stale clarification and acknowledgement timing is machine-visible before the attempt ends.
+
+## What Agents Should Use
+
+Use the coordination log for conversational or workflow state:
+
+- `request`
+  Use this when you need another agent or capability owner to do work. Target it explicitly. This is the kind that becomes a helper assignment.
+- `blocker`
+  Use this when the wave is blocked, but not because the runtime needs to route work to a specific assignee.
+- `handoff`
+  Use this for continuity and context transfer. This is informative by itself; it is not the same as a blocking helper assignment.
+- `evidence`
+  Use this for durable facts, artifacts, or proof that another agent may need.
+- `claim`
+  Use this for assertions that integration should reconcile.
+- `clarification-request`
+  Use this when an ambiguity must be triaged before work can safely continue.
+
+## What Stewards and Orchestrators May Also Use
+
+- `ack`
+  Acknowledge receipt of a request or clarification. Resets the acknowledgement timer.
+- `decision`
+  Record a binding decision that downstream agents should follow.
+- `orchestrator-guidance`
+  Non-binding guidance from the resident orchestrator.
+
+Implementation agents normally do not need these kinds.
+
+Practical rule:
+
+- if you need another agent to take action and you want the wave to stay blocked until it is done, use a targeted `request`
+- a plain board note or plain `handoff` is not enough
+
+## Open Versus Resolved
+
+Wave treats these coordination statuses as open:
+
+- `open`
+- `acknowledged`
+- `in_progress`
+
+It treats these statuses as closed:
+
+- `resolved`
+- `closed`
+- `superseded`
+- `cancelled`
+
+But "open" and "blocking" are now different questions.
+
+Open records can carry a blocker severity:
+
+- `hard`
+- `soft`
+- `stale`
+- `advisory`
+- `proof-critical`
+- `closure-critical`
+
+Practical rule:
+
+- `proof-critical`, `closure-critical`, and hard required barriers still stop the wave outright
+- `soft` blockers stay visible and may still drive repair work or retry targeting
+- `stale` and `advisory` records remain in coordination history without owning the active blocking edge
+
+That means a targeted helper request only blocks while it remains open *and* still has blocking severity in coordination state.
+
+For the practical `0.8.9` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.8.9.md](../guides/recommendations-0.8.9.md).
+
+This page is documenting runtime semantics first. The important contract is that closure follows the durable coordination state, not that a particular human or agent used one exact command path to mutate it.
+
+## Deliverables Versus Helper Work
+
+Deliverables prove an agent landed its own owned outputs.
+
+For implementation agents with an exit contract, closure validates:
+
+- `[wave-proof]`
+- `[wave-doc-delta]`
+- any required `[wave-component]` markers
+- declared `### Deliverables`
+- declared `### Proof artifacts`
+
+Deliverables and proof artifacts are local ownership proof. They do not replace cross-agent follow-up.
+
+That distinction matters:
+
+- if Agent A1 owns `src/foo.ts` and `docs/reviews/foo.md`, those should be modeled as A1 deliverables
+- if A1 needs Agent A8 to reconcile a cross-component interface or integration contradiction, that is not an A1 deliverable
+- that second case is coordination work, and it should become a targeted request
+
+## End-To-End Example: Agent A1 Needs A8
+
+Assume:
+
+- A1 owns implementation files and its review output
+- A8 is the integration steward
+- A1 finishes its code and report, but notices an interface contradiction that only A8 can reconcile
+
+### Step 1: A1 Lands Its Owned Work
+
+A1 can still satisfy its own slice by:
+
+- writing its owned files
+- emitting a valid `[wave-proof]`
+- emitting a valid `[wave-doc-delta]`
+- satisfying any declared deliverables and proof artifacts
+
+At this point A1 can be locally done.
+
+### Step 2: A1 Raises A Durable Request
+
+Example:
+
+```bash
+pnpm exec wave control task create \
+  --lane main \
+  --wave 4 \
+  --agent A1 \
+  --kind request \
+  --summary "Need integration decision for auth/session interface change" \
+  --detail "A1 landed the auth refactor, but session ownership now spans auth, gateway, and docs surfaces. A8 must reconcile the final contract and closure path." \
+  --target agent:A8 \
+  --priority high
+```
+
+What happens next:
+
+- the request lands in the canonical coordination log
+- the runtime derives a helper assignment for `agent:A8`
+- that assignment is written into the assignment snapshot
+- the shared summary and A8 inbox now show the open helper work
+
+`wave control task list` and `wave control task get` surface both blocking and informative coordination kinds. `wave control status` only turns `request`, `blocker`, `clarification-request`, `human-feedback`, and `human-escalation` into candidate blocking task edges, and then only if the current record still has `blocking=true` plus a blocking severity. Plain `handoff`, `evidence`, `claim`, and `decision` records stay visible without falsely blocking the owner. When a launcher attempt is already running, status scopes the top-level blocking edge to that active attempt instead of letting stale relaunch metadata or unrelated closure tasks dominate the wave-level view.
+
+### Step 3: Why A1 Can Be Done But The Wave Is Still Blocked
+
+This is the important distinction:
+
+- A1 may be done with A1's ownership
+- the wave is not done
+
+The reducer and gate engine will still see:
+
+- an open helper assignment for the request
+- an integration summary that is not yet ready for doc closure
+
+So the wave remains blocked.
+
+In runtime terms, this becomes:
+
+- `helper-assignment-open` if the request has an assignee
+- `helper-assignment-unresolved` if no assignee could be found
+
+### Step 4: A8 Resolves The Follow-Up
+
+A8 reads the shared summary and inbox, reconciles the issue, and updates the integration state.
+
+That usually means:
+
+- closing the targeted follow-up in coordination state
+- publishing a final integration position
+- emitting a final `[wave-integration] state=ready-for-doc-closure ...` marker only when no meaningful contradiction or blocker remains
+
+### Step 5: Closure Can Continue
+
+Only after that does the closure engine allow the wave to move on to:
+
+1. documentation closure
+2. cont-QA closure
+
+So the correct mental model is:
+
+- A1 can finish first
+- A8 may still owe wave-level closure work
+- the wave does not pass just because the original implementation owner exited successfully
+
+## End-To-End Example: Clarification Chain
+
+Assume an agent cannot safely choose between two interpretations of a migration rule.
+
+The agent should emit a clarification request:
+
+```bash
+pnpm exec wave coord post \
+  --lane main \
+  --wave 6 \
+  --agent A3 \
+  --kind clarification-request \
+  --summary "Need policy answer for backward-compat migration path" \
+  --detail "I checked the current-state doc and migration plan, but the required compatibility window is still ambiguous."
+```
+
+What happens next:
+
+1. the orchestrator triages the clarification from repo policy, ownership, prior decisions, and routing context
+2. if it can answer inside the wave, it writes the resolution back into coordination state
+3. if another owner can answer it, the runtime opens a targeted follow-up request and keeps the clarification chain blocking
+4. only after policy and routed follow-up paths are exhausted does it create human feedback or escalation artifacts
+5. until that chain is resolved, clarification remains a closure barrier and any routed follow-up also remains blocking helper work
+
+Important implication:
+
+- even if code is landed, an open clarification chain can still block the wave
+- a routed clarification that stays `open` past the acknowledgement policy can be rerouted during the same live attempt instead of waiting for a full retry cycle
+- operators can now inspect and intervene through one command surface, including downgrade or policy-close actions when the remaining issue is no longer proof-critical:
+
+```bash
+pnpm exec wave control status --lane main --wave 10 --agent A7 --json
+pnpm exec wave control task act reassign --lane main --wave 10 --id clarify-a7-rollout --to A1
+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 defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the published rollout guide."
+pnpm exec wave control task act resolve --lane main --wave 10 --id escalation-clarify-a7-rollout --detail "Published command surface covers this question."
+```
+
+That keeps clarification routing, downgrade, dismissal, escalation, policy closure, and human-answer handling inside the canonical coordination state instead of forcing ad hoc file edits.
+
+When the operator answers through the feedback queue directly, the answer path now repairs the same canonical state:
+
+```bash
+pnpm exec wave feedback respond \
+  --id 202603240000-main-w6-A3-abc123 \
+  --response "Use the 90-day compatibility window documented in docs/plans/migration.md." \
+  --operator ops-lead
+```
+
+For ad-hoc runs, include `--run <id>` on that command. The response path will reconcile the linked clarification or escalation chain, re-sync helper-assignment projections, and write a safe one-shot continuation request when the reducer can resume but no active attempt is still running.
+
+## End-To-End Example: Required Dependency
+
+Assume the wave needs another lane to land a required API first.
+
+That should be modeled as a required dependency ticket, not as a local deliverable.
+
+Example:
+
+```bash
+pnpm exec wave dep post \
+  --owner-lane release \
+  --requester-lane main \
+  --owner-wave 2 \
+  --requester-wave 4 \
+  --agent launcher \
+  --summary "Need release lane to publish session token contract before Wave 4 can close" \
+  --target capability:integration \
+  --required
+```
+
+What happens next:
+
+- the dependency appears in the per-wave dependency snapshot
+- integration and inboxes surface it
+- required inbound or outbound dependencies keep the wave blocked
+
+This is separate from helper assignment logic:
+
+- helper assignments are intra-wave follow-up work
+- dependencies are cross-wave or cross-lane prerequisites
+
+## What Integration Actually Does
+
+Integration is not a generic summary pass. It is the place where Wave asks:
+
+- are there still unresolved blockers?
+- do any agent claims contradict each other?
+- are there still proof gaps?
+- are there still deploy or infra risks?
+- are there still documentation gaps?
+- are helper assignments or dependencies still open?
+
+If any of those remain material, the recommendation is `needs-more-work`.
+
+Only when that synthesized state is clean does integration become `ready-for-doc-closure`.
+
+This is why integration sits between raw implementation success and final docs or QA closure.
+
+## Why Closure Is Staged
+
+Closure runs in order:
+
+1. `cont-EVAL`
+2. optional security review
+3. integration
+4. documentation
+5. `cont-QA`
+
+That ordering exists to prevent false PASS outcomes.
+
+Examples:
+
+- `cont-EVAL` should not PASS if the declared eval contract is still unsatisfied
+- security should run before final closure if findings could still change integration or rollout readiness
+- documentation should not close while integration still says the story is unstable
+- cont-QA should be last, because it is supposed to judge the final landed state
+
+## What Each Closure Role Must Prove
+
+### Implementation Owners
+
+Implementation owners must prove their own exit contract, not just exit cleanly.
+
+That means:
+
+- proof state is `met`
+- completion, durability, and proof level meet the contract
+- documentation impact is reported correctly
+- all declared deliverables exist
+- all required proof artifacts exist
+
+### `cont-EVAL`
+
+`cont-EVAL` must emit a final `[wave-eval]` marker and satisfy the declared target and benchmark contract.
+
+For live closure, it is not enough to say "looks good." The target ids and benchmark ids must match the declared wave contract.
+
+### Security Review
+
+If present, security review must emit a final `[wave-security]` marker and publish its report artifact.
+
+- `blocked` stops the wave before integration
+- `concerns` remains visible in summaries and traces
+- `clear` is only valid when no unresolved findings or approvals remain
+
+### Integration
+
+Integration must reconcile cross-agent state and report `ready-for-doc-closure` only when there is no remaining meaningful contradiction, blocker, proof gap, or deploy risk.
+
+### Documentation Steward
+
+Documentation closure must emit `[wave-doc-closure]`.
+
+The important distinction is:
+
+- `closed` means the shared-plan delta was reconciled
+- `no-change` means no shared-plan changes were required
+- `delta` means documentation closure is still open
+
+### `cont-QA`
+
+`cont-QA` must emit:
+
+- a final verdict
+- a final `[wave-gate]` marker
+
+Final PASS requires all gate dimensions to pass in the final state.
+
+## Why The Closure Model Works
+
+The closure model is deliberately conservative.
+
+It works because it refuses to trust weak signals:
+
+- a process exiting successfully
+- a board note saying "done"
+- one agent claiming success while another still reports contradiction
+- stale prior attempt output
+
+Instead, it trusts machine-visible current state:
+
+- current coordination log state
+- current assignment and dependency snapshots
+- current integration summary
+- current docs closure state
+- current cont-QA and cont-EVAL markers
+- current proof artifacts and deliverables
+
+That gives Wave two useful properties:
+
+- already-valid work can stay reusable
+- the wave still refuses to PASS while open follow-up work remains
+
+## Targeted Retry Behavior
+
+When closure fails, the runtime does not always relaunch the entire wave.
+
+It tries to relaunch only the implicated owners:
+
+- agents named by the failure
+- sibling owners that still owe shared promoted-component proof after a landed owner already passed its slice
+- helper assignees
+- dependency owners where relevant
+- the closure stewards needed after that state changes
+
+That is why the system can safely reuse already-valid implementation slices while still forcing the wave to stay blocked until the right follow-up work is done.
+
+Operators now have a first-class override path for that recovery flow:
+
+```bash
+pnpm exec wave control rerun get --lane main --wave 10 --json
+pnpm exec wave control rerun request --lane main --wave 10 --agent A2 --agent A7 --clear-reuse A2 --reason "Resume sibling-owned component closure"
+```
+
+The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the retry engine on the next retry decision, and then cleared by default after one application. This is the supported path for:
+
+- rerunning only specific owners
+- preserving explicit reuse selectors such as attempt ids, proof bundle ids, derived-summary reuse, and invalidated component ids through the compatibility projection
+- clearing reuse for selected agents without wiping the whole wave state
+- resuming at the real remaining implementation owners instead of restarting or stopping at the wrong sibling
+
+## Common Mistakes
+
+- Treating `exit 0` as wave completion.
+- Using a board note or `handoff` when the work should be a blocking targeted `request`.
+- Modeling cross-agent follow-up as a deliverable instead of coordination work.
+- Declaring integration ready while helper assignments or dependencies are still open.
+- Treating documentation closure as optional after plan-affecting outcomes.
+- Treating `cont-QA` as an implementation reviewer instead of the final closure gate.
+
+## Practical Rule Of Thumb
+
+Ask two questions:
+
+1. "Did this agent finish its own owned outputs?"
+2. "Is the wave globally coherent enough that no other blocking owner still owes follow-up work?"
+
+Wave only closes when both are true.

package/docs/reference/deep-research-report (15).md

@@ -0,0 +1,25 @@
+# Encrypted Office Document Research Normalization
+
+This file now records a deferred architecture option, not an active component wave.
+
+Encrypted input is currently solved upstream of `WordReviewEditor`, so the active editor contract expects normal OPC `.docx` bytes or a canonical snapshot.
+
+The deferred packet lives at [encrypted-intake-contracts.md](/home/coder/docx-react-component/docs/plans/waves/deferred/encrypted-intake-contracts.md).
+
+## Decisions That Still Stand
+
+- password-to-open Office files are a pre-import container-access problem, not an in-editor OOXML feature
+- detection must happen before normal OOXML parse
+- decrypt must complete before canonical import begins
+- passwords, derived keys, and decrypted raw bytes must never enter canonical state, snapshots, logs, or surfaced diagnostics
+- editor-owned export must never silently imply re-encryption
+
+## Current Repo Decision
+
+- no active component wave or component maturity track includes encrypted intake
+- no active Railway or QA wave claims encrypted-input support
+- the companion corpus under [test/fixtures/encrypted-docx/README.md](/home/coder/docx-react-component/test/fixtures/encrypted-docx/README.md) is retained only as deferred reference material
+
+## Reactivation Rule
+
+If encrypted intake moves back inside the component boundary, restart from the deferred packet and reintroduce it as a new later wave after the active v1 closure work. Do not silently widen the current public API or active certification surface.

package/docs/reference/docx/README.md

@@ -0,0 +1,10 @@
+# Docx Reference
+
+This directory is reserved for docx-specific reference docs as the broader hierarchy fills out.
+
+The current shipped docx contracts still live in the legacy reference root:
+
+- `docs/reference/public-api.md`
+- `docs/reference/ooxml-compliance.md`
+- `docs/reference/word-review-editor-frontend-architecture.md`
+- `docs/reference/word-review-editor-ux-guide.md`