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.

6.9 KiB Raw Blame History