gallery-organizer-web/.specify/memory/constitution.md

Gallery Archive Curator Constitution

Core Principles

I. Safety Over Convenience (NON-NEGOTIABLE)

All behavior MUST prioritize data preservation over speed or convenience. Whitelisted user directories MUST never be deletable by any directory-level action. Any destructive operation MUST be previewed, explicitly confirmed, and audited. A global read-only mode MUST exist and fully disable mutations. Rationale: irreversible loss is unacceptable.

II. Explicit, Deterministic Behavior

All behavior MUST be explicit, deterministic, and reproducible under the same configuration. The system MUST refuse to operate outside configured root paths and MUST NOT follow symlinks for destructive actions (only the link itself may be removed). Rationale: predictable, bounded behavior prevents accidental loss.

III. Previewed, Confirmed, Reversible Deletion

Deletion MUST be a process, not a single action. The default MUST be two-stage deletion (move to trash/staging first), with permanent deletion only by explicit configuration and confirmation. All deletion behavior MUST remain reversible until explicitly finalized. Rationale: human review requires a safety buffer.

IV. Traceability and Auditability

Every mutation MUST produce a durable, append-only audit record with timestamp, action type, affected paths, list-file changes (if any), and outcome. The UI MUST expose recent audit activity. Rationale: accountability and recovery depend on traceable history.

V. Human-Driven Workflow Clarity

The UI MUST always display the current state of each user directory and support fast, intentional review flows. Required workflows (whitelisted media triage and untagged decisioning) MUST surface essential context (owner, size, type, relative path) and support random and size-prioritized review. Rationale: clear human intent drives safe decisions.

Mission, Scope, and Conceptual Model

Mission

Provide a safe, human-driven system for curating large archives of downloaded media where each directory represents a single user, enabling disk-space recovery while making accidental data loss extremely difficult.

Scope (In/Out)

In scope: manual curation, clear confirmation flows, auditing, and reversible deletion. Out of scope: automatic or unattended deletion, machine-learning-based decisions, silent bulk operations, cloud dependencies, or tight coupling to the scraper.

Conceptual Model

• A user directory is a folder containing media scraped from a single user.
• Each user directory exists in exactly one state: Untagged, Whitelisted, Blacklisted, or Kept.
• The system MUST maintain a single, explicit source of truth for these states.
• The current state of any user directory MUST always be visible in the UI.

Operational Safety, Workflows, and Data Integrity

Absolute Safety Rules (Non-Negotiable)

• Whitelisted directories MUST never be deletable by any directory-level action.
• No destructive operation may occur without: (1) dry-run preview, (2) explicit confirmation, and (3) persistent audit record.
• All filesystem operations MUST refuse to act outside configured root paths.
• A global read-only mode MUST exist and disable all mutations while allowing browsing.
• Destructive operations MUST be single-writer only and MUST NOT run concurrently.
• Symlinks MUST never be followed for destructive actions; only the link itself may be removed.

Deletion Philosophy

• Deletion is a process, not a single action.
• Default behavior MUST be two-stage deletion: move to trash/staging first.
• Permanent deletion MUST require explicit configuration and confirmation.
• Hard deletion MUST never be the silent default.
• All deletion behavior MUST be reversible until explicitly finalized.

Required User Workflows

Mode 1 — Whitelisted Media Triage

• Purpose: reclaim space without risking loss of important users.
• Only individual media files may be deleted; the parent directory MUST remain protected at all times.
• Media is shown one item at a time for rapid decision-making.
• Each item MUST display: owning user, file size, media type, and relative path.
• Ordering MUST support random review and size-prioritized review.

Mode 2 — Untagged Directory Decision

• Purpose: decide whether an entire user is worth keeping.
• A directory is reviewed via a collage of randomly sampled files.
• The sample MUST be refreshable without changing directories.
• Decisions:
  • Keep: directory is moved or marked as preserved and removed from the untagged pool.
  • Delete: directory is removed only after explicit confirmation and preview.
• When deleting a directory, the system MUST attempt to locate and optionally remove the user from a plain-text download list file.
• List-file edits MUST be previewed and optional; directory deletion MUST NOT depend on list-file presence.

Download List File Integrity

• The download list file is a critical control surface.
• Removal rules MUST be explicit and conservative; default is exact-match removal only.
• All edits MUST be previewed and performed atomically.
• If no matching entry is found, the system MUST clearly state this and proceed safely.

Auditing and Accountability

• Every mutation MUST produce a durable, append-only audit record.
• Audit records MUST include: timestamp, action type, affected paths, list-file changes (if any), and outcome.
• Audit logs are core data and MUST never be optional.
• The UI MUST expose recent audit activity for verification.

Configuration and Boundaries

• All operational paths (pools, whitelist, trash, list file) MUST be explicitly configured.
• The system MUST refuse to operate with ambiguous or overlapping roots.
• Behavior MUST be deterministic under the same configuration.
• Configuration changes MUST NOT retroactively invalidate safety guarantees.

Documentation Persistence Rule

Any of the following requires immediate documentation updates:

• Bug fixes affecting behavior or safety
• Edge cases discovered in real data
• Changes in deletion, confirmation, or matching rules
• Changes in directory state handling
• Changes in list-file identity logic Documentation updates MUST include: what changed, why it changed, and how it affects existing behavior. Undocumented behavior is a defect.

Definition of Done

The project is compliant when:

• Whitelisted users are provably protected at the code level.
• All destructive actions are previewed, confirmed, and audited.
• Users can curate large archives without fear of silent loss.
• System behavior remains understandable months later through documentation.

Governance

This constitution is authoritative and supersedes all other practices. All changes MUST explicitly verify compliance with the Core Principles and Operational Safety rules.

Amendment Procedure

• Any amendment MUST update this document, include rationale, and record the impact in the Sync Impact Report.
• Any change affecting filesystem mutations, deletion workflows, or list-file rules MUST include a migration or safety review plan.
• Compliance review is required for every change that touches destructive operations or state handling.

Versioning Policy (Semantic)

• MAJOR: backward-incompatible governance/principle removals or redefinitions.
• MINOR: new principle/section added or materially expanded guidance.
• PATCH: clarifications, wording fixes, or non-semantic refinements.

Compliance Expectations

• All plans and specs MUST include a constitution check before implementation.
• Any deviation requires explicit justification and documented alternatives.

Version: 1.0.0 | Ratified: TODO(RATIFICATION_DATE): original adoption date not found | Last Amended: 2026-02-07