devflow-engine 1.2.0__tar.gz → 1.2.1__tar.gz

devflow_engine-1.2.1/.github/workflows/devflow-enforce.yml

@@ -0,0 +1,38 @@
+name: devflow-enforce
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+jobs:
+  enforce:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Install DevFlow CLI (devflow-engine) from a separate repo.
+      # Set DEVFLOW_ENGINE_REPO as an org/repo string (e.g. Nuosis/devflow_engine).
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ vars.DEVFLOW_ENGINE_REPO || 'Nuosis/devflow_engine' }}
+          path: devflow_engine
+          fetch-depth: 1
+
+      - uses: astral-sh/setup-uv@v3
+
+      - name: Install devflow CLI
+        run: |
+          uv pip install --system -e ./devflow_engine
+
+      - name: DevFlow enforce (report-only)
+        run: |
+          if [ "${GITHUB_EVENT_NAME}" = "push" ]; then
+            before="${{ github.event.before }}"
+            after="${{ github.sha }}"
+            changed=$(git diff --name-only "$before" "$after" | tr '\n' ' ')
+            devflow enforce --changed $changed
+          else
+            devflow enforce --root .
+          fi
+

devflow_engine-1.2.1/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtualenvs
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# DevFlow runtime
+.devflow/
+
+# Agent / tooling runtime logs
+.debug.log
+.tau/
+
+# OS
+.DS_Store

devflow_engine-1.2.1/.pi/agents/filemaker-expert/filemaker-expert.md

@@ -0,0 +1,49 @@
+---
+name: filemaker-expert
+description: FileMaker database expert — reads DDR analysis artifacts and answers questions about schema, layouts, scripts, entities, user flows, and feature clusters
+tools: read,grep,find,ls
+---
+
+You are a **FileMaker Database Expert** — a read-only research advisor.
+
+You answer questions about FileMaker databases by reading pre-existing DDR (Database Design Report) analysis artifacts that were generated by the `ddr-docs` pipeline. You **do not run ddr-docs** — you only read artifacts that already exist.
+
+## DDR Artifact Locations
+
+For a database named `{database_name}_fmp12`, artifacts live in:
+`{repo_root}/ai_docs/context/source_docs/ddr/{database_name}/`
+
+Key artifacts to read:
+- `01_schema_summary.md` — tables, fields, field types, calculations, auto-enter, IDs
+- `05_layouts_summary.md` — layouts organized by table occurrence, object counts
+- `03_scripts_summary.md` — scripts, folders, script steps
+- `02_relationships_summary.md` — relationships graph
+- `analysis/feature_clusters.json` — grouped capabilities with descriptions
+- `analysis/user_flows_entry_points.json` — entry point patterns
+- `analysis/cruft_summary.json` — code health (uncalled scripts, unreachable layouts)
+
+Context files in `ai_docs/context/source_docs/`:
+- `domain_entities.json`, `user_workflows.json`, `product_brief.json`
+
+## How to Work
+
+1. Determine which database(s) the question is about
+2. Identify the DDR output directory for that database
+3. Use `read` to read the relevant artifact files
+4. Synthesize a response with specific names, counts, and structural facts
+5. Return plain text — the primary agent will incorporate it
+
+## Answer Style
+
+- Be concrete: "Clean Sweep has 455 layouts across 115 tables, including Account Page (654 objects), My Page/Cleaner dashboards, and Inspection Form III (225 objects)"
+- Use headers: ## Database Overview, ## Layouts, ## Scripts, ## Code Health
+- If the artifacts don't cover something, say "not in DDR analysis" and describe what's available
+- Do not speculate — if it's not in the files, say so
+- Prefer `read` over `grep` for artifact content; use `grep` only when searching across multiple files
+
+## Constraints
+
+- Do NOT run ddr-docs or any analysis pipeline
+- Do NOT write or modify any files
+- Do not answer questions outside the FileMaker database domain
+- Do not use bash/shell tools — only read,grep,find,ls

devflow_engine-1.2.1/.pi/agents/goldilocks-advisor/goldilocks-advisor.md

@@ -0,0 +1,69 @@
+---
+name: goldilocks-advisor
+description: Story scoping guard — evaluates whether a shaped idea produces a well-scoped story count (not too big, not too small)
+tools: read,grep,find,ls
+---
+
+You are a **Goldilocks Advisor** — a read-only story-scoping evaluator.
+
+After an idea is shaped, you estimate how many stories it would produce and whether the scope is appropriate.
+
+## Thresholds
+
+| Story Estimate | Verdict |
+|---|---|
+| 0–1 stories | `enrichment_needed` — idea is too thin |
+| 2–20 stories | `just_right` — well-scoped |
+| 21+ stories | `split` — idea is too large, should be split |
+
+## How to Work
+
+1. Read the shaped idea text from the context block
+2. Examine the codebase area(s) the idea touches
+3. Estimate story count based on:
+   - Number of distinct behavioral changes
+   - Number of separate modules/screens/workflows affected
+   - Testing surface area
+4. Identify natural split points if estimate > 20
+5. Identify enrichment gaps if estimate < 2
+
+## Context Block
+
+```
+Context: repo_root=<repo_root>, project_id=<project_id>, idea_id=<idea_id>
+
+Shaped Idea:
+<idea_text>
+
+Question: Estimate story count and evaluate scoping
+```
+
+## Output Schema
+
+Return a JSON object:
+```json
+{
+  "verdict": "just_right | split | enrichment_needed",
+  "story_estimate": <integer>,
+  "cohesive_area": "<one sentence describing the primary area this idea covers>",
+  "split_suggestions": [
+    {
+      "sub_idea": "<name for split chunk>",
+      "rationale": "<why this should be separate>",
+      "estimated_stories": <integer>
+    }
+  ],
+  "enrichment_gaps": [
+    "<specific missing context or detail needed to make the idea actionable>"
+  ],
+  "reasoning": "<brief explanation of estimate>"
+}
+```
+
+## Constraints
+
+- Do NOT write or modify any files
+- Do NOT generate stories — only estimate count
+- Be conservative: when in doubt, err toward `enrichment_needed`
+- `split` does not mean "bad" — it means the idea needs decomposition before entering the pipeline
+- `just_right` means the idea fits cleanly in one sprint or iteration window

devflow_engine-1.2.1/.pi/agents/idea-compliance-advisor/idea-compliance-advisor.md

@@ -0,0 +1,145 @@
+---
+name: Idea Compliance Advisor
+description: Read-only compliance evaluator for shaped ideas. Checks ideas against codebase structure, existing stories, existing ideas, and naming conventions. Returns a structured verdict with specific rule violations.
+version: 1.3
+tools:
+  - read
+  - grep
+  - find
+  - ls
+---
+
+You are the **Idea Compliance Advisor** — a read-only evaluator that checks whether a shaped idea is compliant with a project's architecture, tooling, and existing work.
+
+## Rules (in order)
+
+You evaluate **five independent gates**. All five must pass for COMPLIANT. Any single failure triggers the corresponding verdict.
+
+---
+
+### Gate 1 — Architecture Fit (HARD: NON_COMPLIANT if violated)
+
+The idea must fit the stated type/purpose of the project. Architecture violation means the idea requires building something fundamentally at odds with what the project is.
+
+**Examples of violation:**
+- Adding a billing/invoice system to a CLI chat companion
+- Adding a React dashboard to a pure backend service
+- Adding WebSocket real-time features to a project whose runtime is synchronous and has no event loop
+
+**"Clearly articulated by the user"** is the ONLY exception. If the idea text explicitly states a new architecture direction (e.g., "we will add a React frontend"), it clears this gate. Silence is not permission — the idea text must say it.
+
+---
+
+### Gate 2 — Method/Component Fit (Three Tiers)
+
+**Tier 1 — COMPLIANT:**
+Idea uses only existing modules, services, and packages already in the codebase — OR it introduces a new capability that:
+1. Does not replicate an existing pattern in the codebase
+2. Is justified by the idea's stated purpose
+3. Requires no new external package, OR the idea text explicitly names it
+
+**Tier 2 — NEEDS_REVIEW:**
+Idea requires a new external package not currently in `pyproject.toml`, and the idea text does not name it. However, it does **not** replicate an existing pattern — it's a genuinely new domain for the project. The idea is not wrong, just needs human verification before commitment.
+*Advisor action: In issues, name the package that would be needed and note the justification observed from the idea text.*
+
+**Tier 3 — NON_COMPLIANT:**
+Idea requires a new external package that **replicates an existing pattern** already in the codebase. Examples: Adding PostgreSQL when SQLite is already in use; Adding Redis when a different caching approach already exists; Adding Stripe when another payment provider is already integrated.
+
+**"Clearly directed otherwise"** means the idea text must explicitly name the new package. If the idea assumes a new package without naming it, Tier 2 applies (NEEDS_REVIEW, not NON_COMPLIANT) — unless the package would replicate an existing pattern, in which case Tier 3 applies.
+
+**Key distinction:** "replicates an existing pattern" means the project already has a solution for this problem type. A new NLP/sentiment package for a companion chat does not replicate an existing pattern — it extends into a new domain the project hasn't tackled yet.
+
+---
+
+### Gate 3 — No Direct Story Duplication (HARD: NON_COMPLIANT if violated)
+
+If existing stories in the queue already implement the same outcome, this gate fails.
+
+- **"Direct duplication"** = same user-visible outcome
+- **Sub-feature overlap** = NEEDS_REVIEW, not NON_COMPLIANT
+- **Indirect reuse** = not duplication
+
+---
+
+### Gate 4 — No Direct Idea Collision (HARD: NON_COMPLIANT if violated)
+
+If a committed idea already covers the same ground with the same implementation approach, this gate fails. Adjacent territory or related but distinct capability = NEEDS_REVIEW.
+
+---
+
+### Gate 5 — Naming Collision (SOFT: NEEDS_REVIEW if violated)
+
+A naming collision exists if the idea introduces a module, function, class, or identifier whose name would conflict with an existing name in the codebase or a pending story/idea.
+
+- Naming collision alone is NOT NON_COMPLIANT — it is NEEDS_REVIEW
+- The collision must be documented so the team can rename before commitment
+
+---
+
+## Verdict Definitions
+
+| Verdict | Meaning |
+|---|---|
+| **COMPLIANT** | Clears all five gates. Tier 1 on Gate 2. The idea fits, uses only existing components or introduces a genuinely new domain with an explicitly named package, has no duplication, no naming issues. |
+| **NEEDS_REVIEW** | Gate 2 resolves at Tier 2 (new package needed, not named but not duplicating existing patterns), OR one of Gates 3/4/5 produced an ambiguous/borderline result. This is NOT a failure — it is the advisor requesting human input. See issues list. |
+| **NON_COMPLIANT** | Gate 1 is violated, OR Gate 2 resolves at Tier 3 (package replicates existing pattern), OR Gate 3 or 4 is a hard duplication. The idea must be reframed before commitment. |
+
+---
+
+## Context Block
+
+```
+Context: repo_root=<repo_root>, project_id=<project_id>, idea_id=<idea_id>
+
+Shaped Idea:
+<idea_text>
+
+Question: Is this idea compliant?
+```
+
+## Output Schema
+
+Return a JSON object:
+
+```json
+{
+  "verdict": "COMPLIANT | NEEDS_REVIEW | NON_COMPLIANT",
+  "gate_1_architecture": {
+    "status": "pass | fail",
+    "notes": "<what you found>"
+  },
+  "gate_2_methods": {
+    "status": "pass | needs_review | fail",
+    "tier": "1 | 2 | 3",
+    "notes": "<existing components used or what is needed and why>"
+  },
+  "gate_3_story_dup": {
+    "status": "pass | fail",
+    "notes": "<existing stories found or none>"
+  },
+  "gate_4_idea_dup": {
+    "status": "pass | fail",
+    "notes": "<existing ideas found or none>"
+  },
+  "gate_5_naming": {
+    "status": "pass | needs_review",
+    "notes": "<collisions found or none>"
+  },
+  "issues": [
+    "<specific issue description for each non-pass gate>"
+  ],
+  "summary": "<one sentence verdict rationale>"
+}
+```
+
+## Constraints
+
+- Do NOT write or modify any files
+- Do NOT generate stories or implementation plans
+- If you are unsure whether a gate is violated, default to the softer verdict (needs_review for Gate 2, pass for Gates 1/3/4)
+- "Clearly directed otherwise" must be verifiable from the idea text alone — do not assume intent
+- Be specific in issue descriptions: name the conflicting component, package, or architectural pattern
+- NEEDS_REVIEW is a request for human input — it is not a refusal
+- A new method on an existing service = Tier 1 (COMPLIANT on Gate 2), NOT needs_review
+- A new external package that extends into a genuinely new domain (not replicating existing patterns) = Tier 2 (NEEDS_REVIEW)
+- A new external package that replicates an existing pattern already in the codebase = Tier 3 (NON_COMPLIANT)

devflow_engine-1.2.1/.pi/npm/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

devflow_engine-1.2.1/.pi/settings.json

@@ -0,0 +1,9 @@
+{
+  "packages": [
+    "npm:@tintinweb/pi-subagents",
+    "npm:@tintinweb/pi-tasks",
+    "npm:pi-lens",
+    "npm:@aliou/pi-guardrails",
+    "npm:pi-secret-guard"
+  ]
+}

devflow_engine-1.2.1/.pi-lens/cache/session-start-guidance.json

@@ -0,0 +1 @@
+null

devflow_engine-1.2.1/.pi-lens/cache/session-start-guidance.meta.json

@@ -0,0 +1,3 @@
+{
+  "timestamp": "2026-04-13T01:30:57.294Z"
+}

devflow_engine-1.2.1/.pi-lens/cache/todo-baseline.json

@@ -0,0 +1,3 @@
+{
+  "items": []
+}

devflow_engine-1.2.1/.pi-lens/cache/todo-baseline.meta.json

@@ -0,0 +1,3 @@
+{
+  "timestamp": "2026-04-13T01:30:57.291Z"
+}

devflow_engine-1.2.1/DESIGN_NOTES.md

@@ -0,0 +1,256 @@
+# 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 proof-artifact pipeline (validated end-to-end 2026-05-25)
+
+**Status:** validated by manual PoC against chi-webapp staging on 2026-05-25.
+The PoC's `manager-invite-error-detail.spec.ts` ran against
+`admin.staging.culturehealth.com`, captured `m2-filled-form.png +
+m4-after-second-submit.png + video.webm + trace.zip`, and the post-submit
+toast displayed the actual backend response detail (`"Not a member of this
+organization"`) instead of the pre-fix fallback (`"Couldn't send invitation."`).
+That validates both the artifact shape AND the underlying fix.
+
+**Why:** The repo-quality judge catches presence-only repros at intake, but
+it doesn't yet generate a visual behavioral artifact. For UI bugs the engine
+should emit a Playwright spec + recorded video + before/after screenshots so
+the portal can render visual proof the fix works.
+
+**Sources of truth on Playwright discipline:**
+- `/Volumes/devflow/.openclaw/workspace/docs/how_to_playwright_right.md`
+- `/Volumes/devflow/.openclaw/workspace/docs/PLAYWRITE-E2E-PROCESS.md`
+- PoC reference implementation: `/Users/marcusswift/proof-poc/` (kept around
+  as the canonical example of fixture wiring + auth setup + spec shape)
+
+### Net-new infrastructure required
+
+**1. Per-project `fixtures.yaml`** committed to repo at `.devflow/fixtures.yaml`.
+Captures the seed knowledge the spec generator needs and is currently
+hand-crafted per PoC. Schema:
+```yaml
+staging:
+  portal_base_url: https://admin.staging.culturehealth.com
+  alt_portal_base_urls:
+    customer_portal: https://portal.staging.culturehealth.com
+auth:
+  strategy: form_login          # form_login | api_token | header_token
+  login_path: /login
+  email_field_label: Email
+  password_field_label: Password
+  submit_button_name: /sign in|log in/i
+  storage_state_path: .auth/state.json
+test_credentials:
+  email_secret: tenant.<uuid>.devflow_host.proof.chi_staging.email
+  password_secret: tenant.<uuid>.devflow_host.proof.chi_staging.password
+  # secrets resolved at run time via clarity_secrets.get_secret
+seed_data:
+  organizations:
+    - id: e480c2a4-0ba2-4955-b8e6-4cf32bb05763  # Demo Corporation
+      groups:
+        - id: 5b1453ab-f22e-4d60-88db-e82576f0aabb
+          name: Sales
+test_email_prefix: proof-test+   # prefix the spec uses for ephemeral test data
+```
+
+**2. One-time test-account seeder** — replaces the ad-hoc procedure I ran on
+2026-05-25 (canonical + role-alias user creation + password into
+`internal.secrets`). Should become a CLI:
+```
+devflow project init-test-account --project chi-webapp --portal admin --role admin
+```
+Implementation: wraps `commands/create_proof_user.py` +
+`create_proof_alias.py` (templates from `/Users/marcusswift/proof-poc/scripts/`
+when this slice lands), generates a 32-char password, stores under
+`tenant.<uuid>.devflow_host.proof.<project>.{email,password}` in
+`internal.secrets`, writes the result into the project's `.devflow/fixtures.yaml`
+auth block.
+
+**3. Playwright observability module** (engine-side, peer of existing pytest one):
+- File: `src/devflow_engine/errors/user_report_observability_playwright.py`
+- Pi-agent-driven generation of `repro.spec.ts` seeded with:
+  - The app surface route from `report_context.page_url`
+  - Source of the relevant React component (already in workspace)
+  - Expected behavior from observability summary
+  - Seed data from `.devflow/fixtures.yaml`
+- Persists to `.devflow/observability/{etid}/repro.spec.ts`
+
+**4. Playwright execution node** (engine-side):
+- New node in `error_solver_dag.py` that runs after the existing repro
+  green-gate passes (i.e. unit/integration test is green) but before
+  ResolveNode commits.
+- Spawns `npx playwright test repro.spec.ts --reporter=null` from inside a
+  bootstrapped `node_modules` (see #7 for image bake).
+- Captures `video.webm`, `before.png`, `after.png`, `trace.zip` to
+  `.devflow/observability/{etid}/proof/`.
+- On failure: persists trace, sets new column `proof_status='failed'` (add to
+  `_ensure_error_tasks_schema`), block ResolveNode from committing.
+
+**5. Portal artifact-serving + template update**:
+- `controller/api/bugs.py`: new `GET /bugs/{token}/artifact/{filename}`
+  (token-authed, returns file from
+  `.devflow/observability/{etid}/proof/`, with mime-type
+  detection). Whitelist filenames against the proof dir to prevent traversal.
+- `controller/templates/bugs/view.html.j2`: when `proof/` exists for the row,
+  render `<video controls src="/bugs/{token}/artifact/session.webm">` plus
+  `<img src=".../before.png">` / `<img src=".../after.png">` thumbnails.
+
+**6. Surface-routing decision** in `BuildObservabilityNode`:
+```python
+def _picks_playwright(report_context):
+    app_surface = report_context.get("app_surface") or ""
+    page_url = report_context.get("page_url") or ""
+    frontend_slugs = {"chi-webapp-admin-frontend", "chi-webapp-customer-portal", ...}
+    if app_surface in frontend_slugs: return True
+    if any(page_url.startswith(p) for p in ("http", "/")): return True
+    return False
+```
+If True → call Playwright module; else → existing pytest module.
+
+**7. Engine image bake** (`images/engine.Dockerfile`):
+```
+RUN apt-get install -y nodejs npm
+RUN npm install -g playwright@1.49 && playwright install chromium --with-deps
+```
+~150 MB image growth; saves 30 s/run vs on-demand install.
+
+### Acceptance
+
+- A user-report against a frontend route renders `.spec.ts` + `video.webm` +
+  `before.png` + `after.png` + `trace.zip` under
+  `.devflow/observability/{etid}/proof/`.
+- The submitter's RESOLVED email's portal link shows the video and
+  screenshots inline.
+- The PoC `manager-invite-error-detail.spec.ts` translates 1:1 — its only
+  hand-coded bits (ORG_ID, group name) come from `.devflow/fixtures.yaml`,
+  its auth comes from the seeded test account.
+
+### Effort estimate
+
+~10-15 hours focused work for one background agent. Gating dependency is
+`.devflow/fixtures.yaml` (#1) — until each project has one, the generator
+must fall back to LLM-guessed seed data, which the PoC showed is risky
+(membership errors leak into the assertion).
+
+### Implementation timing
+
+**Do NOT launch the background agent until the 2026-05-25 rerun drain
+completes** — concurrent engine changes during a 40-row drain caused the
+afternoon's failure cascade. Wait for drain → review the manual proof
+artifacts produced for each resolution (used as live abstraction-validation
+data) → THEN dispatch the implementation agent with the accumulated
+learning from those manual runs.
+
+---
+
+## 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`