devflow-engine 1.0.0__tar.gz

devflow_engine-1.0.0/.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.0.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtualenvs
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# DevFlow runtime
+.devflow/
+
+# OS
+.DS_Store

devflow_engine-1.0.0/.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.0.0/.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.0.0/.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.0.0/.pi/npm/.gitignore

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

devflow_engine-1.0.0/.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.0.0/.pi-lens/cache/session-start-guidance.json

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

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

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

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

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

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

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

devflow_engine-1.0.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: devflow-engine
+Version: 1.0.0
+Summary: DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)
+Project-URL: Homepage, https://github.com/Nuosis/devflow_engine
+Project-URL: Repository, https://github.com/Nuosis/devflow_engine
+Project-URL: Issues, https://github.com/Nuosis/devflow_engine/issues
+Author: DevFlow
+License: Proprietary
+Keywords: agentic,automation,cli,devflow,testing,workflow
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=45.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# DevFlow Engine
+
+CLI-first Python engine for DevFlow. The PyPI distribution is
+`devflow-engine`; it installs the `devflow` command.
+
+## Goals
+- Project lifecycle: draft shell -> bind workspace/repo -> init/register/list/remove
+- Story lifecycle: index/validate/register/execute
+- Planning support: repo analysis -> source docs -> scopes -> approved scope -> idea(s) -> DevFlow stories
+- Implementation workflow: "green" gate = tests + typecheck + lint
+- Review workflow: story-driven compliance/soundness/security review packets persisted in SQLite
+- Error workflow: error queue + remediation runs
+- Execution store: `.devflow/execution.sqlite`
+
+## Documentation
+- `docs/story-implementation-planning-node.md` — per-story planning/gating node before TestDesign/Red, with dependency findings, queue decisions, and registry expectations consumed by downstream implementation nodes.
+- `docs/llm-input-primitives-v0.02.md` — v0.02 LLM-facing input primitive contract for `idea` and `story`.
+
+## Install
+
+Install the CLI from PyPI:
+
+```bash
+pipx install devflow-engine
+# or
+python -m pip install devflow-engine
+```
+
+Run the CLI:
+
+```bash
+devflow --help
+```
+
+## Development
+
+This repo is intended to be developed with **uv**.
+
+```bash
+cd devflow_engine
+uv venv
+uv pip install -e '.[dev]'
+```
+
+Print the v0.02 LLM input guidance:
+```bash
+devflow llm guide
+devflow llm guide --primitive idea --json
+```
+
+## Happy path
+1. project shell created in control plane
+2. workspace/repo bound to project
+3. registration DAG runs via `devflow project add`
+4. project reaches `ready_for_source_scope`
+5. source docs -> scopes
+6. approved scope -> idea(s)
+7. idea -> DevFlow stories
+8. story -> implementation
+9. implementation -> review
+
+## Quickstart
+Register an existing repo with DevFlow:
+```bash
+devflow project add --path /absolute/path/to/repo --name my-repo --json
+```
+
+Submit an idea or a ready story:
+```bash
+devflow idea submit --project /absolute/path/to/repo --from idea.json --json
+# or
+devflow story submit --project /absolute/path/to/repo --from story.json --json
+```
+
+Run delivery and inspect health:
+```bash
+devflow run start --project /absolute/path/to/repo --json
+devflow run health --project /absolute/path/to/repo --json
+```
+
+Triage and repair failures:
+```bash
+devflow doctor --project /absolute/path/to/repo --json
+devflow recovery run --project /absolute/path/to/repo --json
+devflow error solve --project /absolute/path/to/repo --json
+```
+
+When you have a deterministic project-code repro, pass it to error solving:
+```bash
+devflow error solve \
+  --project /absolute/path/to/repo \
+  --repro-command 'uv run pytest' \
+  --json
+```
+
+Inspect per-node outputs from a stored run:
+```bash
+# dump a specific run by run_id
+python scripts/dump_run_node_outputs.py \
+  --run-id <run_uuid>
+
+# or dump the latest run for any DAG by dag_id
+python scripts/dump_run_node_outputs.py \
+  --dag-id implementation_dag
+
+# second-most-recent run for that DAG
+python scripts/dump_run_node_outputs.py \
+  --dag-id implementation_dag \
+  --latest-index 2
+```
+
+Dumps are written under `.devflow/node_output_dumps/<dag>/<label>/<timestamp>/` by default.
+The navigation path intentionally stays human-readable and omits run IDs / object IDs where possible:
+- `<dag>` comes from `runs.dag_id` unless it looks like an ID, in which case the folder falls back to `dag`
+- `<label>` is derived from readable config fields such as `label`, `name`, `title`, `idea_title`, `scope_title`, or `story_title`
+- the exact `run_id` still lands in `manifest.json` inside the dump directory
+
+Use `--output-root /tmp/devflow-dumps` to write somewhere else.
+
+Run the source -> scope scaffold end-to-end:
+```bash
+devflow source-scope run \
+  --project-id proj_demo \
+  --intake-id source_demo \
+  --text "Customers approve quotes online. Approved quotes create jobs. Completed jobs create invoices and customers can pay online."
+```
+
+Gate a pre-shaped normalized packet + scope outline deterministically:
+```bash
+devflow source-scope gate \
+  --project-id proj_demo \
+  --source-packet .devflow/path/to/normalized_source_packet.json \
+  --scope-outline .devflow/path/to/scope_outline.json
+```
+
+## Story contracts
+Story contracts are YAML documents containing:
+- `id`, `title`
+- `planes`: required plane write-ups (`product`, `ux`, `technical`, `security`, `compliance`, `operations`)
+- `plane_oracles`: list of `{plane, anchor}` entries used as verification anchors
+
+The contract validator enforces presence of required planes + non-empty plane_oracles.
+
+## Execution store
+All runs/events/errors/review packets are stored in:
+- `.devflow/execution.sqlite`
+
+This database is created automatically on first CLI usage.
+
+## Workers / Background services
+
+### Supabase execution-event listener (`devflow worker supabase-events`)
+
+This is the DFE-side listener/dispatcher for the `devflow_execution_events` Supabase table.
+It is the single long-running process that bridges the control-plane (Supabase) to the local
+DevFlow engine — picking up queued events and dispatching the appropriate DFE workflow for each.
+
+**Normal operation (continuous loop with Realtime):**
+```bash
+devflow worker supabase-events
+```
+
+Starts an indefinite polling loop. While running it also opens a Supabase Realtime WebSocket
+subscription on `devflow_execution_events`. New `INSERT` events on that table wake the dispatch
+loop immediately rather than waiting for the next poll interval (default: 3 s). If the WebSocket
+connection drops it reconnects automatically in the background; polling continues as the fallback
+during any gap.
+
+**Process a single queued event and exit:**
+```bash
+devflow worker supabase-events --once
+```
+
+Useful for manual trigger / smoke testing.
+
+**Disable Realtime (polling only):**
+```bash
+devflow worker supabase-events --no-realtime
+```
+
+Runs the same polling loop but skips the WebSocket listener entirely. Use this when the
+`websockets` Python package is unavailable, or when you need to debug without a live connection.
+
+**Additional options:**
+| Flag | Default | Description |
+|---|---|---|
+| `--sleep-seconds N` | `3.0` | Idle sleep between polls (also caps realtime wake latency) |
+| `--max-iterations N` | unlimited | Stop after N loop iterations |
+| `--json` | off | Emit JSON summary on exit |
+
+**When queued events are not being picked up — checklist:**
+1. Verify the worker is running: there should be a live `devflow worker supabase-events` process.
+2. Check Supabase credentials: `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` (or equivalent config)
+   must be set and valid.
+3. Confirm the event row in `devflow_execution_events` has `status = queued` and `run_id IS NULL`
+   — events with any other status are skipped.
+4. Check that the event's `event_type` is in the supported set (see
+   `docs/queue-worker-infra.md` → *Supported event types*).
+5. Run with `--once` to get an immediate result and check stderr/stdout for errors.
+6. If Realtime is misbehaving (false wake-ups or missed wakes), try `--no-realtime` to isolate
+   the issue to the polling path.
+
+See `docs/queue-worker-infra.md` for full architecture details.
+
+## Design notes
+- `docs/scope-idea-agentification.md` — current scope->idea agentic runtime notes
+- `docs/ui-grounding-curtis-medium-tier-doctrine.md` — follow-on UI grounding / wireframe planning doctrine from the Curtis pass, including the proposed `ui_screen_inventory.json` contract and the default medium-tier minimum for customer-facing wireframes