# 47 — Milestone 4 Guided Composer evidence

## Outcome

Milestone 4 passed on 2026-07-27 at commit `80b95bc`. Authoritative
validation used the isolated checkout
`/mnt/user/appdata/devrunbook-validation/m3` on Unraid 7.2, Docker 27.5.1,
Compose 2.40.3, Node.js 24.18.0, Python 3.11.2 and PostgreSQL 17.9. The
Windows workstation's Node.js 23.7.0 results are supporting feedback only.

The application remains useful without Gitea and still has no arbitrary code
execution path. Repository text and commands are inert, bounded, redacted
evidence used only while composing instructions.

## Delivered behavior

- A framework-independent governed resolver normalizes typed inputs, evaluates
  the closed three-valued condition DSL, resolves compatibility, scope,
  policies and command roles, and fails closed when facts are unavailable.
- `composeCanonicalPrompt` remains the byte-frozen reference-v1 formatter. The
  production resolver matches all 28 supplied prompt fixtures byte for byte.
- Server-authoritative preview loads an exact published playbook version and an
  exact immutable repository-profile revision. The client cannot supply prompt
  bytes, snapshots, digests, lint results or provenance.
- Prompt assembly emits mission, repository context, reconnaissance, scope,
  constraints, autonomy, workflow, validation, recovery, completion and final
  reporting blocks with block-level source and condition-fact provenance.
- Sensitive inputs are rejected or redacted, imported text is fenced and
  bounded, unsafe commands remain inert, and protected/excluded paths are
  resolved before rendering.
- Prompt lint separates blocking findings and warnings, links findings to
  composer controls, and prevents generation until required inputs and the
  persisted preview digest are current.
- Workspace-scoped composer drafts use strict JSON, positive monotonic
  revisions, strong `"draft:<revision>"` ETags, atomic compare-and-swap
  updates, semantic no-op suppression and explicit conflict recovery.
- Generated tasks use mandatory workspace idempotency keys, persisted digest
  validation, immutable database triggers and one append-only creation audit
  event in the same transaction.
- Guided UI generation sends `X-DevRunbook-Draft-Id`; the server reloads that
  authorized persisted draft and records `source_draft_id`, rather than
  trusting client-derived composition state.
- Generated task history is authorized, cursor-paginated and stable. Detail
  reads validate every persisted snapshot and render digest before returning
  exact stored prompt bytes.
- The responsive seven-step UI supports profile-free or exact-revision
  repository context, dynamic inputs, scope and protected paths, Observe
  through Repair autonomy, validation, live preview, provenance and immutable
  read-only task detail. Viewer, offline, expired-session, conflict and stale
  profile states are explicit.

## Defect found by live validation

The first production browser run correctly froze all snapshots and digest but
exposed that the generic `POST /runs` path left `source_draft_id` null. Direct
API composition remains supported, but guided composition now supplies an
optional, validated `X-DevRunbook-Draft-Id`. When present, generation reloads
the workspace-authorized draft through `generateCompositionFromDraft` and
ignores client-derived composition state. A second production run proved the
exact draft relation, new digest and single audit event.

## Authoritative validation

| Command or check | Result |
| --- | --- |
| Integrated Node 24.18.0 `pnpm verify` with isolated Python environment | PASS: formatting, 14-workspace lint/typecheck/tests/build, pack validation and reference composition. |
| `python scripts/validate_pack.py` | PASS: 28 P0 packages, 6 examples, 72 catalog entries, 9 schemas, 28 golden prompts and 68 release-evidence fields. |
| `python scripts/reference_compose.py --check` | PASS: 28 byte-identical prompts. |
| Composer tests | PASS: 37 resolver, normalization, condition, policy, redaction, lint, provenance and golden-parity tests. |
| Application tests | PASS: 16 files and 96 tests, including draft generation, replay conflicts, source integrity, authorization and run history. |
| Web tests | PASS: 24 files and 132 tests, including strict draft/preview/run HTTP contracts and UI contract tests. |
| Database unit and live integration | PASS: generated-run integrity/history plus six draft/source and three history tests against PostgreSQL 17. |
| `pnpm test:security` | PASS: 2 files and 11 tests. |
| Production Compose build and migration | PASS: migration `0003` applied; migrate exited zero; web, worker and PostgreSQL healthy. |
| Existing-data preservation | PASS: 9 repositories remained; profile history advanced only by the deliberate browser evidence revision from 13 to 14. |
| Browser critical flow | PASS: library exact-version handoff, draft creation, missing-input block, autosave, deterministic preview, provenance, immutable generation, reload and post-restart read. |
| Historical profile behavior | PASS: draft remained explicitly pinned to revision 2 after current revision 3 was saved; both generated tasks retained revision 2 and its original digest. |
| Responsive matrix | PASS: 390, 768, 1024, 1440 and 2560 pixel widths had no horizontal overflow; mobile navigation switched off at desktop breakpoints. |
| Accessibility interaction | PASS: semantic steps/fieldsets/tabs, disabled generation, theme switch and `Ctrl+K` command palette worked; reduced-motion behavior remains covered by the browser regression contract. |
| Browser console | PASS: zero warning or error entries. |
| Container restart | PASS: readiness recovered and the generated task plus exact draft relation remained persisted. |
| Runtime boundary scan | PASS: web/worker run as `node`, read-only, non-privileged, all capabilities dropped, `no-new-privileges`; zero sensitive log-pattern matches. |

Production evidence identifiers are deliberately non-secret:

- draft `86a44885-41d7-4d86-8664-cb56fc2473c6`;
- linked run `a87ae11c-54b7-41c6-ba70-3a2d2a9aac0e`;
- render digest
  `ea10cbd4920c94bb6af66189e1f35b880b8fe1eafdbe7a02097ee44efd0c4883`;
- frozen profile revision 2 digest
  `6f5f4c8533bad7e5a882b4174f1d212e5a58155a2f29e387cb8adbc16b771f85`.

## Requirement status

Completed with unit, PostgreSQL and production browser evidence:

- `FR-COM-001` through `FR-COM-010`;
- `FR-DET-007`.

Improved but not overstated:

- `FR-OUT-005` and `FR-OUT-006` have working immutable snapshot and historical
  read foundations, but remain assigned to Milestone 5 until export,
  re-import and artifact history are complete.

## Operational notes

No credential, cookie, token, session secret, encryption key or database
password is recorded here. Browser credentials and the Compose environment
remain outside the checkout with restricted permissions. No project-wide
`release-evidence.json` or `FINAL_HANDOFF.md` is created at this intermediate
gate; those remain final-release artifacts.