feat: implement progressive reading with steps_read tracking (#28)

Author: tracer-mohist

src/workflow_as_list/cli/exec.py

@@ -1,4 +1,11 @@
-"""workflow exec command - Execution instance management."""
+"""workflow exec command - Execution instance management for progressive reading.
+
+Design:
+- read: Read current step content (mark as read)
+- next: Advance to next step (must read first)
+
+Progressive reading ensures Agent cannot skip steps without reading.
+"""
 
 from pathlib import Path
 
@@ -17,17 +24,22 @@ def print_output(type: OutputType, message: str):
     console.print(f"[{type.value}] {message}")
 
 
-app = typer.Typer(help="Execution instance management")
+app = typer.Typer(help="Execution instance management (progressive reading)")
 
 
-@app.command("show")
-def exec_show(
+@app.command("read")
+def exec_read(
     execution_id: str = typer.Argument(..., help="Execution instance ID"),
 ):
-    """Show execution instance details.
+    """Read current step content and mark as read.
+
+    Agent reads the current step, understands it, then executes operations
+    using its own tools (git, file operations, API calls, etc.).
+
+    After reading and executing, call 'workflow exec next' to advance.
 
     Example:
-        workflow exec show commit-abc123
+        workflow exec read commit-abc123
     """
     ensure_directories()
     executor = Executor()
@@ -40,28 +52,54 @@ def exec_show(
         )
         raise typer.Exit(4)
 
-    console.print(f"Execution: {execution.execution_id}")
-    console.print(f"  Workflow: {execution.workflow_name}")
-    console.print(f"  Status: {execution.status.value}")
-    console.print(f"  Step: {execution.current_step}/{execution.steps_total}")
-    console.print(f"  Outputs: {execution.outputs_path}")
+    # Load workflow and parse
+    workflow = executor.get_workflow(execution.workflow_name)
+    if not workflow:
+        print_output(OutputType.ERROR, f"Workflow not found: {execution.workflow_name}")
+        raise typer.Exit(4)
+
+    content = Path(workflow.file_path).read_text()
+    parser = WorkflowParser(content)
+    parser.parse()
+
+    # Get current step
+    current_step = executor.get_next_step(execution, parser)
+    if current_step is None:
+        print_output(OutputType.SUCCESS, f"Execution completed: {execution_id}")
+        console.print(f"  All {execution.steps_total} steps completed")
+        return
+
+    # Display current step content
+    console.print(f"[INFO] Step {execution.current_step + 1}/{execution.steps_total}:")
+    console.print(f"  {current_step['content']}")
+    if current_step.get("metadata"):
+        console.print(f"  Comments ({len(current_step['metadata'])}):")
+        for comment in current_step["metadata"]:
+            console.print(f"    {comment}")
+
+    # Mark as read (if not already)
+    if execution.current_step not in execution.steps_read:
+        execution.steps_read.append(execution.current_step)
+        executor.update_execution(execution)
+        console.print(f"\n[INFO] Step {execution.current_step + 1} marked as read")
 
 
 @app.command("next")
 def exec_next(
     execution_id: str = typer.Argument(..., help="Execution instance ID"),
-    output: str = typer.Option(None, "-o", "--output", help="Step output to store"),
-    quiet: bool = typer.Option(False, "-q", "--quiet", help="Quiet mode (no output)"),
 ):
-    """Mark current step complete and advance to next step.
+    """Advance to next step (must read current step first).
 
-    Shows current step content, stores output (if provided), advances execution,
-    and displays next step content.
+    Checks if current step has been read (progressive reading enforcement).
+    If read, advances to next step. If not read, shows error.
+
+    Agent should:
+    1. workflow exec read <id> (read and understand)
+    2. Execute operations (using own tools)
+    3. workflow exec next <id> (advance when ready)
 
     Example:
         workflow exec next commit-abc123
-        workflow exec next commit-abc123 -o "result"
-        workflow exec next commit-abc123 -q  # Quiet mode for scripts
     """
     ensure_directories()
     executor = Executor()
@@ -71,7 +109,19 @@ def exec_next(
         print_output(OutputType.ERROR, f"Execution not found: {execution_id}")
         raise typer.Exit(4)
 
-    # Load workflow and parse
+    # Check if current step has been read
+    if execution.current_step not in execution.steps_read:
+        print_output(OutputType.ERROR, "Current step not read yet")
+        print_output(
+            OutputType.NEXT,
+            f"Read first: workflow exec read {execution_id}",
+        )
+        raise typer.Exit(1)
+
+    # Advance execution
+    executor.advance_execution(execution)
+
+    # Check if completed
     workflow = executor.get_workflow(execution.workflow_name)
     if not workflow:
         print_output(OutputType.ERROR, f"Workflow not found: {execution.workflow_name}")
@@ -81,40 +131,15 @@ def exec_next(
     parser = WorkflowParser(content)
     parser.parse()
 
-    # Get current step BEFORE advancing
-    current_step = executor.get_next_step(execution, parser)
-
-    # Show current step (unless quiet mode)
-    if not quiet and current_step:
-        console.print(
-            f"[INFO] Current step {execution.current_step + 1}/{execution.steps_total}:"
-        )
-        console.print(f"  {current_step['content']}")
-        if current_step.get("metadata"):
-            for comment in current_step["metadata"][:3]:
-                console.print(f"  {comment}")
-
-    # Store output if provided
-    if output:
-        executor.store_output(execution_id, execution.current_step, output)
-
-    # Advance execution
-    executor.advance_execution(execution)
-
-    # Get next step AFTER advancing
     next_step = executor.get_next_step(execution, parser)
     if next_step is None:
         print_output(OutputType.SUCCESS, f"Execution completed: {execution_id}")
-        console.print(f"  Final step: {execution.steps_total}/{execution.steps_total}")
+        console.print(f"  Total steps: {execution.steps_total}")
         return
 
-    # Show next step (unless quiet mode)
-    if not quiet:
-        print_output(
-            OutputType.SUCCESS,
-            f"Advanced to step {execution.current_step}/{execution.steps_total}",
-        )
-        console.print(f"  Next step: {next_step['content']}")
-        if next_step.get("metadata"):
-            for comment in next_step["metadata"][:3]:
-                console.print(f"  {comment}")
+    # Show progress (not content - Agent reads with 'read' command)
+    print_output(
+        OutputType.SUCCESS,
+        f"Advanced to step {execution.current_step + 1}/{execution.steps_total}",
+    )
+    console.print(f"  Read next: workflow exec read {execution_id}")

src/workflow_as_list/config.py

@@ -4,15 +4,22 @@
 import configparser
 from pathlib import Path
 
-from .constants import CONFIG_FILE, PROJECT_ROOT, TOKEN_HUB_LOWER, TOKEN_HUB_UPPER
+from .constants import (
+    CONFIG_FILE,
+    DEFAULT_HOST,
+    DEFAULT_PORT,
+    PROJECT_ROOT,
+    TOKEN_HUB_LOWER,
+    TOKEN_HUB_UPPER,
+)
 from .models import Config
 
 DEFAULT_CONFIG = Config(
     blacklist=[],
     whitelist=[],
     enable_whitelist=False,
-    host="127.0.0.1",
-    port=8080,
+    host=DEFAULT_HOST,
+    port=DEFAULT_PORT,
     config_dir=str(PROJECT_ROOT),
     token_hub_lower=TOKEN_HUB_LOWER,
     token_hub_upper=TOKEN_HUB_UPPER,

src/workflow_as_list/constants.py

@@ -13,7 +13,6 @@
 # Project Root
 # =============================================================================
 
-PROJECT_ROOT = Path.home() / ".workflow-as-list"
 """
 All workflow-as-list state lives here.
 
@@ -23,6 +22,8 @@
 - Easy backup: backup one directory
 - State visible: always know where to look
 """
+PROJECT_ROOT = Path.home() / ".workflow-as-list"
+LOGS_ROOT = PROJECT_ROOT / "logs"
 
 # =============================================================================
 # Configuration Files
@@ -36,7 +37,7 @@
 # =============================================================================
 
 PID_FILE = PROJECT_ROOT / "server.pid"
-SERVER_LOG = PROJECT_ROOT / "logs" / "server.log"
+SERVER_LOG = LOGS_ROOT / "server.log"
 
 # =============================================================================
 # State Directories
@@ -93,9 +94,9 @@ def ensure_directories() -> None:
     Creates PROJECT_ROOT and all subdirectories on first use.
     """
     PROJECT_ROOT.mkdir(parents=True, exist_ok=True)
+    LOGS_ROOT.mkdir(parents=True, exist_ok=True)
     STATE_DIR.mkdir(parents=True, exist_ok=True)
     EXECUTIONS_DIR.mkdir(parents=True, exist_ok=True)
     OUTPUTS_DIR.mkdir(parents=True, exist_ok=True)
     CACHE_DIR.mkdir(parents=True, exist_ok=True)
     IMPORTS_CACHE.mkdir(parents=True, exist_ok=True)
-    (PROJECT_ROOT / "logs").mkdir(parents=True, exist_ok=True)

src/workflow_as_list/models.py

@@ -7,6 +7,9 @@
 
 from pydantic import BaseModel, Field
 
+# Import token constants for Config defaults
+from .constants import TOKEN_HUB_LOWER, TOKEN_HUB_UPPER
+
 
 # Audit status for workflow lifecycle
 class AuditStatus(str, Enum):
@@ -62,6 +65,11 @@ class Execution(BaseModel):
 
     Created when workflow.run() is called.
     Stored in PROJECT_ROOT/state/executions/<name>-<timestamp>.json
+
+    Progressive reading design:
+    - Agent must read current step before advancing (steps_read tracking)
+    - steps_read contains indices of steps that have been read
+    - next command checks if current_step is in steps_read
     """
 
     execution_id: str = Field(..., description="Unique execution identifier")
@@ -78,6 +86,10 @@ class Execution(BaseModel):
     # Execution state
     steps_total: int = Field(default=0, description="Total steps in workflow")
     outputs_path: str = Field(default="", description="Path to outputs directory")
+    steps_read: list[int] = Field(
+        default_factory=list,
+        description="Indices of steps that have been read (progressive reading)",
+    )
 
 
 class Config(BaseModel):
@@ -107,10 +119,10 @@ class Config(BaseModel):
 
     # Token length constraints (from design docs)
     token_hub_lower: int = Field(
-        default=282,
+        default=TOKEN_HUB_LOWER,
         description="Recommended minimum hub tokens (warning if below)",
     )
     token_hub_upper: int = Field(
-        default=358,
+        default=TOKEN_HUB_UPPER,
         description="Maximum hub tokens before decomposition required (error if above)",
     )

src/workflow_as_list/server_manager.py

@@ -188,11 +188,11 @@ def print_status() -> None:
     info = status()
 
     if info["running"]:
-        print(f"✓ Server running (PID: {info['pid']})")
+        print(f"[OK] Server running (PID: {info['pid']})")
         print(f"  Host: {info['host']}")
         print(f"  Port: {info['port']}")
         print(f"  URL: http://{info['host']}:{info['port']}")
         print(f"  API: http://{info['host']}:{info['port']}/docs")
     else:
-        print("✗ Server not running")
+        print("[NO] Server not running")
         print("  Start with: workflow server start")