cowork-flow 0.0.38 → 0.0.40

package/template/.cowork-flow/scripts/commands/add_session.py

@@ -196,6 +196,42 @@ def generate_session_content(
 """
 
 
+def _replace_index_section(
+    lines: list[str],
+    start_marker: str,
+    end_marker: str,
+    replacement: list[str],
+) -> list[str]:
+    rendered: list[str] = []
+    inside = False
+    for line in lines:
+        if start_marker in line:
+            rendered.extend((line, *replacement))
+            inside = True
+        elif end_marker in line:
+            rendered.append(line)
+            inside = False
+        elif not inside:
+            rendered.append(line)
+    return rendered
+
+
+def _insert_session_history(lines: list[str], row: str) -> list[str]:
+    rendered: list[str] = []
+    inside = False
+    inserted = False
+    for line in lines:
+        if MARKER_SESSION_HISTORY_START in line:
+            inside = True
+        elif MARKER_SESSION_HISTORY_END in line:
+            inside = False
+        rendered.append(line)
+        if inside and re.match(r"^\|\s*-", line) and not inserted:
+            rendered.append(row)
+            inserted = True
+    return rendered
+
+
 def update_index(
     index_file: Path,
     dev_dir: Path,
@@ -207,8 +243,6 @@ def update_index(
 ) -> bool:
     """Update index.md with new session info."""
     commit_display = _format_commit_display(commit)
-
-    # Get file number from active_file name
     match = re.search(r"(\d+)", active_file)
     active_num = int(match.group(1)) if match else 0
     files_table = count_journal_files(dev_dir, active_num)
@@ -225,69 +259,26 @@ def update_index(
         print("Error: index.md is missing auto-update markers. Please restore the template first.", file=sys.stderr)
         return False
 
-    # Process sections
     lines = content.splitlines()
-    new_lines = []
-
-    in_current_status = False
-    in_active_documents = False
-    in_session_history = False
-    header_written = False
-
-    for line in lines:
-        if MARKER_CURRENT_STATUS_START in line:
-            new_lines.append(line)
-            in_current_status = True
-            new_lines.append(f"- **Current file**: `{active_file}`")
-            new_lines.append(f"- **Total Sessions**: {new_session}")
-            new_lines.append(f"- **Last Active**: {today}")
-            continue
-
-        if MARKER_CURRENT_STATUS_END in line:
-            in_current_status = False
-            new_lines.append(line)
-            continue
-
-        if MARKER_ACTIVE_DOCUMENTS_START in line:
-            new_lines.append(line)
-            in_active_documents = True
-            new_lines.append("| File | Lines | Status |")
-            new_lines.append("|------|------|------|")
-            new_lines.append(files_table)
-            continue
-
-        if MARKER_ACTIVE_DOCUMENTS_END in line:
-            in_active_documents = False
-            new_lines.append(line)
-            continue
-
-        if MARKER_SESSION_HISTORY_START in line:
-            new_lines.append(line)
-            in_session_history = True
-            header_written = False
-            continue
-
-        if MARKER_SESSION_HISTORY_END in line:
-            in_session_history = False
-            new_lines.append(line)
-            continue
-
-        if in_current_status:
-            continue
-
-        if in_active_documents:
-            continue
-
-        if in_session_history:
-            new_lines.append(line)
-            if re.match(r"^\|\s*-", line) and not header_written:
-                new_lines.append(f"| {new_session} | {today} | {title} | {commit_display} |")
-                header_written = True
-            continue
-
-        new_lines.append(line)
-
-    index_file.write_text("\n".join(new_lines), encoding="utf-8")
+    lines = _replace_index_section(
+        lines,
+        MARKER_CURRENT_STATUS_START,
+        MARKER_CURRENT_STATUS_END,
+        [
+            f"- **Current file**: `{active_file}`",
+            f"- **Total Sessions**: {new_session}",
+            f"- **Last Active**: {today}",
+        ],
+    )
+    lines = _replace_index_section(
+        lines,
+        MARKER_ACTIVE_DOCUMENTS_START,
+        MARKER_ACTIVE_DOCUMENTS_END,
+        ["| File | Lines | Status |", "|------|------|------|", files_table],
+    )
+    row = f"| {new_session} | {today} | {title} | {commit_display} |"
+    lines = _insert_session_history(lines, row)
+    index_file.write_text("\n".join(lines), encoding="utf-8")
     print("[OK] index.md updated.", file=sys.stderr)
     return True
 
@@ -326,87 +317,109 @@ def _auto_commit_workspace(repo_root: Path) -> None:
         print(f"[WARN] Metadata auto-commit failed: {commit_result.stderr.strip()}", file=sys.stderr)
 
 
-def add_session(
-    title: str,
-    commit: str = "-",
-    summary: str = "(add summary)",
-    extra_content: str = "(add details)",
-    auto_commit: bool = False,
-) -> int:
-    """Add a new session."""
-    repo_root = get_repo_root()
-    ensure_developer(repo_root)
-
+def _session_workspace(repo_root: Path):
     developer = get_developer(repo_root)
     if not developer:
         print("Error: developer identity has not been initialized.", file=sys.stderr)
-        return 1
-
+        return None
     dev_dir = get_workspace_dir(repo_root)
-    if not dev_dir:
+    if dev_dir is None or not dev_dir.is_dir():
         print("Error: workspace directory not found.", file=sys.stderr)
-        return 1
-
-    max_lines = get_max_journal_lines(repo_root)
-
+        return None
     index_file = dev_dir / "index.md"
-    today = datetime.now().strftime("%Y-%m-%d")
-
     journal_file, current_num, current_lines = get_latest_journal_info(dev_dir)
-    current_session = get_current_session(index_file)
-    new_session = current_session + 1
+    if not index_file.is_file():
+        print(f"Error: workspace index is missing: {index_file}", file=sys.stderr)
+        return None
+    if journal_file is None:
+        print(f"Error: workspace journal is missing: {dev_dir}", file=sys.stderr)
+        return None
+    return developer, dev_dir, index_file, journal_file, current_num, current_lines
 
-    session_content = generate_session_content(
-        new_session, title, commit, summary, extra_content, today
-    )
-    content_lines = len(session_content.splitlines())
 
-    print("========================================", file=sys.stderr)
-    print("Add Session Record", file=sys.stderr)
-    print("========================================", file=sys.stderr)
-    print("", file=sys.stderr)
-    print(f"Session: {new_session}", file=sys.stderr)
+def _print_session_preview(
+    new_session: int,
+    title: str,
+    commit: str,
+    current_num: int,
+    current_lines: int,
+    content_lines: int,
+) -> None:
+    print("=" * 40, "Add Session Record", "=" * 40, sep="\n", file=sys.stderr)
+    print(f"\nSession: {new_session}", file=sys.stderr)
     print(f"Title: {title}", file=sys.stderr)
-    print(f"Commit: {commit}", file=sys.stderr)
-    print("", file=sys.stderr)
+    print(f"Commit: {commit}\n", file=sys.stderr)
     print(f"Current journal file: {FILE_JOURNAL_PREFIX}{current_num}.md", file=sys.stderr)
     print(f"Current lines: {current_lines}", file=sys.stderr)
     print(f"New content lines: {content_lines}", file=sys.stderr)
-    print(f"Total lines after append: {current_lines + content_lines}", file=sys.stderr)
-    print("", file=sys.stderr)
-
-    target_file = journal_file
-    target_num = current_num
+    print(f"Total lines after append: {current_lines + content_lines}\n", file=sys.stderr)
 
-    if current_lines + content_lines > max_lines:
-        target_num = current_num + 1
-        print(f"[!] Over {max_lines} lines, creating {FILE_JOURNAL_PREFIX}{target_num}.md", file=sys.stderr)
-        target_file = create_new_journal_file(dev_dir, target_num, developer, today, max_lines)
-        print(f"Created: {target_file}", file=sys.stderr)
 
-    # Append session content
-    if target_file:
-        with target_file.open("a", encoding="utf-8") as f:
-            f.write(session_content)
-        print(f"[OK] Appended session to {target_file.name}", file=sys.stderr)
-
-    print("", file=sys.stderr)
+def _session_target(
+    journal_file: Path,
+    current_num: int,
+    current_lines: int,
+    content_lines: int,
+    max_lines: int,
+    dev_dir: Path,
+    developer: str,
+    today: str,
+) -> tuple[Path, int]:
+    if current_lines + content_lines <= max_lines:
+        return journal_file, current_num
+    target_num = current_num + 1
+    print(f"[!] Over {max_lines} lines, creating {FILE_JOURNAL_PREFIX}{target_num}.md", file=sys.stderr)
+    target_file = create_new_journal_file(
+        dev_dir, target_num, developer, today, max_lines
+    )
+    print(f"Created: {target_file}", file=sys.stderr)
+    return target_file, target_num
 
-    # Update index.md
-    active_file = f"{FILE_JOURNAL_PREFIX}{target_num}.md"
-    if not update_index(index_file, dev_dir, title, commit, new_session, active_file, today):
-        return 1
 
-    print("", file=sys.stderr)
-    print("========================================", file=sys.stderr)
+def _print_session_success(new_session: int, target_file: Path) -> None:
+    print("\n" + "=" * 40, file=sys.stderr)
     print(f"[OK] Session {new_session} recorded successfully.", file=sys.stderr)
-    print("========================================", file=sys.stderr)
-    print("", file=sys.stderr)
+    print("=" * 40 + "\n", file=sys.stderr)
     print("Updated files:", file=sys.stderr)
-    print(f"  - {target_file.name if target_file else 'journal'}", file=sys.stderr)
+    print(f"  - {target_file.name}", file=sys.stderr)
     print("  - index.md", file=sys.stderr)
 
-    # Auto-commit workspace changes only when explicitly requested.
+
+def add_session(
+    title: str,
+    commit: str = "-",
+    summary: str = "(add summary)",
+    extra_content: str = "(add details)",
+    auto_commit: bool = False,
+) -> int:
+    """Add a new session."""
+    repo_root = get_repo_root()
+    ensure_developer(repo_root)
+    workspace = _session_workspace(repo_root)
+    if workspace is None:
+        return 1
+    developer, dev_dir, index_file, journal_file, current_num, current_lines = workspace
+    max_lines = get_max_journal_lines(repo_root)
+    today = datetime.now().strftime("%Y-%m-%d")
+    new_session = get_current_session(index_file) + 1
+    session_content = generate_session_content(
+        new_session, title, commit, summary, extra_content, today
+    )
+    content_lines = len(session_content.splitlines())
+    _print_session_preview(
+        new_session, title, commit, current_num, current_lines, content_lines
+    )
+    target_file, target_num = _session_target(
+        journal_file, current_num, current_lines, content_lines,
+        max_lines, dev_dir, developer, today,
+    )
+    with target_file.open("a", encoding="utf-8") as stream:
+        stream.write(session_content)
+    print(f"[OK] Appended session to {target_file.name}\n", file=sys.stderr)
+    active_file = f"{FILE_JOURNAL_PREFIX}{target_num}.md"
+    if not update_index(index_file, dev_dir, title, commit, new_session, active_file, today):
+        return 1
+    _print_session_success(new_session, target_file)
     if auto_commit:
         print("", file=sys.stderr)
         _auto_commit_workspace(repo_root)

package/template/.cowork-flow/scripts/commands/task.py

@@ -16,6 +16,7 @@ else:
     import _bootstrap  # noqa: F401
 
 from application.task_context import (
+    PLANNED_FILE_HINT,
     TaskContextService,
     detect_installed_platforms as _detect_installed_platforms,
     discover_spec_files as _discover_spec_files,
@@ -42,6 +43,7 @@ from application.batch_execution import (
 )
 from commands.task_archive_commands import cmd_archive
 from commands.task_context_commands import (
+    cmd_add_planned_file,
     cmd_add_context,
     cmd_init_context,
     cmd_list_context,
@@ -205,6 +207,15 @@ def _task_context_validation_issues(
     )
 
 
+def _refresh_task_artifact_placeholders(
+    task_dir: Path,
+    repo_root: Path,
+) -> list[str]:
+    service = TaskContextService(repo_root)
+    service.ensure_task_artifact_placeholders(task_dir)
+    return _task_context_validation_issues(task_dir, repo_root)
+
+
 def _optional_readiness_blockers(
     repo_root: Path,
     task_dir: Path,
@@ -243,6 +254,8 @@ def _start_preflight(
         task_dir,
         repo_root,
     )
+    if validation_issues:
+        validation_issues = _refresh_task_artifact_placeholders(task_dir, repo_root)
     if validation_issues:
         return LifecyclePreflightFailure(
             code="TASK-CONTEXT-001",
@@ -250,7 +263,7 @@ def _start_preflight(
             blockers=tuple(validation_issues),
             hint=(
                 "run ./.cowork-flow/run task validate <dir> and fix the "
-                "reported issues"
+                f"reported issues. {PLANNED_FILE_HINT}"
             ),
         )
 
@@ -302,6 +315,102 @@ def _report_lifecycle_repository_error(
     return 1
 
 
+def _resolve_start_task(
+    task_input: str,
+    repo_root: Path,
+) -> Path | None:
+    full_path = _resolve_task_dir(task_input, repo_root)
+    if full_path.is_dir():
+        return full_path
+    print(
+        colored(
+            f"Error: Task not found: {task_input}",
+            Colors.RED,
+        )
+    )
+    print(
+        "Hint: Use task name (e.g., 'my-task') or full path "
+        f"(e.g., '{DIR_WORKFLOW}/tasks/01-31-my-task')"
+    )
+    return None
+
+
+def _run_auto_start(
+    args: argparse.Namespace,
+    full_path: Path,
+    preflight,
+) -> int:
+    failure = preflight(full_path)
+    if failure is not None:
+        return _report_lifecycle_preflight(failure)
+    from common.task.batch_mode import run_batch_entry
+
+    return run_batch_entry(get_repo_root(), full_path, args)
+
+
+def _report_start_failure(
+    result: LifecycleResult,
+    service: TaskLifecycleService,
+) -> int:
+    if result.title:
+        return _report_lifecycle_preflight(result)
+    if result.code == "LIFECYCLE-TRANSITION-001":
+        _print_transition_blockers(list(result.blockers))
+        return 1
+    if result.code == "LIFECYCLE-GATE-001":
+        return _report_gate_block(
+            "Spec enforcement blocked task start",
+            result.gate_result,
+            service.gate_runner,
+        )
+    if result.code == "LIFECYCLE-CONTEXT-001":
+        return _report_missing_session_context()
+    if result.repository_error is not None:
+        return _report_lifecycle_repository_error(result)
+    print(
+        colored("Error: Task lifecycle failed", Colors.RED),
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _report_missing_session_context() -> int:
+    print(
+        colored(
+            "Error: Missing session context. Set "
+            "COWORK_FLOW_CONTEXT_ID or run inside a "
+            "supported host session.",
+            Colors.RED,
+        ),
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _report_start_success(
+    result: LifecycleResult,
+    repo_root: Path,
+    full_path: Path,
+) -> None:
+    task_dir = result.active_task_path or _display_task_path(
+        repo_root,
+        full_path,
+    )
+    print(
+        colored(
+            f"[OK] Active session task set to: {task_dir}",
+            Colors.GREEN,
+        )
+    )
+    print()
+    print(
+        colored(
+            "Fixed agents will load context from this task's jsonl files.",
+            Colors.BLUE,
+        )
+    )
+
+
 def cmd_start(args: argparse.Namespace) -> int:
     """Set the active task for this session."""
     repo_root = get_repo_root()
@@ -315,18 +424,8 @@ def cmd_start(args: argparse.Namespace) -> int:
         )
         return 1
 
-    full_path = _resolve_task_dir(task_input, repo_root)
-    if not full_path.is_dir():
-        print(
-            colored(
-                f"Error: Task not found: {task_input}",
-                Colors.RED,
-            )
-        )
-        print(
-            "Hint: Use task name (e.g., 'my-task') or full path "
-            f"(e.g., '{DIR_WORKFLOW}/tasks/01-31-my-task')"
-        )
+    full_path = _resolve_start_task(task_input, repo_root)
+    if full_path is None:
         return 1
 
     def preflight(
@@ -335,63 +434,14 @@ def cmd_start(args: argparse.Namespace) -> int:
         return _start_preflight(task_dir, repo_root)
 
     if getattr(args, "auto", False):
-        failure = preflight(full_path)
-        if failure is not None:
-            return _report_lifecycle_preflight(failure)
-        from common.task.batch_mode import run_batch_entry
-
-        return run_batch_entry(repo_root, full_path, args)
+        return _run_auto_start(args, full_path, preflight)
 
     service = TaskLifecycleService(repo_root)
     result = service.start(full_path, preflight=preflight)
     if not result.ok:
-        if result.title:
-            return _report_lifecycle_preflight(result)
-        if result.code == "LIFECYCLE-TRANSITION-001":
-            _print_transition_blockers(list(result.blockers))
-            return 1
-        if result.code == "LIFECYCLE-GATE-001":
-            return _report_gate_block(
-                "Spec enforcement blocked task start",
-                result.gate_result,
-                service.gate_runner,
-            )
-        if result.code == "LIFECYCLE-CONTEXT-001":
-            print(
-                colored(
-                    "Error: Missing session context. Set "
-                    "COWORK_FLOW_CONTEXT_ID or run inside a "
-                    "supported host session.",
-                    Colors.RED,
-                ),
-                file=sys.stderr,
-            )
-            return 1
-        if result.repository_error is not None:
-            return _report_lifecycle_repository_error(result)
-        print(
-            colored("Error: Task lifecycle failed", Colors.RED),
-            file=sys.stderr,
-        )
-        return 1
+        return _report_start_failure(result, service)
 
-    task_dir = result.active_task_path or _display_task_path(
-        repo_root,
-        full_path,
-    )
-    print(
-        colored(
-            f"[OK] Active session task set to: {task_dir}",
-            Colors.GREEN,
-        )
-    )
-    print()
-    print(
-        colored(
-            "Fixed agents will load context from this task's jsonl files.",
-            Colors.BLUE,
-        )
-    )
+    _report_start_success(result, repo_root, full_path)
     _run_hooks("after_start", full_path / FILE_TASK_JSON, repo_root)
     return 0
 
@@ -511,6 +561,7 @@ def cmd_complete(args: argparse.Namespace) -> int:
     result = service.complete(
         task_dir,
         completed_at=datetime.now().strftime("%Y-%m-%d"),
+        allow_spec_file_modifications=is_main_session(repo_root),
     )
     if not result.ok:
         if result.code == "LIFECYCLE-TRANSITION-001":
@@ -592,6 +643,60 @@ def cmd_current(args: argparse.Namespace) -> int:
     return 0
 
 
+WORKER_BLOCKED_COMMANDS = frozenset((
+    "create",
+    "init-context",
+    "add-context",
+    "add-planned-file",
+    "start",
+    "batch-resume",
+    "batch-record-result",
+    "review",
+    "complete",
+    "finish",
+    "archive",
+    "add-subtask",
+    "remove-subtask",
+))
+
+COMMANDS = {
+    "create": cmd_create,
+    "init-context": cmd_init_context,
+    "add-context": cmd_add_context,
+    "add-planned-file": cmd_add_planned_file,
+    "validate": cmd_validate,
+    "list-context": cmd_list_context,
+    "start": cmd_start,
+    "batch-resume": cmd_batch_resume,
+    "batch-record-result": cmd_batch_record_result,
+    "current": cmd_current,
+    "review": cmd_review,
+    "complete": cmd_complete,
+    "next": cmd_next,
+    "finish": cmd_finish,
+    "archive": cmd_archive,
+    "add-subtask": cmd_add_subtask,
+    "remove-subtask": cmd_remove_subtask,
+    "list": cmd_list,
+    "list-archive": cmd_list_archive,
+}
+
+
+def _worker_command_blocked(execution_context, command: str) -> bool:
+    if not execution_context.is_worker or command not in WORKER_BLOCKED_COMMANDS:
+        return False
+    print(
+        worker_command_block_message(
+            execution_context,
+            f"task {command}",
+            "Workers must not activate, archive, or mutate "
+            "cowork-flow task state.",
+        ),
+        file=sys.stderr,
+    )
+    return True
+
+
 def main() -> int:
     """CLI entry point."""
     args = build_parser().parse_args()
@@ -600,53 +705,10 @@ def main() -> int:
         show_usage()
         return 1
 
-    worker_blocked_commands = {
-        "create",
-        "init-context",
-        "add-context",
-        "start",
-        "batch-resume",
-        "batch-record-result",
-        "review",
-        "complete",
-        "finish",
-        "archive",
-        "add-subtask",
-        "remove-subtask",
-    }
-    if execution_context.is_worker and args.command in worker_blocked_commands:
-        print(
-            worker_command_block_message(
-                execution_context,
-                f"task {args.command}",
-                "Workers must not activate, archive, or mutate "
-                "cowork-flow task state.",
-            ),
-            file=sys.stderr,
-        )
+    if _worker_command_blocked(execution_context, args.command):
         return 2
 
-    commands = {
-        "create": cmd_create,
-        "init-context": cmd_init_context,
-        "add-context": cmd_add_context,
-        "validate": cmd_validate,
-        "list-context": cmd_list_context,
-        "start": cmd_start,
-        "batch-resume": cmd_batch_resume,
-        "batch-record-result": cmd_batch_record_result,
-        "current": cmd_current,
-        "review": cmd_review,
-        "complete": cmd_complete,
-        "next": cmd_next,
-        "finish": cmd_finish,
-        "archive": cmd_archive,
-        "add-subtask": cmd_add_subtask,
-        "remove-subtask": cmd_remove_subtask,
-        "list": cmd_list,
-        "list-archive": cmd_list_archive,
-    }
-    command = commands.get(args.command)
+    command = COMMANDS.get(args.command)
     if command is None:
         show_usage()
         return 1