Image inventory and dynamic file workflows¶
PRD-001 | Draft | Implemented in the working tree. The user authorized implementation on September 28, 2026 and settled the material workflow policies. This document records that implementation, not a release or formal PRD approval.
Business authority: BRD-2026-Q3-001, approved version 1.0.0. The user approved the business scope with an explicit measurement waiver. This PRD remains draft. Implementation authorization does not approve proposed performance targets, business measurements or release readiness.
Executive Summary¶
Extend Archivist with image inventory and relocation capabilities that compose with ZIP extraction in its existing pipeline. Users should be able to inspect a folder tree, discover matching pictures inside ZIPs, review a report, and approve extraction and relocation without manually unpacking each archive first.
The defining move sequence is list pictures, obtain human confirmation, extract
ZIPs, then move pictures. A move request supplies those prerequisites even when
the caller does not explicitly select listing or extraction. Dry-run stops at the
inventory/report boundary and performs no extraction or movement.
Adding --copy to --move-pictures changes the final action to duplication:
source pictures and ZIPs remain unchanged, including during prerequisite extraction.
The subsequent user request also requires unchanged EXIF/date-taken data and
preservation of original available filesystem creation/modification dates.
The immediate scope is a deterministic CLI and dynamic workflow builder. The conversational agent and AG-UI proposal is deferred to future-spec.md. No model, agent framework, web interface, or hosted service is needed for this scope. Release date, delivery ownership and representative performance targets remain open.
Product Context¶
Problem and current baseline¶
Pictures can be scattered across folders and ZIP archives. The requested outcome is one inspectable, filterable inventory followed by an explicitly approved extraction-and-move operation.
At source revision 42666b2, Archivist has a sequence-based workflow builder,
recursive ZIP extraction, configurable metadata cleanup, and console/file reports.
It does not have the proposed image actions, extension filter, or destination option.
That baseline workflow always includes ZIP extraction; cleanup is enabled unless
disabled by --leave-* flags. The implementation preserves it when no explicit
action flags are selected, and adds image-specific inventory/approval/extraction/
transfer steps using the existing builder and integer-counter Step contract.
Current runs preview by default, with --apply enabling mutations. The legacy
--dry-run flag overrides ARCHIVIST_APPLY=true. Successful extraction deletes
the original ZIP unless --leave-zip is set. Existing-folder conflicts can prompt
for merging during interactive application. These are compatibility constraints
preserved by the new action selection. New image moves have the separately
approved delayed-disposal policy below.
Evidence and precedence¶
Source |
Product evidence |
|---|---|
Conversation: initial request |
Name/type/full-path listing, |
Conversation: ZIP clarification |
Inspect ZIP contents and report the number of images inside archives |
Conversation: dynamic workflow clarification |
Combine |
Conversation: final move-order clarification |
List, confirm, extract, then move; extraction is an implicit move prerequisite |
Conversation: specification request |
Document the CLI scope now and keep the agent/AG-UI route in a separate future specification |
Existing command behavior and implementation conventions |
The dynamic-workflow clarification supersedes the earlier interpretation of a separate, mutually exclusive image command. Unanswered questions and assistant recommendations are not treated as user-approved decisions. The subsequently approved business scope is recorded in BRD-2026-Q3-001; no feasibility handoff was supplied.
Users and Personas¶
User |
Job to be done |
Success outcome |
|---|---|---|
Archivist operator managing a local or mounted folder tree |
Find and collect pictures across ordinary folders and archives |
Review one inventory and approve the intended file operations |
Existing CLI user |
Continue using extraction and cleanup |
Understand any new mode rules without accidentally enabling unrelated actions |
The first role comes from the request; the second is a compatibility stakeholder inferred from the existing product. No broader user research or adoption estimates are claimed.
Design Decisions¶
Confirmed means explicitly selected by the user. Implemented denotes engineering policy consistent with the approved intent. Open means unresolved.
ID |
Status |
Decision |
|---|---|---|
DD-001 |
Confirmed |
Actions compose in the existing pipeline rather than selecting isolated image and ZIP modes |
DD-002 |
Confirmed |
A move requires listing, human confirmation, ZIP extraction, and movement in that order |
DD-003 |
Confirmed |
Listing and move dry-run have the same inventory/report behavior; archives are inspected without extracting images |
DD-004 |
Confirmed |
The inventory is |
DD-005 |
Confirmed |
Agent/AG-UI work is deferred and must not become a dependency of the CLI scope |
DD-006 |
Implemented |
Canonical |
DD-007 |
Implemented |
Preserve no-action legacy behavior; explicit actions include only selected stages and prerequisites, never implicit metadata cleanup |
DD-008 |
Implemented |
Retain |
DD-009 |
Confirmed |
Filters select pictures, while applicable ZIPs are extracted completely; nonselected contents remain in sibling extraction folders for moves |
DD-010 |
Confirmed |
Number collisions oldest-first using original creation time, explicitly reported original-mtime fallback, and full-source-location ties |
DD-011 |
Confirmed |
|
DD-012 |
Confirmed |
Flatten destination layout |
DD-013 |
Confirmed |
Delete original physical ZIPs only after complete extraction and successful transfer; copy and |
DD-014 |
Confirmed |
Recursively inspect nested ZIPs with bounded resources and visible errors |
DD-015 |
Confirmed |
Stop on failure, retain not-yet-removed ZIPs, and report partial outcomes without promising rollback |
DD-016 |
Confirmed |
Append clearly separated runs to an existing |
DD-017 |
Confirmed |
Number every colliding incoming file from |
DD-018 |
Confirmed |
List-plus-applied-extraction without transfer follows list, approval, extraction |
DD-019 |
Implemented |
Resolve relative destinations against process cwd; require a destination only when applying transfers |
DD-020 |
Implemented |
Reject overlapping roots, unsafe paths, source-mutating copy modifiers and existing extraction targets; never overwrite destination pictures |
Implemented command surface¶
These commands are implemented in the working tree. JPG,PNG,ARW is a concrete
filter example; the conversational etc. is not an extension or wildcard.
# Inventory files and matching ZIP entries; return the pictures.log location.
archivist --list-images --parent-folder "C:\Photos" --filter JPG,Png,ARW
# Compose actions while previewing only; do not extract.
archivist --list-images --extract-zip --parent-folder "C:\Photos" --dry-run --filter JPG,Png,ARW
# Same inventory/report behavior as listing; do not prompt or create the destination.
archivist --move-pictures --parent-folder "C:\Photos" --destination "D:\Collected" --dry-run --filter JPG,Png,ARW
# Apply: inventory -> human approval -> extract -> move.
archivist --move-pictures --parent-folder "C:\Photos" --destination "D:\Collected" --apply --filter JPG,Png,ARW
# Apply: inventory -> human approval -> safe extraction -> copy.
archivist --move-pictures --copy --parent-folder "C:\Photos" --destination "D:\Collected" --apply --filter JPG,Png,ARW
# Copy preview: inventory only, with no copies, extraction, or destination creation.
archivist --move-pictures --copy --parent-folder "C:\Photos" --destination "D:\Collected" --dry-run --filter JPG,Png,ARW
Relative destinations resolve against the current working directory. A destination is required for an applied transfer, but optional for inventory-only preview.
Product Goals¶
These are proposed acceptance targets for the first image-workflow release, not measured business improvements or a delivery commitment.
Goal |
Priority |
Target and measurement |
|---|---|---|
GOAL-001 |
MUST |
On the agreed readable test corpus, inventory 100% of supported matching on-disk files and archive entries, with exact per-archive counts |
GOAL-002 |
MUST |
Across dry-run and declined-confirmation scenarios, make zero source/destination content changes other than the requested report |
GOAL-003 |
MUST |
Every supported transfer follows list -> confirmation -> extraction -> movement or source-preserving copying, including omitted prerequisite flags and permuted flag order |
SMART assessment is deferred: the outcomes and acceptance measurements are specific, but corpus limits, resources, ownership, and a release date are unresolved.
Functional Requirements¶
All actors below are the Archivist operator. Priorities follow MUST/SHOULD/COULD/ WON’T terminology. Acceptance and goal links are in the traceability matrix.
ID |
Priority / basis |
Trigger and expected outcome |
|---|---|---|
FR-001 |
MUST / Confirmed |
When multiple actions are selected, execute a dependency-ordered workflow containing those actions and their prerequisites once, regardless of argument order |
FR-002 |
MUST / Confirmed |
When listing pictures, recursively identify matching files beneath the selected parent folder |
FR-003 |
MUST / Confirmed |
When listing pictures, also inspect ZIPs found beneath the parent folder and report matching image-entry counts for each archive and in total |
FR-004 |
MUST / Confirmed |
When listing completes, write each matching image’s name, type, and full source location to |
FR-005 |
MUST / Implemented clarification |
When |
FR-006 |
MUST / Confirmed |
When moving pictures is requested, include listing, confirmation, and ZIP extraction before transfer even if those actions were not explicitly requested; |
FR-007 |
MUST / Confirmed |
Before ZIP extraction or transfer, present the matching file count, affected extensions, source-folder impact, destination, and move/copy mode, then wait for explicit human approval |
FR-008 |
MUST / Confirmed |
After approval, extract applicable ZIPs discovered beneath the parent tree before picture transfer; copy mode must stage extraction without changing the source tree or original ZIPs |
FR-009 |
MUST / Confirmed |
Without |
FR-010 |
MUST / Confirmed |
When dry-run is active, inspect and report without extracting, moving, copying pictures, deleting, overwriting source files, or creating destination folders; only the inventory/report write is permitted |
FR-011 |
MUST / Confirmed |
For the same root, filter, and unchanged inputs, listing, move dry-run, and copy dry-run produce the same inventory entries, counts, report location, and no approval prompt |
FR-012 |
MUST / Approved business scope |
When discovery or execution is incomplete, report failed/skipped items and distinguish planned, completed, and remaining operations rather than declaring all selected pictures moved |
FR-013 |
MUST / Confirmed |
When destination filenames collide, append numbered suffixes before the extension, such as |
FR-014 |
MUST / Confirmed |
When |
FR-015 |
MUST / Confirmed follow-up |
When image extraction or transfer succeeds, preserve original picture bytes/EXIF and available original creation/modification dates; if a known filesystem date cannot be restored exactly, report failure before removing the affected source or original ZIP |
Copy mode¶
--copy is a modifier of the picture-transfer action, not a separate stage
appended after movement and not a command to copy the ZIP itself. It replaces
the final move with a copy. It retains filter selection, archive inventory,
human approval, and collision-numbering rules. Both image aliases select the same
copy behavior.
Effect |
Move without |
With |
|---|---|---|
Selected ordinary pictures |
Relocated |
Duplicated; original paths and contents retained |
Selected archived pictures |
Extracted before moving |
Extracted outside the source tree, then duplicated to the destination |
Original ZIPs |
Deleted only after complete extraction and successful transfer, unless |
Always retained byte-for-byte; no deletion or rewrite |
Collision names |
Oldest-first available numbered suffix |
Same policy, applied only to destination copies |
Human approval |
Before extraction or movement |
Before extraction or copying; label mode as COPY |
Dry-run |
Inventory/report only |
Same inventory/report only |
The existing extractor deletes ZIPs by default and extracts beside the source archive. Those behaviors cannot be reused unchanged for copy mode. Extraction output and temporary staging must be outside the source tree, with no metadata cleanup of the source. The destination must be disjoint from the source tree; reject an overlapping source/destination before any mutation. This prevents a copy from overwriting a source, introducing files into the source tree, or recursively discovering its own output.
“Source unchanged” means no application-initiated changes to source file paths,
bytes, or metadata; filesystem-managed read-access bookkeeping is excluded.
The previously requested pictures.log remains the explicit local-report write
exception. If the chosen report path is an existing source image or archive,
reject it rather than overwrite source data.
Copy mode must preserve sources even if --extract-zip is explicitly selected:
use the same source-preserving prerequisite once, not a separate destructive
extraction stage. Reject requested combinations that would mutate sources,
including explicitly selected source cleanup, rather than silently overriding
the promise. Report successful transfers as copied, not moved.
--copy without a picture-transfer action is an argument error.
ARCHIVIST_COPY maps to the same modifier; it does not grant approval.
Original picture metadata and dates¶
The user’s September 28 follow-up explicitly requests initial EXIF, picture-taken dates and original file creation/modification dates. Embedded metadata remains byte-identical; no EXIF parsing/re-encoding or substitution of date categories is required. Capture original filesystem dates during inventory, before reading picture payloads; retain integer precision through extraction and final transfer.
Read ZIP local and central NTFS/extended Unix timestamp extras, preferring NTFS precision, then extended Unix, then DOS modification time interpreted in the local timezone. If creation was not recorded or exposed by the source OS, report it as unavailable; the output’s OS-assigned creation time is not presented as original. Do not infer creation from EXIF, modification or staging-file metadata.
Restore and verify original modification and known creation dates before source
removal. Native creation restoration exists for Windows; Linux volumes that do
not support required timestamp restoration produce explicit failure, retaining
the affected source and not-yet-removed ZIPs. Earlier successful transfers are
not rolled back. Access-time bookkeeping and POSIX metadata-change ctime are
excluded from the exact-date guarantee. The legacy extraction-only workflow is unchanged.
Filename collision handling¶
The user selected oldest to newest creation-date order for collisions; this
applies to both moves and copies. Existing destination
files are not renamed or overwritten to make room for incoming pictures.
Noncolliding files retain their names. Within a collision group, lower available
numbers go to earlier-created incoming files. Already occupied numbered names
must not be reused; numbers use at least three digits and do not wrap after 999.
These numbering safeguards elaborate the requested (001, 002, etc.) behavior.
For example, if photo.jpg already exists and two incoming photo.jpg files were
created in 2020 and 2023, respectively, the older becomes photo (001).jpg and the
newer photo (002).jpg when those names are free. If (001) is already occupied,
it is preserved and numbering uses the next available names.
Creation time means original source metadata, not the time a copy or extracted file is newly written. Standard ZIP timestamps generally describe modification time, not creation time, and creation metadata is not portable across filesystems. Use original modification time only as an explicitly reported fallback; never substitute POSIX metadata-change time, image capture time or extraction time. Full source location breaks ties. Every incoming duplicate receives a suffix, including when the unsuffixed name is unused. Source-to-final-name mapping is reviewable before movement and recorded in execution results without changing the standalone listing versus move-dry-run inventory contract.
Inventory and filter semantics¶
Implemented report interpretation:
A filesystem image has its original filename, normalized extension as its type, and absolute filesystem path. Extension matching is not image-content validation.
An archive image has its filename, type, and an archive-qualified location such as
C:\Photos\holiday.zip :: day-1\IMG_001.JPG. It must not be represented as an already-existing extracted file.Counts distinguish on-disk images from archive entries, including nested ZIPs. Each archive’s count covers its direct selected entries; aggregate ZIP totals include nested matches. Source-folder impact counts physical parent directories.
A single extraction result is not counted twice as both an archive image and a new file in the same projected inventory. A file already on disk and a separate archived copy are separate occurrences; content deduplication is not requested.
Filter normalization removes whitespace, optional leading dots and repeated extensions after case normalization. Empty or unsupported entries are errors.
The report appends separated runs with JSON inventory rows and text counts/outcomes.
Image workflows use pictures.log, not a second report.log, and honor
--log-file/--no-log-file. FR-011 requires identical inventory semantics.
If projected extraction or destination paths are included, standalone listing
must retain the same inventory contract rather than claim those files exist.
Non-Functional Requirements¶
The following quality requirements are proposed engineering safeguards, not additional user-approved feature decisions.
Performance and Capacity¶
NFR-001: Listing ordinary ZIP entries shall not decompress image payloads or write extracted image files. Nested-archive inspection, if selected, shall have explicit depth and decompressed-byte limits. Implemented limits are ten archive levels including the outer ZIP, 100,000 aggregate entries, 64 MiB per nested ZIP and 256 MiB aggregate nested payload reads. Latency targets remain open in Q-015; no throughput claim is made.
Reliability and Resilience¶
NFR-002: For a failed transfer, the original source shall remain available unless a complete destination copy has been established in move mode; copy mode retains it even after successful transfer. Rejection, cancellation, and extraction failures shall never be reported as successful moves. Partial application is possible; automatic rollback is not promised (Q-012).
Security¶
NFR-003: A workflow shall not write outside its approved source/extraction/ destination/report scope through ZIP member paths, symlinks, or Windows junctions. Collision and archive-deletion effects shall be disclosed before approval. Link policy rejects links/junctions and existing extraction targets; no implicit merge or additional overwrite approval is supported.
Privacy¶
NFR-004: Inventory and file operations shall require zero network calls or uploads. Full paths are intentionally present in the local operator-requested report; image contents, credentials, and personal paths shall not be exported as service telemetry. Sharing and retaining the report remain the operator’s concern.
Scalability and Elasticity¶
No server, autoscaling, concurrency, or multi-user capacity target is in scope. Representative folder sizes and large/nested ZIP budgets must be agreed under Q-015 before performance acceptance.
Maintainability and Operability¶
NFR-005: CLI-selected and automatically required actions shall use one shared set of workflow rules. Each required stage appears once; the agent proposal shall not add a second execution engine or a dependency to this release.
Observability¶
NFR-006: The local report and console shall distinguish previews, approval outcomes, extraction outcomes, moved files, and failures. Report location and unreadable archives must remain visible. These are local user-facing reports, not a new telemetry service; no custom metric or span names, exporter, or SLO is specified.
Usability and Accessibility¶
NFR-007: Confirmation shall name the root, destination, selected extensions, image counts, affected source folders, and archive effects in text, without requiring color to understand approval. Empty input, EOF, or no terminal shall not implicitly authorize a move (Q-013).
Compatibility and Interoperability¶
NFR-008: Existing extraction/cleanup invocations and CLI-over-environment precedence shall retain their documented behavior unless a reviewed migration explicitly changes it. Default action selection, log overrides and error exit codes follow the resolution register below.
Portability¶
NFR-009: The feature shall remain usable through the existing Python CLI on Windows and Linux without an agent service; these are the only targeted operating systems. macOS is unsupported; an Apple host is not a development, installation, or release prerequisite. Absolute and relative path cases, mixed-case extensions, and cross-volume movement require acceptance on the targeted platforms. Raising the current Python 3.10 minimum is not proposed.
Constraints¶
ID |
Source / category |
Boundary and impact |
|---|---|---|
CON-001 |
User / technical scope |
Extend Archivist’s existing multi-step pipeline; do not create a competing standalone image utility |
CON-002 |
User / operational |
List and obtain human approval before extraction and movement in every move workflow |
CON-003 |
User / scope |
Agent Framework, AG-UI, model integration, and chat UI are future considerations only |
CON-004 |
User / delivery |
The subsequent explicit implementation request authorizes source, tests and related docs, not operations on actual user collections, releases or remote tracker writes |
CON-005 |
User / platform scope |
Support Windows and Linux only; macOS is unsupported and no Apple host is required for development, installation, CI, or release acceptance |
These boundaries can change only through an explicit product-scope revision.
Process Models¶
Move workflow¶
Validate inputs and resolve the proposed root, destination, and filter.
List on-disk and archived pictures; write the inventory and display its location.
If dry-run applies, stop here without requesting mutation approval.
Otherwise display the proposed effects and wait for human confirmation.
If approved, perform the required ZIP extraction stage, using source-preserving extraction outside the source tree for copy mode.
Reconcile available files with the approved selection, then move the selected pictures or duplicate them when
--copyis selected.Report actual outcomes, including incomplete extraction and movement.
Steps 2 -> 4 -> 5 -> 6 are the confirmed ordering. Validation, reconciliation, and failure policies are implemented safeguards. The workflow builder must not interpret the order of command-line flags as permission to reorder prerequisites.
Declining confirmation stops before any extraction or movement; the previously requested inventory log remains. If extraction finds additional candidates or changes the plan, they must not be silently added to the approved move scope. Nested inspection limits and incomplete-inventory errors prevent approval from claiming an unverified complete total.
Listing and other combinations¶
Standalone listing and move dry-run use the same inventory behavior. Selecting listing plus extraction in a dry-run still does not extract. For real listing-plus-extraction without movement, the user explicitly selected listing, approval, then extraction, preserving inventory provenance before ZIP disposal.
Cleanup inclusion is intentionally not inferred from --extract-zip or a move
request. Without explicit action flags, legacy extraction and cleanup remain.
Acceptance Criteria¶
The criteria are implemented and covered by focused filesystem/CLI fixtures in
tests/test_image_inventory.py and tests/test_image_workflow.py, alongside the
existing suite. Acceptance targets Windows and Linux; CI runs Windows and Ubuntu
jobs, and no macOS host or macOS acceptance run is required. Local Windows
execution is evidence for the implementation, not formal product approval or
cross-platform release acceptance. Link scenarios requiring unavailable host
symlink privileges are explicitly skipped; CI owns the remaining targeted
platform coverage.
ID |
Given / When / Then |
|---|---|
AC-001 |
Given a move request with listing and extraction also selected, when the workflow is prepared with any argument order, then each prerequisite appears once and listing precedes confirmation, extraction, and movement |
AC-002 |
Given a root containing |
AC-003 |
Given a ZIP in a subfolder containing |
AC-004 |
Given a writable report location and matching files, when listing completes, then |
AC-005 |
Given JPG, JPEG, PNG, ARW, and TXT files, when filtering with |
AC-006 |
Given a move request without explicit listing or extraction flags, when prepared, then the workflow includes listing, human confirmation, extraction, and movement in that order |
AC-007 |
Given a prepared move inventory, when approval is requested, then file count, extension breakdown, and affected source-folder count are displayed before extraction or movement; declining changes neither source nor destination contents |
AC-008 |
Given a root with an ordinary picture and a ZIP in a subfolder containing another selected picture, when the complete plan is approved and extraction succeeds, then no picture movement starts until extraction finishes and both selected pictures reach the destination |
AC-009 |
Given valid absolute and relative destinations under the approved resolution policy, when relocation succeeds, then each selected file has the same contents at its destination and is no longer at its original on-disk location |
AC-010 |
Given a parent tree and a destination that does not exist, when moving with |
AC-011 |
Given unchanged input files, the same root and filter, and the same report policy, when standalone listing and move dry-run are run, then their normalized inventory rows, counts, and report locations match |
AC-012 |
Given a malformed ZIP or a failed move, when reporting the run, then the failure is visible and neither an unknown archive count nor a failed move is represented as a successful zero-count/completed result |
AC-013 |
Given |
AC-014 |
Given a move after a successful extraction has added files, when the move selection is reconciled, then only files covered by the approved plan are moved; unexpected additions require a revised decision |
AC-015 |
Given an existing |
AC-016 |
Given |
AC-017 |
Given ordinary pictures and a disjoint destination, when |
AC-018 |
Given pictures inside source ZIPs, when copy mode with or without explicit |
AC-019 |
Given copy mode, when |
AC-020 |
Given destination-name collisions with known distinct original creation times, when copying after approval, then available numbered names are assigned oldest first exactly as for movement while source pictures remain unchanged |
AC-021 |
Given copy mode and an overlapping source/destination, a source-mutating action combination, or a report path targeting a source image/ZIP, when inputs are validated, then the run reports the conflict before any filesystem mutation |
AC-022 |
Given an ordinary EXIF-bearing image with distinct taken, creation and modification dates, when an approved move/copy succeeds, then the destination bytes and EXIF dates are unchanged and supported original filesystem dates match exactly |
AC-023 |
Given a picture inside a nested ZIP with original timestamps in NTFS or local extended Unix metadata, when extraction/transfer succeeds, then metadata survives temporary extraction and publication without substituting staging dates; missing creation remains explicitly unavailable |
AC-024 |
Given a known creation/modification date that the destination cannot represent or restore, when applying an image workflow, then it fails visibly before removing the affected source or original ZIP and does not report the affected transfer complete |
Counts and naming fixtures follow the settled policies in Q-005 through Q-016.
Traceability Matrix¶
Requirement |
Acceptance criteria |
Product goals |
|---|---|---|
FR-001 |
AC-001 |
GOAL-003 |
FR-002 |
AC-002 |
GOAL-001 |
FR-003 |
AC-003 |
GOAL-001 |
FR-004 |
AC-004 |
GOAL-001 |
FR-005 |
AC-005 |
GOAL-001 |
FR-006 |
AC-006 |
GOAL-003 |
FR-007 |
AC-007, AC-014 |
GOAL-002 |
FR-008 |
AC-008 |
GOAL-003 |
FR-009 |
AC-009 |
GOAL-003 |
FR-010 |
AC-010, AC-013 |
GOAL-002 |
FR-011 |
AC-011 |
GOAL-001, GOAL-002 |
FR-012 |
AC-012 |
GOAL-002 |
FR-013 |
AC-015, AC-016 |
GOAL-002, GOAL-003 |
FR-014 |
AC-017, AC-018, AC-019, AC-020, AC-021 |
GOAL-002, GOAL-003 |
FR-015 |
AC-022, AC-023, AC-024 |
GOAL-002, GOAL-003 |
FR-to-AC coverage: 15/15 (100%). FR-to-GOAL alignment: 15/15 (100%). These measure authored links, not passing tests or product approval. No feasibility-candidate disposition register applies because no handoff was supplied.
MVP and Release Framing¶
The CLI release targets FR-001 through FR-014, with NFR-001 through NFR-009 proposed for safety and operability review. It covers pictures, not a general catalog of audio, video, or document categories. Image conversion, content-based deduplication, rewriting ZIPs to remove individual members, and automatic rollback are not requested.
Delivery should first establish composable actions and ZIP-aware inventory, then add approved extraction-and-move execution. Listing can be reviewed without claiming movement is ready. Agent/AG-UI exploration is deferred to the companion future specification and must not delay or complicate CLI installation.
Engineering impact, not implementation mandates¶
The existing builder and step interfaces are a useful starting point. They currently pass a root path and return report counters; a dry-run extraction creates no files for the next stage to discover. Simply appending a filesystem listing after that step would miss archived pictures.
Existing surface |
Expected specification impact |
|---|---|
CLI parser and configuration |
Composable action flags, filter/destination validation, mode and environment precedence, help text |
Workflow builder and runner |
Prerequisites, stage ordering, approval boundary, inventory/results shared across relevant stages |
ZIP service |
Read-only image-member inventory distinct from extraction; preserve archive provenance and skipped outcomes |
Image services |
Classification, report generation, selection, conflict handling, and relocation |
Prompts and logging |
Aggregate approval before extraction; |
Documentation and existing acceptance coverage |
Command examples, pinned help text, step-order contracts, cross-platform and dry-run behavior |
Reuse existing layering rather than introducing a generic workflow framework. The precise data model and functions are engineering decisions, not product requirements. Direct ZIP entry inspection can reuse Python’s standard ZIP metadata support; no new image-decoding dependency is assumed.
Success Metrics¶
Goal |
Baseline |
Proposed first-release target |
Evidence window / source |
|---|---|---|---|
GOAL-001 |
No image inventory command |
100% exact matching occurrence counts on the agreed corpus |
Release acceptance: ordinary files, archive entries, filter and zero-match fixtures |
GOAL-002 |
Default preview exists; no image move workflow |
Zero unauthorized source/destination content changes |
Every dry-run, declined, and pre-approval fixture; compare file contents and directory entries excluding the report |
GOAL-003 |
Fixed extraction-first workflow |
100% supported move/copy combinations follow the approved stage order |
Release acceptance: explicit/implicit prerequisites and argument permutations |
No adoption baseline, user time-savings estimate, throughput target, or remote telemetry instrumentation is available. Product and engineering owners must approve the corpus, targets, and measurement responsibility before release sign-off.
Risks and Assumptions¶
Key assumptions¶
Assumption |
Impact if false |
Response |
|---|---|---|
Extension-based classification meets the need |
Medium: mislabeled files will be included or missed |
Document extension semantics and supported catalog; no content detection is claimed |
Selecting an extraction stage extracts the whole archive |
High: non-image files may also be created |
Disclose complete extraction in the approval summary |
The inventory captures everything a subsequent move may affect |
High: nested archives, changes, or conflicts can invalidate approval |
Bound inspection and reconcile against the approved selection |
Existing CLI users expect current defaults |
High: a new action model could change destructive behavior |
Preserve and regression-test explicit-versus-legacy selection |
Risk register¶
Likelihood has not been assessed; impact is an engineering assessment.
Risk |
Impact |
Proposed mitigation |
|---|---|---|
Default extractor deletes ZIPs after approval described only as a move |
High |
Explicit ZIP-retention decision and effects in the approval summary |
Flattened destination produces duplicate filenames |
High |
Preflight numbered renaming by creation date; resolve metadata gaps and ties |
Dry-run misses nested ZIP images or promises extraction that will be skipped |
High |
Report inspection limits and projected versus available files honestly |
Cross-volume copy fails or the process is interrupted |
High |
Preserve sources until transfer completes; record partial outcomes |
Files change after inventory or a linked path escapes the root |
High |
Validate approved scope again at execution; stop or request renewed approval |
Archived copies and extracted outputs inflate counts |
Medium |
Separate occurrence inventory, provenance, and actual moved totals |
Decision resolutions and remaining release question¶
Implementation resolutions below retain the original question identifiers. Material policy choices were explicitly confirmed by the user; compatibility and defensive engineering details are recorded as implemented decisions. Q-015 retains release/performance work, not an unresolved CLI behavior choice.
ID |
Topic |
Resolution or remaining work |
|---|---|---|
Q-001 |
Image/picture aliases |
Resolved: both vocabularies; shared |
Q-002 |
Defaults and cleanup |
Resolved: preserve no-action legacy behavior; explicit actions have no implicit cleanup |
Q-003 |
Apply and approval |
Resolved: preview by default, |
Q-004 |
Catalog/filter/extraction |
Resolved: catalog in Usage, extension-based matching, normalized validated filters; complete archive extraction |
Q-005 |
Source-folder counts |
Resolved: distinct physical parent directories; archive-qualified locations and direct per-archive image counts |
Q-006 |
Layout and extraction conflicts |
User confirmed flat destinations; existing extraction folders are rejected without merging |
Q-007 |
ZIP retention |
User confirmed deletion only after full extraction and successful transfer; |
Q-008 |
Destination resolution |
Resolved: process cwd, apply-only requirement, no preview destination creation |
Q-009 |
Overlap, links and metadata |
Resolved: disjoint roots, reject path links/junctions, skip filesystem links and known AppleDouble/ |
Q-010 |
Nested ZIP limits |
User confirmed bounded recursion; implemented limits in NFR-001 and Usage; unsafe/encrypted/unsupported members block application |
Q-011 |
Reports |
User confirmed appended separated runs; JSON rows, logging overrides, no second report, mappings shown only for the applying approval plan |
Q-012 |
Failure behavior |
User confirmed stop/retain/report partial work; nonzero image-workflow status, no rollback; legacy exit behavior unchanged |
Q-013 |
Approval input |
Resolved: only yes/y; blank, EOF or no terminal declines; no auto-approval/timeout or merge prompt |
Q-014 |
List plus extraction |
User confirmed list, ask for approval, then extract; standalone extraction preserves legacy behavior without cleanup |
Q-015 |
Release/performance evidence |
Open: representative corpus, latency/throughput targets, delivery date, owners and approvers; implemented resource limits do not establish these claims |
Q-016 |
Timestamp and collision allocation |
User confirmed reported original-mtime fallback, full-source-path ties and numbering every incoming collision |
Q-017 |
Copy modifier |
Resolved: requires transfer action; |
Glossary¶
Term |
Meaning |
|---|---|
Picture / image |
The same file category with interchangeable image/picture flag aliases |
Image type |
Normalized extension label, not verified MIME/content classification |
Archive entry |
A member inside a ZIP, not necessarily an existing filesystem file |
Nested ZIP |
A ZIP member inside another ZIP; different from a ZIP stored in an ordinary subfolder |
Inventory |
Observed matching occurrences with source locations and counts |
Plan |
Proposed effects and destinations awaiting approval, distinct from actual outcomes |
Move |
Relocate an on-disk file without converting it; not rewriting a ZIP to remove a member |
Dry-run |
Inspect/report only; the requested local log is the allowed write exception |
Sign-Off¶
This product specification remains draft. The requesting user approved the business baseline in BRD-2026-Q3-001 and its W-001 measurement waiver, then authorized implementation and selected the material policies above. This is not formal PRD or release approval. Acceptance owners, delivery estimate and the representative performance corpus remain unassigned.
Implementation is present with local regression coverage. Formal PRD quality review, cross-platform release acceptance and final approval remain separate gates. No backlog upload or tracker mutation is requested.
Disclaimer¶
This AI-assisted draft supports product and engineering review. It does not constitute product approval, requirements sign-off, or engineering commitment.
Document Metadata¶
Source: Archivist product conversation, September 28, 2026.
Baseline: repository revision
42666b2; legacy behavior is preserved while explicit image workflows are added.Structure adapted from the Microsoft HVE-Core
requirements-author/templates/prd/prd-full.mdtemplate, version 1.0.0, under CC BY 4.0.Future scope: Conversational agent and AG-UI.