# task-lock-format.md — `.tasks/locks/<task-id>.lock` schema

> 도입: 2026-05-14 (task-2575)
> 책임: dev5 마르둑 (task-2575) / pre_push_guard.py 인프라(task-2569+2)

## 개요

`.tasks/locks/<task-id>.lock` 파일은 봇이 sub-task를 시작할 때 생성되는 JSON 락 파일이다.
파일은 `start_task_guard.py._write_lock_file()` 또는 `worktree_manager.cmd_create()` 시점에 생성/갱신된다.

## 필드 정의

| 키 | 타입 | 필수 | 작성자 | 의미 |
|---|---|---|---|---|
| `task_id` | string | ✅ | start_task_guard / worktree_manager | 태스크 식별자 (예: `task-2575`) |
| `bot` | string | △ | start_task_guard | 작업 봇 ID (예: `dev5`) |
| `branch` | string | △ | start_task_guard | 워크트리 브랜치명 (예: `task/task-2575-dev5`) |
| `worktree` | string | △ | start_task_guard | worktree 절대 경로 |
| `pid` | int | △ | start_task_guard | 가드 프로세스 PID |
| `started_at` | ISO8601 | △ | start_task_guard | 작업 시작 시각 (UTC) |
| `heartbeat_timestamp` | ISO8601 | △ | start_task_guard | 마지막 heartbeat 시각 (UTC) |
| `lock_sha` | string(40) | ⭐ | **worktree_manager** | **worktree 생성 시점의 `git rev-parse HEAD` (= origin/main HEAD)** |

★ 필수 표기:
- ✅ = 필수
- △ = 생성자(start_task_guard 또는 worktree_manager)에 따라 조건부
- ⭐ = task-2575 신규 추가, additive

## lock_sha 의미와 기록 규칙

- **정의**: worktree 디렉토리에서 `git rev-parse HEAD`로 추출한 40자 SHA-1 hash.
- **시점**: `worktree_manager.cmd_create()`에서 `git worktree add` 직후, .env 복사 직후.
- **기준 base**: worktree_base는 항상 `origin/main` (workflow 강제) → 따라서 lock_sha == origin/main HEAD SHA (worktree 생성 시점).
- **갱신**: 동일 task에 대해 worktree가 재생성되면 lock_sha도 갱신.
- **기록 방식**: read-modify-write. 기존 키 보존, `lock_sha`만 추가/갱신.

## Backward Compatibility

- `lock_sha` 없는 기존 lock 파일은 그대로 유효.
- `pre_push_guard._resolve_diff_base()`와 `task_scope._resolve_diff_base()`가 lock_sha 부재 시 `origin/main` fallback (task-2569+2에서 이미 인프라 반영).

## 사용처

1. `scripts/pre_push_guard.py:37-55` — `_resolve_diff_base()` (사용)
2. `scripts/task_scope.py:149-167` — `_resolve_diff_base()` (사용)
3. `scripts/worktree_manager.py:cmd_create()` — `lock_sha` 기록 (생성)
4. `scripts/taskctl_start.py:record_lock_sha()` — `lock_sha` 갱신 헬퍼 (helper)

## 보존 정책

- lock 파일은 task 완료(`.done`) 후 cleanup-stale-tasks가 정리.
- lock 파일에 PII/secret 저장 금지.

## 변경 이력

- 2026-05-14 task-2575: `lock_sha` 필드 추가 (additive)
- 2026-05-14 task-2569+2: `_resolve_diff_base()` 인프라 반영 (PR #121)
- (이전): 5키 schema (task_id, bot, branch, worktree, pid, started_at, heartbeat_timestamp)