photoanalyzer/AGENTS.md

# Agent Instructions — Photo Analyzer

`INTEGRATED_PIPELINE_CONCEPT.md` is the authoritative product and architecture
foundation for every user story. Before claiming or resuming implementation, read it
in full, then use it to interpret the story's scope, acceptance criteria, donor
strategy, architecture boundaries, safety invariants, fixture requirements, and test
obligations. Read `CLAUDE.md` as operational donor context after the concept. If an
issue, backlog Markdown file, or implementation idea conflicts with the concept, do
not silently follow the conflicting source: preserve the concept and stop for an
explicit decision when the conflict materially changes scope or behavior.

Re-read the complete concept whenever context has been compacted/lost, the concept has
changed since the story began, or an implementation session is resumed without a
reliable record that the current version was read. A summary, prior familiarity, or
reading only the story's phase is not sufficient.

Preserve the established project invariants: never inspect or process content beneath any
`_IGNORE/` directory; write verified EXIF before Immich upload; use managed
`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 `work_item/scripts/work-item`. Gitea issues and their dependencies
are the authoritative backlog.

1. Read the current `INTEGRATED_PIPELINE_CONCEPT.md` completely and treat it as the
   foundation for all decisions in the story. Then read `CLAUDE.md` for operational
   donor context.
2. Run `work_item/scripts/work-item claim`.
3. 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.
4. Read the entire issue, linked specification, dependencies, and acceptance criteria.
   Reconcile them with the concept before designing or changing code.
5. Inspect the legacy CLI donors before replacing applicable behavior. Update the donor
   ledger and characterization tests required by the story.
6. Implement every acceptance criterion and its automated tests.
7. Run story-specific tests and the accumulated regression suite required by the epic.
8. Run `work_item/scripts/work-item submit --test "<story-specific command>"` without
   `--yes` and review the reported diff and file list.
9. 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.
10. 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.
11. Continue with the next eligible story by returning to step 1.

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

- Never run automated Git operations from the personal photo-library directory.
- Never stage or commit real photos, videos, `_IGNORE/` content, databases, logs,
  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 `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
CI pass, test evidence is recorded on the issue, the issue is closed with
`status/done`, and the local repository is back on a clean, current `main` branch.