Skip to content

richfrem/agent-plugins-skills / plugins/agent-exploration-cycle/.apm/skills/running-exploration-cycle

running-exploration-cycle

Verified

Runs the business exploration cycle end to end: starts or resumes a session (intake interview, session brief), enforces the Discovery Plan HARD-GATE, routes the four phases (Discovery Plan, Visual Blueprinting, Prototype, Handoff) to the sibling skills and keeps session state. Use when the user says "let's explore this idea", "I have an idea I want to explore", "help me plan this out", "start discovery", "resume my exploration", "where did we leave off", or starts any conversation about a need, problem or idea before building. Not for hardening an existing prototype (use reengineering-vibe-code) or for engineering build work.

FileKindSize
SKILL.mdskill md4.6 KB
assets/exploration-dashboard.mdmarkdown1.8 KB
evals/evals.jsonconfig6.0 KB
references/acceptance-criteria.mdmarkdown2.2 KB
references/architecture.mdmarkdown6.3 KB
references/design-rationale.mdmarkdown6.3 KB
references/discovery-planning-agent.mdmarkdown4.7 KB
references/discovery-planning-tracks.mdmarkdown5.9 KB
references/discovery-planning.mdmarkdown2.4 KB
references/dispatch-strategies.mdmarkdown5.7 KB
references/domain-patterns-exploration-session.mdmarkdown3.3 KB
references/domain-patterns.mdmarkdown1.7 KB
references/environment-check.mdmarkdown1.7 KB
references/exploration-cycle-orchestrator-agent.mdmarkdown16.7 KB
references/exploration-optimizer.mdmarkdown8.9 KB
references/exploration-orchestrator-guide.mdmarkdown3.7 KB
references/exploration-session-brief.mdmarkdown2.1 KB
references/exploration-workflow.mdmarkdown2.4 KB
references/hard-gate-enforcement.mdmarkdown3.3 KB
references/high-level-process.mmdother885 B
references/intake-agent.mdmarkdown12.0 KB
references/orchestrator-loop.mmdother1.3 KB
references/post-run-survey.mdmarkdown1.7 KB
references/problem-framing-agent.mdmarkdown2.7 KB
references/process-definition.mdmarkdown3.7 KB
references/process-overview.mmdother3.7 KB
references/session-setup.mmdother1.3 KB
references/state-and-gates.mmdother1.0 KB
references/using-exploration-cycle.mdmarkdown2.3 KB
requirements-dev.inother69 B
requirements.inother60 B
scripts/check_gaps.pyscript2.5 KB
scripts/dispatch.pyexecutablescript23.6 KB
scripts/exploration_session.pyexecutablescript15.9 KB
scripts/sandbox_runner.pyscript8.7 KB
scripts/smoke_test.pyscript5.1 KB
scripts/state_engine.pyscript21.9 KB
scripts/test_dispatch_authorization_gate.pyscript4.0 KB
scripts/test_dispatch_security.pyscript10.0 KB
scripts/test_exploration_integration.pyscript14.7 KB
scripts/test_integration.pyscript4.4 KB
scripts/test_path_traversal.pyscript1.8 KB
scripts/test_phase_premium_counter.pyscript2.0 KB
scripts/test_sandbox_runner.pyscript5.6 KB
scripts/test_session_start_hook.pyscript2.4 KB
scripts/test_state_engine.pyscript13.5 KB
scripts/test_validate_phase_gate.pyscript12.7 KB
scripts/validate_phase_gate.pyexecutablescript8.7 KB

scripts/test_state_engine.py

View on GitHub
"""
Purpose:
    Unit tests for state_engine.py: schema/constraint enforcement (WAL mode,
    table creation, status/FK/TTL CHECK constraints), concurrency (busy-retry
    transactions, parallel-agent budget gates), task lifecycle (lease, commit,
    CAS guard, expired-lease reclaim), review/artifact hash verification,
    dashboard round-trip and migration, and CLI subcommand invocation
    (dual-runtime execution: both library import and CLI tool).

Key Input Dependencies:
    - state_engine.py module (in ../scripts/)
    - pytest tmp_path fixture, mem_conn fixture (file-backed SQLite, WAL mode)
"""
import sys, sqlite3, uuid, time, threading
from pathlib import Path
import pytest

sys.path.insert(0, str(Path(__file__).parent))
import state_engine as SE


@pytest.fixture
def mem_conn(tmp_path):
    """File-backed SQLite — WAL mode requires a real filesystem, not :memory:."""
    db_path = tmp_path / "test.sqlite"
    conn = SE.init_db(str(db_path))
    yield conn
    conn.close()


def test_wal_mode_enabled(tmp_path):
    """Verify init_db enables WAL journal mode."""
    db_path = tmp_path / "wal.sqlite"
    conn = SE.init_db(str(db_path))
    result = conn.execute("PRAGMA journal_mode;").fetchone()
    assert result[0].lower() == "wal"
    conn.close()


def test_all_tables_created(mem_conn):
    """Verify init_db creates all expected schema tables."""
    expected = {"sessions", "tasks", "approvals", "artifacts", "reviews",
                "dispatches", "policy_decisions", "phase_metrics", "nonces"}
    rows = mem_conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()
    actual = {r[0] for r in rows}
    assert expected == actual, f"Missing tables: {expected - actual}"


def test_session_status_constraint(mem_conn):
    """Verify sessions.status rejects values outside the allowed CHECK constraint set."""
    with pytest.raises(sqlite3.IntegrityError):
        mem_conn.execute(
            "INSERT INTO sessions (id, session_name, status) VALUES (?, ?, ?)",
            (str(uuid.uuid4()), "test", "invalid_status")
        )
        mem_conn.commit()


def test_task_fk_references_session(mem_conn):
    """tasks.session_id must reference a real session (FK enforced at connection level)."""
    with pytest.raises(sqlite3.IntegrityError):
        mem_conn.execute(
            "INSERT INTO tasks (id, session_id, phase_ordinal, phase_name, component_name) "
            "VALUES (?,?,?,?,?)",
            (str(uuid.uuid4()), "nonexistent-session", 1, "phase1", "comp1")
        )
        mem_conn.commit()


def test_approval_ttl_capped_at_one_hour(mem_conn):
    """approvals.expires_at must not exceed created_at + 1 hour (CHECK constraint)."""
    SE.create_session(mem_conn, "s1", "TTL Test Session")
    with pytest.raises(sqlite3.IntegrityError):
        mem_conn.execute("""
            INSERT INTO approvals (id, session_id, phase, approved_actions, allowed_paths,
                spec_hash, spec_source_path, expires_at)
            VALUES (?, 's1', 'p1', '[]', '[]', 'abc', '/spec.md', datetime('now', '+2 hours'))
        """, (str(uuid.uuid4()),))
        mem_conn.commit()


def test_immediate_transaction_retries_on_busy(tmp_path):
    """Verify _immediate_transaction retries when the database is locked by another connection."""
    db_path = tmp_path / "retry.sqlite"
    conn1 = SE.init_db(str(db_path))
    conn2 = SE.init_db(str(db_path))
    conn2.execute("PRAGMA busy_timeout=0")

    conn1.execute("BEGIN EXCLUSIVE")
    retry_count = []

    def write_with_conn2():
        """Attempt an immediate transaction on conn2 while conn1 holds an exclusive lock."""
        try:
            with SE._immediate_transaction(conn2) as c:
                retry_count.append(1)
        except Exception:
            retry_count.append(0)

    t = threading.Thread(target=write_with_conn2)
    t.start()
    time.sleep(0.2)
    conn1.execute("ROLLBACK")
    t.join(timeout=5)
    conn1.close()
    conn2.close()
    assert len(retry_count) >= 1


def test_state_engine_cli_init(tmp_path):
    """state_engine.py must be callable as a CLI tool (dual-runtime: library and CLI)."""
    import subprocess
    db_path = str(tmp_path / "cli.sqlite")
    result = subprocess.run(
        [sys.executable, str(Path(SE.__file__)), "init", "--db-path", db_path],
        capture_output=True, text=True, timeout=10,
    )
    assert result.returncode == 0, f"CLI init failed: {result.stderr}"
    assert Path(db_path).exists(), "DB file must exist after CLI init"


def test_create_session_and_add_task(mem_conn):
    """Verify create_session and add_task insert rows with expected default status."""
    SE.create_session(mem_conn, "sess-1", "Test Session")
    SE.add_task(mem_conn, "task-1", "sess-1", 1, "Phase 1", "Comp A")
    row = mem_conn.execute("SELECT * FROM tasks WHERE id='task-1'").fetchone()
    assert row is not None
    assert row["status"] == "pending"


def test_lease_task_increments_parallel_counter(mem_conn):
    """Successful lease must increment sessions.parallel_agents_running."""
    SE.create_session(mem_conn, "sess-2", "Session 2")
    SE.add_task(mem_conn, "task-2", "sess-2", 1, "Phase 1", "Comp B")
    before = mem_conn.execute(
        "SELECT parallel_agents_running FROM sessions WHERE id='sess-2'"
    ).fetchone()["parallel_agents_running"]

    SE.lease_task(mem_conn, "task-2", "subagent-abc", ttl_seconds=300)

    after = mem_conn.execute(
        "SELECT parallel_agents_running FROM sessions WHERE id='sess-2'"
    ).fetchone()["parallel_agents_running"]
    assert after == before + 1


def test_commit_task_complete_decrements_parallel_counter(mem_conn):
    """Completion must decrement sessions.parallel_agents_running."""
    SE.create_session(mem_conn, "sess-3", "Session 3")
    SE.add_task(mem_conn, "task-3", "sess-3", 1, "Phase 1", "Comp C")
    SE.lease_task(mem_conn, "task-3", "subagent-x", ttl_seconds=300)
    row = mem_conn.execute("SELECT version FROM tasks WHERE id='task-3'").fetchone()

    SE.commit_task_complete(mem_conn, "task-3", "subagent-x", row["version"], "hash1")

    after = mem_conn.execute(
        "SELECT parallel_agents_running FROM sessions WHERE id='sess-3'"
    ).fetchone()["parallel_agents_running"]
    assert after == 0


def test_commit_task_complete_cas_guard(mem_conn):
    """Verify commit_task_complete's compare-and-swap guard rejects wrong agent/version."""
    SE.create_session(mem_conn, "sess-4", "Session 4")
    SE.add_task(mem_conn, "task-4", "sess-4", 1, "Phase 1", "Comp D")
    SE.lease_task(mem_conn, "task-4", "subagent-x", ttl_seconds=300)
    row = mem_conn.execute("SELECT version FROM tasks WHERE id='task-4'").fetchone()
    version = row["version"]

    assert SE.commit_task_complete(mem_conn, "task-4", "wrong-agent", version, "h") is False
    assert SE.commit_task_complete(mem_conn, "task-4", "subagent-x", version + 99, "h") is False
    assert SE.commit_task_complete(mem_conn, "task-4", "subagent-x", version, "h") is True


def test_budget_gate_blocks_over_parallel_limit(mem_conn):
    """Verify lease_task raises when parallel_agents_running is at MAX_PARALLEL_AGENTS."""
    SE.create_session(mem_conn, "sess-5", "Session 5")
    mem_conn.execute(
        "UPDATE sessions SET parallel_agents_running=? WHERE id='sess-5'",
        (SE.MAX_PARALLEL_AGENTS,)
    )
    mem_conn.commit()
    SE.add_task(mem_conn, "task-5", "sess-5", 1, "Phase 1", "Comp E")
    with pytest.raises(RuntimeError, match="parallel_agents_running"):
        SE.lease_task(mem_conn, "task-5", "subagent-over-limit", ttl_seconds=300)


def test_record_premium_call_increments_counter(mem_conn):
    """Verify record_premium_call increments sessions.premium_calls_used."""
    SE.create_session(mem_conn, "sess-6", "Session 6")
    SE.record_premium_call(mem_conn, "sess-6")
    used = mem_conn.execute(
        "SELECT premium_calls_used FROM sessions WHERE id='sess-6'"
    ).fetchone()["premium_calls_used"]
    assert used == 1


def test_verify_review_current_detects_mismatch(mem_conn):
    """verify_review_current must return False when artifact hash doesn't match review hash."""
    SE.create_session(mem_conn, "sess-7", "Session 7")
    SE.add_task(mem_conn, "task-7", "sess-7", 1, "Phase 1", "Comp F")
    artifact_id = str(uuid.uuid4())
    mem_conn.execute(
        "INSERT INTO artifacts (id, task_id, path, original_sha256, sanitized_sha256, "
        "sanitization_report, artifact_type, created_by, sanitizer_version) "
        "VALUES (?,?,?,?,?,?,?,?,?)",
        (artifact_id, "task-7", "/tmp/file.py", "aaa", "bbb", "{}", "code", "agent-1", "1.0")
    )
    review_id = str(uuid.uuid4())
    mem_conn.execute(
        "INSERT INTO reviews (id, artifact_id, reviewer, review_type, verdict, artifact_sha256) "
        "VALUES (?,?,?,?,?,?)",
        (review_id, artifact_id, "reviewer-1", "code_quality", "pass", "DIFFERENT_HASH")
    )
    mem_conn.commit()
    assert SE.verify_review_current(mem_conn, artifact_id) is False


def test_reclaim_expired_leases_returns_tasks_to_pending(mem_conn):
    """Verify reclaim_expired_leases resets tasks with an expired lease back to pending."""
    SE.create_session(mem_conn, "sess-8", "Session 8")
    SE.add_task(mem_conn, "task-8", "sess-8", 1, "Phase 1", "Comp G")
    SE.lease_task(mem_conn, "task-8", "subagent-crash", ttl_seconds=300)
    # Manually expire the lease
    mem_conn.execute(
        "UPDATE tasks SET lease_expires_at=datetime('now', '-1 second') WHERE id='task-8'"
    )
    mem_conn.commit()
    count = SE.reclaim_expired_leases(mem_conn)
    assert count >= 1
    row = mem_conn.execute("SELECT status FROM tasks WHERE id='task-8'").fetchone()
    assert row["status"] == "pending"


def test_state_engine_cli_lease_task(tmp_path):
    """CLI lease-task command must work end-to-end (dual-runtime: library and CLI)."""
    import subprocess
    import json
    db_path = str(tmp_path / "cli.sqlite")
    conn = SE.init_db(db_path)
    SE.create_session(conn, "cli-sess", "CLI Test")
    SE.add_task(conn, "cli-task", "cli-sess", 1, "Phase 1", "Comp A")
    conn.close()
    result = subprocess.run(
        [sys.executable, str(Path(SE.__file__)), "lease-task",
         "--db-path", db_path, "--task-id", "cli-task", "--subagent-id", "gemini-1"],
        capture_output=True, text=True, timeout=10,
    )
    assert result.returncode == 0, f"CLI lease-task failed: {result.stderr}"
    assert json.loads(result.stdout)["ok"] is True


def test_project_dashboard_round_trips(mem_conn):
    """Verify project_dashboard renders session name and component names into markdown."""
    SE.create_session(mem_conn, "sess-d1", "My Session")
    SE.add_task(mem_conn, "task-d1a", "sess-d1", 1, "Phase 1", "Component Alpha")
    SE.add_task(mem_conn, "task-d1b", "sess-d1", 1, "Phase 1", "Component Beta")
    md = SE.project_dashboard(mem_conn, "sess-d1")
    assert "My Session" in md
    assert "Component Alpha" in md
    assert "Component Beta" in md


def test_validate_dashboard_detects_drift(mem_conn):
    """Verify validate_dashboard_checkboxes detects mismatch between DB status and markdown."""
    SE.create_session(mem_conn, "sess-d2", "Drift Session")
    SE.add_task(mem_conn, "task-d2", "sess-d2", 1, "Phase 1", "Comp X")
    fake_md = "- [x] Comp X\n"  # DB says pending, md says complete
    assert SE.validate_dashboard_checkboxes(fake_md, mem_conn, "sess-d2") is False


def test_migrate_dashboard_parses_tasks(mem_conn, tmp_path):
    """Verify migrate_dashboard parses checkbox tasks and skips [~] lines."""
    dashboard = tmp_path / "exploration-dashboard.md"
    dashboard.write_text(
        "# Exploration Session: Test Migration\n"
        "## Phase 1: Discovery\n"
        "- [ ] Task Alpha\n"
        "- [x] Task Beta\n"
        "- [~] Task Gamma\n"  # skipped — must be ignored
    )
    SE.migrate_dashboard(dashboard, mem_conn)
    tasks = mem_conn.execute(
        "SELECT component_name, status FROM tasks ORDER BY phase_ordinal"
    ).fetchall()
    names = {t["component_name"] for t in tasks}
    assert "Task Alpha" in names
    assert "Task Beta" in names
    assert "Task Gamma" not in names  # [~] skipped lines not migrated
    beta = next(t for t in tasks if t["component_name"] == "Task Beta")
    assert beta["status"] == "complete"
    assert (tmp_path / "exploration-dashboard.md.migrated").exists()


# --- C7 regression tests (consolidation): the documented `state_engine.py status` command must exist ---
def test_state_engine_cli_status_without_db(tmp_path):
    """`status` with no database reports that no session is active and exits 0 (skills call it as a probe)."""
    import subprocess
    result = subprocess.run(
        [sys.executable, str(Path(SE.__file__)), "status", "--db-path", str(tmp_path / "missing.sqlite")],
        capture_output=True, text=True, timeout=10,
    )
    assert result.returncode == 0, result.stderr
    assert "No active exploration session" in result.stdout


def test_state_engine_cli_status_reports_session_and_tasks(tmp_path):
    """`status` prints JSON with the latest session and task counts by status."""
    import subprocess, json
    db_path = str(tmp_path / "s.sqlite")
    conn = SE.init_db(db_path)
    SE.create_session(conn, "sess-1", "Status Session")
    SE.add_task(conn, "t1", "sess-1", 1, "Discovery", "Plan")
    SE.add_task(conn, "t2", "sess-1", 1, "Discovery", "Interview")
    conn.close()
    result = subprocess.run(
        [sys.executable, str(Path(SE.__file__)), "status", "--db-path", db_path],
        capture_output=True, text=True, timeout=10,
    )
    assert result.returncode == 0, result.stderr
    data = json.loads(result.stdout)
    assert data["session_name"] == "Status Session"
    assert data["status"] == "in_progress"
    assert data["tasks"] == {"pending": 2}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall