---
phase: 13-logging-foundation
plan: 03
type: execute
wave: 2
depends_on:
  - 13-01
  - 13-02
files_modified:
  - paperforge/worker/sync.py
  - paperforge/worker/ocr.py
  - paperforge/worker/deep_reading.py
  - paperforge/worker/status.py
  - paperforge/commands/sync.py
  - paperforge/commands/ocr.py
  - paperforge/commands/status.py
autonomous: true
requirements:
  - OBS-03
must_haves:
  truths:
    - "paperforge sync --verbose enables DEBUG-level logging"
    - "paperforge ocr --verbose enables DEBUG-level logging"
    - "paperforge deep-reading --verbose enables DEBUG-level logging"
    - "paperforge status --verbose enables DEBUG-level logging"
    - "All 4 commands accept the global --verbose/-v flag without error"
  artifacts:
    - path: "paperforge/commands/sync.py"
      provides: "verbose passthrough from args to worker functions"
      contains: "verbose"
    - path: "paperforge/commands/ocr.py"
      provides: "verbose passthrough from args to run_ocr"
      contains: "verbose"
    - path: "paperforge/commands/status.py"
      provides: "verbose passthrough from args to run_status"
      contains: "verbose"
  key_links:
    - from: "paperforge/commands/*.py"
      to: "paperforge/worker/*.py"
      via: "verbose=getattr(args, 'verbose', False) -> worker_func(verbose=...)"
      pattern: "verbose=getattr"
---

<objective>
Wire the global `--verbose` flag through command modules to worker function signatures for sync, ocr, status, and deep-reading commands.

Purpose: Per OBS-03, all primary CLI commands must accept `--verbose`/`-v` and propagate it to enable DEBUG-level output. Plan 01 added the global flag to the CLI parser. This plan completes the wiring by adding `verbose` parameters to worker functions and passing the flag through command modules.

Output:
- Worker function signatures updated with `verbose=False` parameter
- Command modules wire `args.verbose` through to worker function calls
</objective>

<execution_context>
@C:/Users/Lin/.opencode/get-shit-done/workflows/execute-plan.md
@C:/Users/Lin/.opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/13-logging-foundation/13-CONTEXT.md
@.planning/phases/13-logging-foundation/13-RESEARCH.md
@paperforge/commands/sync.py
@paperforge/commands/ocr.py
@paperforge/commands/status.py
@paperforge/commands/deep.py
@paperforge/commands/repair.py
@paperforge/worker/sync.py
@paperforge/worker/ocr.py
@paperforge/worker/deep_reading.py
@paperforge/worker/status.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add verbose parameter to worker function signatures</name>

  <files>
    paperforge/worker/sync.py
    paperforge/worker/ocr.py
    paperforge/worker/status.py
  </files>

  <read_first>
  - paperforge/worker/deep_reading.py -- Reference: existing `def run_deep_reading(vault, verbose=False)` signature (already has verbose)
  - paperforge/worker/repair.py -- Reference: existing `def run_repair(vault, paths, verbose=False, ...)` signature (already has verbose)
  - paperforge/worker/sync.py -- Current signatures: `def run_selection_sync(vault: Path) -> int:` and `def run_index_refresh(vault: Path) -> int:`
  - paperforge/worker/ocr.py -- Current signature: `def run_ocr(vault: Path) -> int:`
  - paperforge/worker/status.py -- Current signature: `def run_status(vault: Path) -> int:`
  </read_first>

  <action>
  Modify worker function signatures to add `verbose: bool = False` parameter:

  **A) paperforge/worker/sync.py:**

  Change line ~808:
  ```python
  # FROM:
  def run_selection_sync(vault: Path) -> int:
  # TO:
  def run_selection_sync(vault: Path, verbose: bool = False) -> int:
  ```

  Change line ~1355:
  ```python
  # FROM:
  def run_index_refresh(vault: Path) -> int:
  # TO:
  def run_index_refresh(vault: Path, verbose: bool = False) -> int:
  ```

  No behavioral changes needed INSIDE the functions yet -- the `verbose` parameter is accepted and available for future use. The parameter serves as a contract for the command module wiring.

  **B) paperforge/worker/ocr.py:**

  Change line ~1217:
  ```python
  # FROM:
  def run_ocr(vault: Path) -> int:
  # TO:
  def run_ocr(vault: Path, verbose: bool = False) -> int:
  ```

  **C) paperforge/worker/status.py:**

  Find `run_status` function signature (around line 563):
  ```python
  # FROM:
  def run_status(vault: Path) -> int:
  # TO:
  def run_status(vault: Path, verbose: bool = False) -> int:
  ```

  Also find `run_doctor` function signature and add `verbose: bool = False` parameter:
  ```python
  # FROM:
  def run_doctor(vault: Path) -> int:
  # TO:
  def run_doctor(vault: Path, verbose: bool = False) -> int:
  ```

  For each function, only change the signature -- do NOT modify any logic inside the function body. The `verbose` parameter is received and available for use, even if the current implementation doesn't branch on it yet. This follows the contract-first pattern.
  </action>

  <acceptance_criteria>
  - `run_selection_sync` signature includes `verbose: bool = False`
  - `run_index_refresh` signature includes `verbose: bool = False`
  - `run_ocr` signature includes `verbose: bool = False`
  - `run_status` signature includes `verbose: bool = False`
  - `run_doctor` signature includes `verbose: bool = False`
  - All existing call sites still work (backward compatible due to default `False`)
  - No changes to function bodies, only signatures
  </acceptance_criteria>

  <verify>
  <automated>python -c "import sys; sys.path.insert(0, '.'); import inspect; from paperforge.worker.sync import run_selection_sync, run_index_refresh; assert 'verbose' in inspect.signature(run_selection_sync).parameters; assert 'verbose' in inspect.signature(run_index_refresh).parameters; from paperforge.worker.ocr import run_ocr; assert 'verbose' in inspect.signature(run_ocr).parameters; from paperforge.worker.status import run_status, run_doctor; assert 'verbose' in inspect.signature(run_status).parameters; assert 'verbose' in inspect.signature(run_doctor).parameters; print('OK')"</automated>
  </verify>

  <done>
  All 6 worker functions (`run_selection_sync`, `run_index_refresh`, `run_ocr`, `run_status`, `run_doctor`) accept `verbose: bool = False` parameter. Backward compatible.
  </done>
</task>

<task type="auto">
  <name>Task 2: Wire verbose through command modules to worker functions</name>

  <files>
    paperforge/commands/sync.py
    paperforge/commands/ocr.py
    paperforge/commands/status.py
  </files>

  <read_first>
  - paperforge/commands/deep.py -- Reference: existing `verbose=getattr(args, 'verbose', False)` wiring pattern (line 36)
  - paperforge/commands/repair.py -- Reference: existing `verbose=getattr(args, 'verbose', False)` wiring pattern (line 42)
  - paperforge/commands/sync.py -- Current dispatch: `run_selection_sync(vault)` and `run_index_refresh(vault)`
  - paperforge/commands/ocr.py -- Current dispatch: `run_ocr(vault)`
  - paperforge/commands/status.py -- Current dispatch: `run_status(vault)`
  </read_first>

  <action>
  Wire `verbose` from `args` (populated by the global `--verbose` flag added in Plan 01) through each command module to its worker function call.

  **A) paperforge/commands/sync.py:**

  Lines 81-82 currently:
  ```python
  code = run_selection_sync(vault)
  ```
  Change to:
  ```python
  code = run_selection_sync(vault, verbose=getattr(args, "verbose", False))
  ```

  Lines 87-88 currently:
  ```python
  code = run_index_refresh(vault)
  ```
  Change to:
  ```python
  code = run_index_refresh(vault, verbose=getattr(args, "verbose", False))
  ```

  **B) paperforge/commands/ocr.py:**

  Line 74 currently:
  ```python
  exit_code = run_ocr(vault)
  ```
  Change to:
  ```python
  exit_code = run_ocr(vault, verbose=getattr(args, "verbose", False))
  ```

  **C) paperforge/commands/status.py:**

  Line 40 currently:
  ```python
  return run_status(vault)
  ```
  Change to:
  ```python
  return run_status(vault, verbose=getattr(args, "verbose", False))
  ```

  **Verification pattern for all changes:**
  - Use `getattr(args, "verbose", False)` to safely handle the case where `args` might not have `verbose` (e.g., when command modules are called outside the CLI dispatch, such as in tests)
  - The `verbose` default of `False` in worker function signatures ensures backward compatibility
  - The global `--verbose` flag from Plan 01 populates `args.verbose = True` when the flag is used

  **No changes needed to:**
  - `commands/deep.py` — already has `verbose=getattr(args, "verbose", False)` on line 36
  - `commands/repair.py` — already has `verbose=getattr(args, "verbose", False)` on line 42
  - `cli.py` — already configured with global `--verbose` flag in Plan 01
  </action>

  <acceptance_criteria>
  - `commands/sync.py` passes `verbose=getattr(args, "verbose", False)` to `run_selection_sync()` and `run_index_refresh()`
  - `commands/ocr.py` passes `verbose=getattr(args, "verbose", False)` to `run_ocr()`
  - `commands/status.py` passes `verbose=getattr(args, "verbose", False)` to `run_status()`
  - All 3 commands work with `--verbose`, `-v`, and without the flag
  - `python -c "from paperforge.cli import main; main(['--verbose', 'status'])"` exits with code 0
  - `python -c "from paperforge.cli import main; main(['status'])"` exits with code 0
  </acceptance_criteria>

  <verify>
  <automated>python -c "import sys; sys.path.insert(0, '.'); import inspect; from paperforge.commands.sync import run; sig=inspect.signature(run); # verify run() uses getattr; src=open('paperforge/commands/sync.py').read(); assert 'verbose=getattr(args' in src; src2=open('paperforge/commands/ocr.py').read(); assert 'verbose=getattr(args' in src2; src3=open('paperforge/commands/status.py').read(); assert 'verbose=getattr(args' in src3; print('OK')"</automated>
  </verify>

  <done>
  All 3 primary commands (sync, ocr, status) pass the global `--verbose` flag to their respective worker functions. deep-reading and repair were already wired.
  </done>
</task>

</tasks>

<verification>
1. Sync, ocr, and status worker functions accept `verbose: bool = False` parameter
2. Sync, ocr, and status command modules pass `args.verbose` to workers
3. deep-reading and repair commands continue to work (already wired)
4. All commands work with and without `--verbose`/`-v`
</verification>

<success_criteria>
- All primary CLI commands (sync, ocr, deep-reading, status) propagate the global `--verbose` flag
- Worker functions accept and handle the verbose parameter
- No regressions in command dispatch behavior
- Backward compatible: all flags work at both root and subcommand level
</success_criteria>

<output>
After completion, create `.planning/phases/13-logging-foundation/13-03-SUMMARY.md`
</output>
