chore: make work-item a reusable subproject

AGENTS.md

@@ -6,31 +6,75 @@ the established project invariants: never inspect or process content beneath any
 `immich-go` uploads rather than External Libraries; keep operations resume-safe; and
 treat the existing CLI implementations as primary donors rather than rewriting them.
 
+## Work-item helper
+
+The reusable workflow helper is a self-contained subproject under `work_item/`:
+
+- launcher: `work_item/scripts/work-item`;
+- Python wrapper: `work_item/scripts/python`;
+- active project configuration: `work_item/.work-item.yml`;
+- implementation: `work_item/src/work_item/`;
+- helper tests: `work_item/tests/`;
+- complete usage and configuration reference: `work_item/README.md`.
+
+Do not recreate root-level `scripts/`, `tests/`, or `.work-item.*` files for the
+helper. Its launcher adds `work_item/src/` to `PYTHONPATH` and selects Conda base when
+it provides Python 3.12 or newer, with supported system Python as fallback.
+
+The helper supports TOML, YAML, dotenv, and `WORK_ITEM_*` environment overrides. This
+repository intentionally keeps its configuration inside `work_item/.work-item.yml`.
+Do not change its repository identity, required tests, allow list, deny list, size
+limit, or CI policy merely to bypass a workflow failure.
+
+Workflow state is local at `.git/work-item-state.json` and must never be committed.
+`claim` is resume-aware:
+
+- with no active state, it selects the lowest-numbered eligible story whose Gitea
+  dependencies are closed, updates `main`, creates the feature branch, assigns the
+  issue, and applies `status/in-progress`;
+- on the active story branch, rerunning it preserves and resumes dirty implementation
+  work;
+- from another clean branch, rerunning it switches back to the claimed branch;
+- for a blocked story, rerunning it explicitly returns that same story to
+  `status/in-progress` instead of selecting a later story;
+- a story already in review cannot be replaced by another claim.
+
+`submit` always combines configured required tests with repeated story-specific
+`--test` arguments and runs duplicate commands only once. It checks denied/allowed
+paths, maximum file size, likely credentials/private keys, and Git whitespace errors
+before allowing a commit. The first invocation without `--yes` is a mandatory review
+step; only the confirmed invocation may stage, commit, push, open/reuse a pull request,
+record test evidence, and move the issue to review. If push or PR-related remote work
+partially succeeds, rerun the same command so its recovery logic can reuse the existing
+commit and pull request.
+
 ## Mandatory implementation workflow
 
 When asked to start, resume, or continue implementation, work from this isolated Git
-repository and use `scripts/work-item`. Gitea issues and their dependencies are the
-authoritative backlog.
+repository and use `work_item/scripts/work-item`. Gitea issues and their dependencies
+are the authoritative backlog.
 
-1. Run `scripts/work-item claim`.
-2. Work only on the claimed story and its generated feature branch.
+1. Run `work_item/scripts/work-item claim`.
+2. Run `work_item/scripts/work-item status` when resuming or whenever branch/state is
+   uncertain. Work only on the claimed story and its generated feature branch.
 3. Read the entire issue, linked specification, dependencies, and acceptance criteria.
 4. Inspect the legacy CLI donors before replacing applicable behavior. Update the donor
    ledger and characterization tests required by the story.
 5. Implement every acceptance criterion and its automated tests.
 6. Run story-specific tests and the accumulated regression suite required by the epic.
-7. Run `scripts/work-item submit --test "<story-specific command>"` without `--yes` and
-   review the reported diff and file list.
+7. Run `work_item/scripts/work-item submit --test "<story-specific command>"` without
+   `--yes` and review the reported diff and file list.
 8. If the changes are correct and safe, rerun with `--yes`. This commits, pushes, opens
    a pull request, records test evidence, and moves the issue to review.
-9. After review and successful CI, run `scripts/work-item complete --merge`. This
-   verifies the merge, closes the issue, returns to updated `main`, and removes the
-   local feature branch.
+9. After review and successful CI, run
+   `work_item/scripts/work-item complete --merge`. This verifies the merge, closes the
+   issue, returns to updated `main`, and removes the local feature branch.
 10. Continue with the next eligible story by returning to step 1.
 
-If genuinely blocked, run `scripts/work-item block --reason "<precise reason>"` and
-stop. Never skip to a later story whose dependencies are open. Never mark work done
-when tests are missing, skipped, or failing.
+If genuinely blocked, run
+`work_item/scripts/work-item block --reason "<precise reason>"` and stop. Never skip to
+a later story whose dependencies are open. Never mark work done when tests are
+missing, skipped, or failing.
 
 ## Git and privacy safety
 
@@ -39,10 +83,20 @@ when tests are missing, skipped, or failing.
   credentials, environment files, caches, generated thumbnails, or runtime data.
 - Never use force-push, destructive reset, untracked-file deletion, or automatic merge
   conflict resolution.
-- Do not bypass `scripts/work-item` safety checks or manually close implementation
-  issues to conceal a failed transition.
+- Do not bypass `work_item/scripts/work-item` safety checks or manually close
+  implementation issues to conceal a failed transition.
+- Do not edit `.git/work-item-state.json` manually. Use `claim`, `block`, `submit`, and
+  `complete` so local Git state and Gitea state remain consistent.
 - Preserve unrelated user changes and stop if the working tree is unexpectedly dirty.
 
+When modifying the helper itself, run all of its own checks from the repository root:
+
+```bash
+ruff check --no-cache work_item/src work_item/tests
+ruff format --check --no-cache work_item/src work_item/tests
+work_item/scripts/python -m unittest discover -s work_item/tests -v
+```
+
 ## Completion standard
 
 A story is complete only when its pull request is merged, required automated tests and