devflow-engine 1.1.17__tar.gz → 1.1.18__tar.gz

devflow_engine-1.1.18/DESIGN_NOTES.md

@@ -0,0 +1,145 @@
+# DevFlow Error-Solver Hardening — Design Notes
+
+Track A landed in `v1.1.18`:
+- `errors/repo_quality_judge.py` — pure-LLM judge (medium tier → MiniMax) scoring
+  repro artifacts on `behavioral_vs_presence` and `fails_for_described_reason`.
+- `BuildObservabilityNode` runs the judge after the observation pass and before
+  `FirstPassFix`. Unhealthy judgments flip `error_tasks.quality_status` to
+  `awaiting_quality_review` and stop the workflow with `status='observed'`.
+- `ResolveNode` enforces the red-before-fix invariant: `verified =
+  green_gate AND observation_was_red`. Closes the "already-green-at-intake" leak
+  (`src/devflow_engine/errors/error_solver_dag.py` ResolveNode).
+- Schema: added `error_tasks.quality_status TEXT` via
+  `ExecutionStore._ensure_error_tasks_schema` (in-code migration, no Alembic).
+
+The rest of this document is the queue for the NEXT vertical slices. Each
+slice is intentionally small enough to land in one PR.
+
+---
+
+## Slice 1 — Playwright observe-time spec generation + visual-artifact capture
+
+**Why:** The repo-quality judge catches presence-only repros at intake, but it
+doesn't yet generate the behavioral repro itself. For UI bugs the observability
+worker should emit a Playwright spec (not just a pytest grep script) plus a
+screenshot/video so the portal can render visual evidence to the submitter and
+the fix worker.
+
+**Where to start:**
+- Sources of truth on Playwright discipline live at:
+  - `/Volumes/devflow/.openclaw/workspace/docs/how_to_playwright_right.md`
+  - `/Volumes/devflow/.openclaw/workspace/docs/PLAYWRITE-E2E-PROCESS.md`
+- Add a sibling to `src/devflow_engine/errors/user_report_observability.py`:
+  `user_report_observability_playwright.py`. Reuse the same agentic pi+tools
+  scaffold but emit `repro.spec.ts` + `artifacts/{screenshot.png,trace.zip}`.
+- BuildObservabilityNode already scopes the sandbox to
+  `.devflow/observability/{etid}/`; mirror that path layout for the new artifact set.
+- Wire selection (pytest vs. Playwright) through `report_context.surface` — when
+  the user-report intake came from a frontend route, prefer Playwright.
+- The repo-quality judge keys off the same payload shape (`repro_artifact.path` +
+  `repro_artifact.source`) — pass the `.spec.ts` source through unchanged.
+
+**Acceptance:**
+- A user-report against a route renders a `.spec.ts` + screenshot + trace.
+- RepoQualityJudge sees `behavioral` for a spec that exercises the page and
+  asserts on visible DOM/text, `presence` for a spec that only asserts a
+  selector exists in the rendered HTML.
+
+---
+
+## Slice 2 — Bug-portal routes `/bugs/{token}` on devflow-host
+
+**Why:** Submitters need to see (and respond to) the analyst's observation +
+repro + quality-judgment without an account. Mirrors the clarify magic-link
+pattern that's already in production for clarification questions.
+
+**Where to start:**
+- Mirror the controller pattern at
+  `controller/api/clarify.py` (in the devflow-host repo, not engine).
+- Token mechanism: reuse `clarification_links.create_link()` —
+  same TTL/rotation semantics already approved.
+- Engine side: add a `create_bug_portal_link(error_task_id)` helper next to
+  the existing clarification-link helper. New rows in the existing
+  `clarification_links` table with a discriminator column, OR a new
+  `bug_portal_links` table — prefer the former to keep the token rotation
+  audit in one place.
+- Portal routes (devflow-host):
+  - `GET /bugs/{token}` — render observation summary, repro source, judgment.
+  - `POST /bugs/{token}/request-changes` — see Slice 3.
+  - `POST /bugs/{token}/approve` — see Slice 4.
+
+**Acceptance:**
+- A user-report row with `quality_status='awaiting_quality_review'` exposes a
+  portal URL in `error_tasks` (new column `portal_url` or derived).
+- Submitter sees the repro and the judge's rationale; can act on it.
+
+---
+
+## Slice 3 — Modification-request → linked-new error_task
+
+**Why:** When a submitter clicks "request changes" on the portal, that's new
+information the analyst doesn't have yet. Spawn a new `error_tasks` row linked
+back to the original so the analyst pool re-claims it cleanly without losing
+the original audit trail.
+
+**Where to start:**
+- New schema column: `error_tasks.parent_error_task_id TEXT` (NULL for roots).
+  Add to `ExecutionStore._ensure_error_tasks_schema` required list. Index on it
+  for `WHERE parent_error_task_id = ?` lookups.
+- Engine helper: `ExecutionStore.create_modification_request(parent_etid,
+  message)` — inserts a child row with `source_kind='user_report'`,
+  `status='open'`, copies `project_id` + `reporter_*` + `source_app` from
+  parent, message = submitter's modification request, fingerprint derived
+  from `parent_etid + nonce` to bypass dedupe.
+- Portal handler `POST /bugs/{token}/request-changes` calls that helper.
+- Worker claim filter (`stores/execution_store.py` ~ line 2461 / 2478) does
+  NOT need changes — child rows are plain `open` user_report rows.
+
+**Acceptance:**
+- Submitter modification creates a sibling row visible to the analyst with a
+  link back to the original via `parent_error_task_id`.
+- Original row's `quality_status` remains; child gets its own DAG run.
+
+---
+
+## Slice 4 — Submitter-approval → staging push integration
+
+**Why:** After RepoQualityJudge + green-gate + observation_was_red all pass,
+the resolution commit lives in the worker's local repo but doesn't reach
+staging until a human approves. The portal `approve` button should be the
+trigger.
+
+**Where to start:**
+- The commit is already created by `_commit_resolution` in
+  `errors/error_solver_dag.py` (lines 179–224). The SHA is persisted to
+  `task_context.metadata["commit_result"]`. Extend ResolveNode to also write
+  the SHA into `error_tasks.resolution_commit_sha TEXT` (new column).
+- Portal handler `POST /bugs/{token}/approve`:
+  1. Look up `resolution_commit_sha` on the row.
+  2. `git push origin HEAD:refs/heads/staging-<etid>` from the worker's repo
+     clone (engine-side helper: `push_resolution_to_staging(etid)`).
+  3. Optionally open a PR via `gh pr create` against the project's main.
+- New `error_tasks.staging_status TEXT` column to track
+  `unpushed | pushed | pr_open | merged | rejected`.
+
+**Acceptance:**
+- Approval pushes exactly the resolution commit (single-commit branch) to
+  staging.
+- Rejection leaves the commit local and flips
+  `quality_status='awaiting_quality_review'` so a fresh analyst pass can
+  iterate.
+
+---
+
+## Anchors quick-reference
+
+- Engine DAG entrypoint: `src/devflow_engine/errors/error_solver_dag.py`
+  - `BuildObservabilityNode.process` — observation + RepoQualityJudge
+  - `ResolveNode.process` — red-before-fix invariant + commit
+  - `_commit_resolution` — atomic per-error commit (existing)
+- Schema migrations: `src/devflow_engine/stores/execution_store.py`
+  `_ensure_error_tasks_schema` (~ line 611)
+- Runner: `ExecutionStore.run_error_solver_dag` (~ line 1953); add new
+  `repo_quality_judge_fn` kwarg already present.
+- Judge: `src/devflow_engine/errors/repo_quality_judge.py`
+- Tests: `tests/area8_errors/test_us85_error_solver_repo_quality.py`

{devflow_engine-1.1.17 → devflow_engine-1.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devflow-engine
-Version: 1.1.17
+Version: 1.1.18
 Summary: DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)
 Author: DevFlow
 License: Proprietary

{devflow_engine-1.1.17 → devflow_engine-1.1.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devflow-engine"
-version = "1.1.17"
+version = "1.1.18"
 description = "DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)"
 readme = "README.md"
 requires-python = ">=3.11"