Stockroom Phase 3 Listing Preparation Plan

Part of the Simple Agility stack. Canonical copy: ~/source/stockroom/docs/superpowers/plans/2026-10-04-stockroom-phase-3-listing-preparation.md (18 test-first tasks with complete code). This page mirrors the decisions for retrieval. It implements rollout phase 3 of StockroomIntakeInventoryPricingDesign and follows StockroomPhase2PricingTriagePlan. The rules pages it reads are in the reselling cluster (ResellingHub). Status: written 2026-10-04. Built and reviewed 2026-10-04: every task had its own review, then a final whole-branch review, one fix wave and a re-review ("ready to merge"). Not yet deployed. What execution changed, and what was parked, is recorded in docs/superpowers/notes/2026-10-04-phase-3-review-carryover.md.

Goal

Turn an item routed to eBay, local sale or a lot into a reviewed, channel-neutral listing. A listing is a title, a description, condition text, item specifics and keywords.

• Photos are captured on a phone.
• A GenAI drafter writes the draft from the catalog facts, the operator's grade and flaw tags, the photos and the rules pages.
• Honesty rules are enforced in the prompt and by code after generation.
• The operator reviews the draft, confirms any claim taken from a photo, and approves.
• FBA items get Amazon condition notes from a template, with no model call.

Architecture

• New core packages:
  • core.photo: the photo store port, a filesystem store and image scaling.
  • core.listing: versioned listing_content, the honesty validator, FBA notes, the draft job and review.
  • core.rules: the category-to-rules-page mapping and a cached Wikantik reader port.
  • core.genai: the ListingDrafter port, plus a provider-neutral prompt and JSON schema.
• New adapter module stockroom-genai:
  • Claude, through the official com.anthropic:anthropic-java SDK. It uses the beta endpoint, server-side fallbacks: "default", a cached system prompt, JSON-schema output and an effort level set per task.
  • Ollama: /api/chat, with images, the schema in format, and think: false.
  • The Wikantik reader: GET /api/pages/{slug}, anonymous.
• A draft_listing job runs on its own job lane, outside any database transaction. It validates the draft and retries once with the violations. It then stores a versioned draft, or a rejected one with its reasons. A draft whose item changed while it was being written is discarded.

Key decisions

Topic	Decision
Photos	Stored on a named volume and mirrored nightly into the backup tree. The browser converts captures to upright JPEG of at most 2400 px. The phone offers "Take photo" (camera) and "Choose photos" (gallery). Limits: JPEG or PNG only, 15 MB, 12 per item. Thumbnails are 400 px.
When drafting runs	Only on request, once photos exist; never automatically.
Draft lifecycle	Each item has versions: draft, rejected (with violations), approved and superseded. Approval moves the item to ready. Edits create a new human_edit version. A change to the condition, identification or kind supersedes current drafts, and sends an approved eBay/local item back to prep with a reason.
Claims	Every specific carries a source: catalog, photo, user or rule. Photo-sourced specifics need confirmation and block approval until they are confirmed. Code checks the claimed source: a catalog specific needs a matching catalog fact, and a user specific is allowed only for the condition, the jacket or a flaw.
Honesty checks	Titles are at most 70 characters. Nine rule codes apply. Claims such as first edition, signed, complete, mint and rare are refused anywhere in the listing; a real catalog title is exempt. Every tagged flaw must be disclosed, never denied, and none invented. No grade word may be better than the grade, and an untested item may not be said to work. No contact details. Catalog facts must be copied exactly.
Rules pages	Read by slug from Wikantik and cached for an hour. When the wiki is down, a stale copy is used and marked. Drafting is blocked with a reason when no copy exists. One page-name pattern is used everywhere.
Providers	Claude (claude-opus-5-5, effort low) by default; Ollama (gemma4:e4b on the inference host) by configuration. Claude runs with a 90 s timeout and 1 retry, inside a 15-minute job lease that is checked at startup.
FBA	Template condition notes: the Amazon label plus one sentence per flaw, at most 1000 characters. They are written whenever an item is routed to FBA or its condition changes.
Golden set	A runner with 3 synthetic cases. The operator adds about 20 real items to measure whether a local model is good enough.
Prep screen	Lists the items awaiting photos, a draft or review, with bulk approval for clean book drafts.

Review focus

1. Model output that breaks the honesty rules or the format is never offered for approval.
2. A provider refusal, truncation, rate limit, outage or missing key leaves a readable reason, never a half-saved draft.
3. When Wikantik is down or a page is missing, the stale copy is used and recorded, or drafting is clearly blocked.
4. Phone photos are handled whether they are huge, HEIC, rotated, duplicated, too many or not images. Files are removed with their item.
5. Review integrity holds: unconfirmed claims, superseded versions, re-routed items and bulk approval all refuse cleanly.

Tasks

1. Phase 2 carry-over (stale reasons, lot Media Mail shipping, current-weight nets)
2. Photos: schema, store and service
3. Photos: HTTP, multipart and the dev volume
4. Listing content: schema, model and review service
5. Honesty validator, FBA condition notes and the FBA hook
6. Rules: category mapping, cache and the rules service
7. GenAI core: port, prompt, schema, images and selection
8. stockroom-genai: Wikantik reader and Ollama drafter
9. The Claude drafter (official Java SDK)
10. The draft job
11. Listing HTTP, prep and review
12. The golden-set runner
13. Frontend: client, API modules, types, labels, image utility
14. Frontend: photos card
15. Frontend: listing card (review, edit, approve) and FBA notes
16. Frontend: Prep page, bulk approve, nav
17. Frontend: rules-page mapping and the carry-over
18. Hand-over: configuration, photo backup, docs, coverage, verification

Out of scope

• Posting, crosslisting, delisting and copy-to-channel helpers (no posting approach has been chosen).
• Photo-first identification (phase 4).
• Sales.
• The Amazon SP-API price source.
• Anything for the rental business.