init

.specify/memory/constitution.md

@@ -1,50 +1,168 @@
-# [PROJECT_NAME] Constitution
-<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+<!--
+Sync Impact Report
+Version change: N/A (template) -> 1.0.0
+Modified principles: N/A (initial adoption)
+Added sections: Mission & Scope; Conceptual Model; Absolute Safety Rules; Deletion Philosophy;
+Required User Workflows; Download List File Integrity; Auditing & Accountability;
+Configuration & Boundaries; Documentation Persistence; Definition of Done; Out of Scope
+Removed sections: N/A
+Templates requiring updates:
+- ✅ updated: .specify/templates/plan-template.md
+- ✅ updated: .specify/templates/spec-template.md
+- ✅ updated: .specify/templates/tasks-template.md
+- ⚠️ pending: .specify/templates/commands/*.md (no files found)
+Follow-up TODOs:
+- TODO(RATIFICATION_DATE): original adoption date not found
+-->
+# Gallery Archive Curator Constitution
 
 ## Core Principles
 
-### [PRINCIPLE_1_NAME]
-<!-- Example: I. Library-First -->
-[PRINCIPLE_1_DESCRIPTION]
-<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+### 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.
 
-### [PRINCIPLE_2_NAME]
-<!-- Example: II. CLI Interface -->
-[PRINCIPLE_2_DESCRIPTION]
-<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+### 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.
 
-### [PRINCIPLE_3_NAME]
-<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
-[PRINCIPLE_3_DESCRIPTION]
-<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+### 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.
 
-### [PRINCIPLE_4_NAME]
-<!-- Example: IV. Integration Testing -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+### 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.
 
-### [PRINCIPLE_5_NAME]
-<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
-[PRINCIPLE_5_DESCRIPTION]
-<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+### 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.
 
-## [SECTION_2_NAME]
-<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+## Mission, Scope, and Conceptual Model
 
-[SECTION_2_CONTENT]
-<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+### 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.
 
-## [SECTION_3_NAME]
-<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+### 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.
 
-[SECTION_3_CONTENT]
-<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+### 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
-<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+This constitution is authoritative and supersedes all other practices. All changes MUST
+explicitly verify compliance with the Core Principles and Operational Safety rules.
 
-[GOVERNANCE_RULES]
-<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+**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.
 
-**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+**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