|
|
|
|
@@ -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
|
|
|
|
|
|
Danilo Reyes