diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..9045be3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,90 @@ +--- +name: Bug Report +about: Report a bug or issue in ProSe +title: "[BUG] " +labels: bug +assignees: "" +--- + +## πŸ› Bug Description + +A clear and concise description of what the bug is. + +> Example: "Evidence validator crashes when timeline.csv is missing the Evidence_IDs column." + +--- + +## πŸ“‚ Area Affected + +Which part of the system is impacted? + +- [ ] Engine / core +- [ ] Agents (e.g. evidence validator, timeline builder) +- [ ] file_organizer / PSFO tools +- [ ] Tests +- [ ] Docs +- [ ] Other (describe): + +--- + +## πŸ“‹ Steps to Reproduce + +1. Go to "..." +2. Run command / action: `...` +3. Using data / sample files: `...` +4. See error: `...` + +> Include exact commands if possible. + +--- + +## βœ… Expected Behavior + +What you **expected** to happen. + +--- + +## ❌ Actual Behavior + +What **actually** happened. + +- Error messages (copy/paste if possible): +- Did it crash, hang, or produce wrong output? + +--- + +## πŸ–ΌοΈ Screenshots (Optional) + +If applicable, add screenshots or logs to help explain the problem. + +> ⚠️ **Do not** include real case documents, real names, or unredacted legal files. + +--- + +## 🌍 Environment + +- OS: [e.g. ChromeOS (Linux container), Windows, macOS] +- Python version: [e.g. 3.11] +- ProSe version / branch: [e.g. `main`, `feature/prose-evidence-index-schema`] +- How you ran it: + - [ ] `python -m ...` + - [ ] VS Code terminal + - [ ] Other (describe): + +--- + +## πŸ“ Additional Context + +Add any other context about the problem here. + +- Related PRs or branches: +- Donor repo involved (if any): `ProSe_Agent2`, `ProSe-File-Organizer`, etc. + +--- + +## βœ”οΈ Before Submitting + +- [ ] I’ve searched existing issues to avoid duplicates +- [ ] I’ve provided clear steps to reproduce +- [ ] I’ve **not** attached real case data, legal documents, or unredacted evidence +- [ ] I’ve included relevant environment details diff --git a/.github/ISSUE_TEMPLATE/cleanup_request.md b/.github/ISSUE_TEMPLATE/cleanup_request.md new file mode 100644 index 0000000..666a609 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/cleanup_request.md @@ -0,0 +1,59 @@ +--- +name: Cleanup Request +about: Report clutter, unused code, or organization issues +title: "[CLEANUP] " +labels: cleanup, maintenance +assignees: "" +--- + +## 🧹 Cleanup Description + +What needs to be cleaned up or reorganized? + +--- + +## πŸ“ Location + +Where in the repository is the issue? + +- Path(s): +- Files/directories affected: + +--- + +## πŸ” Issue Type + +- [ ] Backup files (*.bak, *.old, etc.) +- [ ] Temporary files +- [ ] Unused/dead code +- [ ] Disorganized structure +- [ ] Outdated documentation +- [ ] Other (describe below) + +--- + +## πŸ’‘ Suggested Action + +How should this be addressed? + +--- + +## πŸ“Š Impact + +- [ ] Low - Minor cleanup +- [ ] Medium - Affects repository organization +- [ ] High - Significant clutter or disorganization + +--- + +## πŸ“ Additional Details + +Any other information about the cleanup needed. + +--- + +## βœ”οΈ Before Submitting + +- [ ] I've verified this is actually clutter/needs cleanup +- [ ] I've provided specific location information +- [ ] I've suggested how to address it diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..935bace --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,49 @@ +--- +name: Feature Request +about: Suggest a new feature or enhancement +title: "[FEATURE] " +labels: enhancement +assignees: "" +--- + +## πŸš€ Feature Description + +A clear and concise description of the feature you'd like to see. + +--- + +## 🎯 Problem/Motivation + +What problem does this feature solve? Why is it needed? + +--- + +## πŸ’‘ Proposed Solution + +How would you like this feature to work? + +--- + +## πŸ”„ Alternatives Considered + +Have you considered any alternative solutions or features? + +--- + +## πŸ“Š Impact + +Who will benefit from this feature? How will it improve the project? + +--- + +## πŸ“ Additional Context + +Add any other context, mockups, or examples about the feature request. + +--- + +## βœ”οΈ Before Submitting + +- [ ] I've searched existing issues to avoid duplicates +- [ ] This feature aligns with the project's goals +- [ ] I've clearly described the problem and solution diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..cf52653 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,113 @@ +# πŸ“‹ Pull Request Description + +## What does this PR do? + + +## Why is this change needed? + + +## Related Issues + + +--- + +# πŸ§ͺ Testing + +## How has this been tested? + + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing completed +- [ ] All tests pass + +### Test Coverage + + +--- + +# 🧹 Cleanliness Checklist + +**CRITICAL**: Ensure your PR maintains repository cleanliness standards + +- [ ] **No backup files** (*.bak, *.old, *.backup, etc.) +- [ ] **No temporary files** (*.tmp, temp/, tmp/) +- [ ] **No commented-out code** (delete, don't comment) +- [ ] **No debug statements** (console.log, print, etc.) +- [ ] **No unused imports** or variables +- [ ] **No personal IDE configs** (.vscode/, .idea/, etc.) +- [ ] **No build artifacts** (dist/, build/, compiled files) +- [ ] **No sensitive data** (keys, tokens, passwords) +- [ ] **All files in correct directories** (engine/, tests/, docs/, scripts/, etc.) + +--- + +# πŸ“ Code Quality Checklist + +- [ ] Code follows project style guidelines +- [ ] Functions/methods are documented +- [ ] Complex logic has explanatory comments +- [ ] Error handling is appropriate +- [ ] Code is DRY (Don't Repeat Yourself) + +--- + +# πŸ“š Documentation + +- [ ] README updated (if needed) +- [ ] Documentation added/updated for new features +- [ ] Examples added/updated (if applicable) +- [ ] CHANGELOG updated (if applicable) + +--- + +# πŸ” Review Checklist + +Before requesting review, ensure: + +- [ ] Self-reviewed all changes +- [ ] Commit messages are clear and descriptive +- [ ] Branch is up to date with main +- [ ] No merge conflicts +- [ ] CI/CD checks pass (if applicable) + +--- + +# πŸ“Š Impact Assessment + +### Breaking Changes + +- [ ] This PR includes breaking changes +- [ ] Migration guide provided (if breaking changes) + +### Performance Impact + + + +### Security Considerations + + + +--- + +# πŸ“Έ Screenshots/Recordings + + + +--- + +# πŸ’¬ Additional Notes + + + +--- + +## βœ… Final Confirmation + +By submitting this PR, I confirm that: + +- [ ] I have read and followed the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] I have read and accept the [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) +- [ ] My code is clean, tested, and ready for review +- [ ] I have removed all clutter, backup, and temporary files +- [ ] This PR maintains the high standards of the ProSe repository diff --git a/.github/workflows/repo_clean.yml b/.github/workflows/repo_clean.yml new file mode 100644 index 0000000..a787a7d --- /dev/null +++ b/.github/workflows/repo_clean.yml @@ -0,0 +1,97 @@ +name: Repository Cleanliness Check + +on: + pull_request: + branches: [ main ] + push: + branches: [ main ] + workflow_dispatch: + +jobs: + cleanliness-check: + runs-on: ubuntu-latest + name: Check for Clutter and Repository Health + + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Check for backup files + run: | + echo "πŸ” Checking for backup files..." + BACKUP_FILES=$(find . -type f \( -name "*.bak" -o -name "*.old" -o -name "*.backup" -o -name "*~" \) ! -path "./.git/*" || true) + if [ -n "$BACKUP_FILES" ]; then + echo "❌ Found backup files:" + echo "$BACKUP_FILES" + exit 1 + else + echo "βœ… No backup files found" + fi + + - name: Check for temporary files + run: | + echo "πŸ” Checking for temporary files..." + TEMP_FILES=$(find . -type f \( -name "*.tmp" -o -name "*.temp" \) ! -path "./.git/*" || true) + if [ -n "$TEMP_FILES" ]; then + echo "❌ Found temporary files:" + echo "$TEMP_FILES" + exit 1 + else + echo "βœ… No temporary files found" + fi + + - name: Check for OS-generated files + run: | + echo "πŸ” Checking for OS-generated files..." + OS_FILES=$(find . -type f \( -name ".DS_Store" -o -name "Thumbs.db" -o -name "desktop.ini" \) ! -path "./.git/*" || true) + if [ -n "$OS_FILES" ]; then + echo "❌ Found OS-generated files:" + echo "$OS_FILES" + exit 1 + else + echo "βœ… No OS-generated files found" + fi + + - name: Check for backup directories + run: | + echo "πŸ” Checking for backup directories..." + BACKUP_DIRS=$(find . -type d \( -name "backup" -o -name "backups" -o -name "old" -o -name "_old" \) ! -path "./.git/*" || true) + if [ -n "$BACKUP_DIRS" ]; then + echo "❌ Found backup directories:" + echo "$BACKUP_DIRS" + exit 1 + else + echo "βœ… No backup directories found" + fi + + - name: Check for IDE configuration directories + run: | + echo "πŸ” Checking for IDE configuration directories..." + IDE_CONFIGS=$(find . -type d \( -name ".vscode" -o -name ".idea" \) ! -path "./.git/*" || true) + if [ -n "$IDE_CONFIGS" ]; then + echo "⚠️ Warning: Found IDE configuration directories:" + echo "$IDE_CONFIGS" + echo "These should typically be in .gitignore and not committed." + else + echo "βœ… No IDE configuration directories found" + fi + + - name: Check for essential files + run: | + echo "πŸ“ Checking for essential files..." + REQUIRED_FILES=("README.md" "CONTRIBUTING.md" "CODE_OF_CONDUCT.md" ".gitignore") + for file in "${REQUIRED_FILES[@]}"; do + if [ ! -f "$file" ]; then + echo "❌ Missing required file: $file" + exit 1 + else + echo "βœ… Found $file" + fi + done + + - name: Summary + run: | + echo "" + echo "=================================" + echo "βœ… Repository cleanliness check complete!" + echo "=================================" diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1d9f8b0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## [0.1.0] - Initial Clean Hub Setup + +- Added GitHub issue templates (bug, feature, cleanup) +- Added Pull Request template with cleanliness checklist +- Added repository cleanliness GitHub Actions workflow +- Added `README.md` with project philosophy and structure +- Added `CONTRIBUTING.md` with strict cleanliness rules +- Added `CODE_OF_CONDUCT.md` focused on repository standards +- Initialized `CHANGELOG.md` +- Established core directory structure (engine/, file_organizer/, case/, docs/, tests/, scripts/) +- Adopted MIT License diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9d7bf29 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,131 @@ +# Code of Conduct - ProSe Repository Standards + +## Our Pledge + +We are committed to maintaining a professional, clean, and well-organized repository that serves as an example of best practices in software development. + +This Code of Conduct focuses on **repository standards and cleanliness**, not social interaction (for that you can also adopt a standard community CoC if needed). + +--- + +## Repository Standards + +### Cleanliness Standards + +1. **No Clutter** + The repository must remain free of: + - Backup files (`*.bak`, `*.old`, `*.backup`) + - Temporary files (`*.tmp`, `temp/`, `tmp/`) + - Unused code or commented-out blocks + - Old versions of files + - Experimental code that isn't production-ready + +2. **Organization** + All files must be in their proper locations: + - Core engine code in `engine/` + - File tools in `file_organizer/` + - Tests in `tests/` + - Documentation in `docs/` + - Scripts in `scripts/` + - Examples in `examples/` + +3. **Quality Over Quantity** + - Every line of code should have a purpose + - Remove dead code immediately + - Don't keep "just in case" files + - Use git history for old versions + +--- + +## Contribution Standards + +1. **Clean Commits** + - Clear, descriptive commit messages + - Atomic commits (one logical change per commit) + - No commits containing backup or temp files + +2. **Code Quality** + - Follow existing code style + - Include tests for new features + - Document public APIs + - Remove debug statements before committing + +3. **Pull Request Quality** + - Self-review your code before submitting + - Ensure all tests pass + - Update documentation + - Keep commit history clean + +--- + +## Enforcement + +### Review Process + +All contributions will be reviewed for: + +- βœ… Code quality and functionality +- βœ… Adherence to cleanliness standards +- βœ… Proper documentation +- βœ… Test coverage +- βœ… Absence of clutter files + +### Violations + +Contributions that violate these standards will be: + +1. **First offense**: Requested to clean up and resubmit +2. **Repeated offenses**: May result in rejected PRs +3. **Severe violations**: Immediate rejection (e.g., committing sensitive data) + +--- + +## Maintenance Responsibilities + +### For Contributors + +- Clean up your workspace before committing +- Use `.gitignore` appropriately +- Remove files you don't intend to commit +- Ask if unsure about including a file + +### For Maintainers + +- Conduct thorough reviews +- Maintain `.gitignore` +- Keep documentation updated +- Perform periodic cleanup audits +- Lead by example + +--- + +## Periodic Cleanup + +The repository undergoes regular maintenance: + +- **Weekly**: Review for stray files +- **Monthly**: Documentation updates +- **Quarterly**: Dependency updates +- **Annually**: Major refactoring if needed + +--- + +## Reporting Issues + +If you notice clutter or organization issues: + +1. Create an issue with the `cleanup` label +2. Describe what needs attention +3. Suggest improvements if applicable + +--- + +## Attribution + +These standards exist to ensure ProSe remains a professional, maintainable repository that serves as a reliable foundation for integration with other projects. + +--- + +**Version**: 1.0 +**Last Updated**: November 2025 +**Maintainer**: ProSe Team diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1555436 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,234 @@ +# Contributing to ProSe + +Thank you for contributing to ProSe! This repository is the **clean hub** that pulls in proven pieces from other projects (like ProSe Agent 2 and ProSe File Organizer) and leaves the chaos behind. + +The goal: a repo that’s safe to clone, easy to understand, and doesn’t ship someone’s backups or live case files. + +--- + +## 🎯 Repository Philosophy + +ProSe is the **mainline repo**. Other projects are **donors**. + +- ProSe_Agent2 and ProSe File Organizer are where experiments and one-off scripts can live. +- This repo only receives **clean, intentional imports** from those donors. +- Live case data (real divorce/custody files) must **never** be committed here. + +Think of this repo as the *cathedral*, not the workshop. + +--- + +## πŸ“‹ Before You Contribute + +### ❌ What NOT to include + +Do **not** commit: + +- Backup files (`*.bak`, `*.old`, `*.backup`, timestamps in file names, etc.) +- Temporary files (`*.tmp`, `tmp/`, `temp/`, scratch scripts) +- Unused or dead code + > If it’s not used, delete it. Git history is the archive. +- Old versions of files (e.g., `file_v2_final_final.py`) +- Build artifacts (`dist/`, `build/`, compiled binaries) +- Dependency folders (`node_modules/`, `.venv/`, `venv/`, etc.) +- IDE/editor configs (`.vscode/`, `.idea/`, `.history/`) +- Personal notes, brain-dumps, or TODO text files + > Use Issues or PR descriptions instead. +- Experimental or half-baked features + > Put those on a feature branch or in a donor repo, not `main`. + +--- + +### 🚫 ABSOLUTE HARD LINE + +- **No live case data.** + Do **not** commit any real legal documents, evidence, or personal data. + - No PDFs from actual cases + - No screenshots with names, addresses, or children + - No exported timelines with real dates/parties + +If you need sample data, use redacted or synthetic examples under `examples/`. + +--- + +### βœ… What TO include + +- Clean, production-ready code +- Migrations or refactors that remove complexity or duplication +- Relevant tests for any new behavior +- Documentation for new features or public APIs +- Updates to `README.md` or `docs/` for major features +- Clear commit messages explaining **what** and **why** + +--- + +## πŸ”„ Contribution Workflow + +1. **Fork and clone** the repository. + +2. **Create a feature branch** from `main`: + ```bash + git checkout -b feature/your-feature-name + ``` + +3. **Make your changes, keeping donors in mind**: + If you’re copying from ProSe_Agent2 or PSFO, clean it first. + Strip out debug code, hardcoded paths, and case-specific assumptions. + +4. **Test your changes thoroughly.** + +5. **Clean up before committing**: + ```bash + # Remove common junk files + find . -name "*.bak" -delete + find . -name "*.tmp" -delete + find . -name "*~" -delete + ``` + +6. **Commit with clear messages**: + ```bash + git add . + git commit -m "feat: add timeline summarizer endpoint" + ``` + +7. **Push and open a Pull Request** against `main`. + +--- + +## πŸ“ Pull Request Guidelines + +### PR Title Format (Conventional Commits) + +- `feat:` – New feature +- `fix:` – Bug fix +- `docs:` – Documentation change +- `refactor:` – Code refactoring (no behavior change) +- `test:` – Adding or updating tests +- `chore:` – Maintenance / tooling + +**Examples:** +- `feat: add affidavit generation API` +- `fix: handle missing timestamps in timeline parser` +- `refactor: extract drive sync client` + +--- + +### PR Description Should Include + +- What you changed +- Why you changed it (problem/motivation) +- How to test it +- Any related issues or design docs + +--- + +### Before Submitting a PR + +- [ ] Code is clean and follows project style +- [ ] No backup, temp, or junk files +- [ ] All tests pass (pytest, python -m unittest, etc.) +- [ ] Documentation updated +- [ ] Commit history clean (squash if needed) +- [ ] No secrets or personal data (keys, tokens, real names, etc.) + +--- + +## 🧹 Code Cleanup Checklist + +Before you commit: + +1. **No commented-out code** + If you don’t need it, delete it. Git remembers. + +2. **No debug prints/log spam** + - Remove `print()` used for debugging + - Use proper logging levels + +3. **No unused imports** + Clean up imports detected by your linter/IDE. + +4. **No copy-paste duplication** + Extract helpers for repeated logic. + +5. **No TODOs as comments** + File an Issue instead and link it in your PR if needed. + +6. **Consistent formatting** + Use the project’s formatter (e.g. black, isort, ruff, prettier). + +--- + +## πŸ—οΈ Project Structure + +ProSe is trending toward this layout: + +```text +ProSe/ +β”œβ”€β”€ engine/ # Core orchestration (from ProSe_Agent2) +β”‚ β”œβ”€β”€ core/ # engine.py, orchestrator, process wiring +β”‚ └── agents/ # FileAgent, SyncAgent, TimelineAgent, etc. +β”œβ”€β”€ file_organizer/ # Tools imported from PSFO (cleaned) +β”œβ”€β”€ case/ # Local-only examples (never real case data) +β”‚ β”œβ”€β”€ DivorceFiles/ # Example input +β”‚ └── Generated/ # Example outputs +β”œβ”€β”€ docs/ # Documentation, specs, architecture +β”œβ”€β”€ tests/ # Automated tests +β”œβ”€β”€ scripts/ # Utility scripts (no hardcoded paths) +└── README.md # Project overview +``` + +> Note: Real case folders should live outside the git repo in a user’s filesystem. +This `case/` tree is for structure & examples only. + +--- + +## πŸ” Code Review Process + +Reviewers will look for: +- Code quality and adherence to these guidelines +- No clutter (backups, artifacts, temp files) +- Proper tests for new logic +- Clear documentation or inline comments where needed +- Clean, understandable commit history +- Respect for privacy and data boundaries + +PRs that mix huge refactors with new features are harder to review. Try to keep changes scoped. + +--- + +## 🚫 What Will Be Rejected + +PRs may be rejected or asked to rework if they: +- Include backup, temp, or experimental junk +- Contain large binaries without strong justification +- Include real personal or legal data +- Break existing functionality or tests +- Ignore contribution guidelines +- Contain credentials, API keys, or secrets + +--- + +## πŸ’‘ Best Practices + +1. **Keep it boring.** Simple, obvious code is future-proof. +2. **Write tests as you go.** Don’t leave testing for β€œlater.” +3. **Document behavior, not just functions.** Why matters as much as what. +4. **Commit in small pieces.** Easier to review, easier to revert. +5. **Clean before pushing.** `git diff` is your friend. Scan it before each commit. +6. **Ask questions early.** Open an Issue if something feels unclear or architectural. + +--- + +## πŸ“ž Getting Help + +- Open an Issue for questions or design discussions. +- Tag maintainers in PRs that touch core engine or agents. +- Check existing Issues/PRs before starting big changes. + +--- + +## πŸ™ Thank You + +Your contributions help ProSe stay clean, professional, and usable for real people in real legal stress. + +**A clean repo is a calm brain. πŸŽ‰** diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..768e9c2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the β€œSoftware”), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED β€œAS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/README.md b/README.md index eed3129..c652dc5 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,178 @@ # ProSe -the main module for Prose' litagints + +**The Main Module for Pro Se Litigants** + +[![Code Quality](https://img.shields.io/badge/code%20quality-clean-brightgreen)]() +[![Maintenance](https://img.shields.io/badge/maintained-yes-green)]() +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)]() +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)]() + +ProSe is a clean, well-organized main repository designed to receive and integrate contributions from multiple source repositories while maintaining the highest standards of code quality and organization. + +--- + +## πŸ’‘ Why ProSe Exists + +Self-represented litigants are already overloaded. Their files shouldn’t be. +ProSe gives a structured, clean, and predictable home for the automation, agents, and tools that support real-world divorce and custody cases, without ever dragging live case data into the repo. + +This is the **cathedral**, not the workshop. + +--- + +## 🎯 Project Goals + +- **Maintain Cleanliness**: Zero tolerance for backup files, temporary files, and clutter +- **Organized Structure**: Everything in its proper place +- **Quality Code**: No unused code, no commented-out blocks, no debug statements +- **Easy Integration**: Seamless integration from donor repositories +- **Long-term Maintainability**: Built to last without accumulating technical debt + +--- + +## πŸ“ Repository Structure + +```text +ProSe/ +β”œβ”€β”€ .github/ # GitHub templates and workflows +β”‚ β”œβ”€β”€ ISSUE_TEMPLATE/ # Issue templates (bug, feature, cleanup) +β”‚ └── PULL_REQUEST_TEMPLATE.md # PR template with cleanliness checklist +β”œβ”€β”€ docs/ # Documentation +β”‚ β”œβ”€β”€ INTEGRATION.md # Guide for integrating from donor repos +β”‚ └── MAINTENANCE.md # Repository maintenance guide +β”œβ”€β”€ examples/ # Usage examples (when available) +β”œβ”€β”€ scripts/ # Maintenance and utility scripts +β”‚ β”œβ”€β”€ cleanup.sh # Automated cleanup script +β”‚ └── audit.sh # Repository health audit +β”œβ”€β”€ engine/ # Core orchestration (ProSe_Agent2) +β”œβ”€β”€ file_organizer/ # File tools (PSFO) +β”œβ”€β”€ case/ # Local-only examples +β”œβ”€β”€ tests/ # Test files +β”œβ”€β”€ .gitignore # Comprehensive ignore patterns +β”œβ”€β”€ CODE_OF_CONDUCT.md # Repository standards +β”œβ”€β”€ CONTRIBUTING.md # Contribution guidelines +β”œβ”€β”€ CHANGELOG.md # Version history +└── README.md # This file +``` + +> ⚠️ Real case data (PDFs, screenshots, exports) should never live in this repo. +Keep those in a local `DivorceFiles/` tree or synced drive outside git. + +--- + +## πŸš€ Getting Started + +### For Contributors + +1. **Read the Guidelines** + - `CONTRIBUTING.md` + - `CODE_OF_CONDUCT.md` + +2. **Fork and Clone** + ```bash + git clone https://github.com/your-username/ProSe.git + cd ProSe + ``` + +3. **Create a Feature Branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +4. **Make Your Changes** + - Follow the contribution guidelines + - Keep it clean (no backup or temp files) + - Add tests where appropriate + +5. **Run Maintenance Scripts** + ```bash + bash scripts/audit.sh + bash scripts/cleanup.sh + ``` + +6. **Submit a Pull Request** + - Use the PR template + - Ensure all checklist items are complete + +--- + +## 🧹 Keeping It Clean + +### Not Allowed +- ❌ Backup files (`*.bak`, `*.old`, `*.backup`, `*~`) +- ❌ Temporary files (`*.tmp`, `temp/`, `tmp/`) +- ❌ Commented-out code +- ❌ Unused imports or functions +- ❌ Debug print statements +- ❌ IDE configuration (`.vscode/`, `.idea/`) +- ❌ Build artifacts (`dist/`, `build/`, compiled binaries) +- ❌ Personal notes or TODO text files + +### Automated Checks +CI runs the repository cleanliness workflow on every push and PR. + +Locally: +```bash +bash scripts/audit.sh +bash scripts/cleanup.sh +``` + +--- + +## πŸ“š Documentation + +- `CONTRIBUTING.md` – Contribution guidelines +- `CODE_OF_CONDUCT.md` – Repository standards and enforcement +- `docs/MAINTENANCE.md` – Maintenance schedule and procedures +- `docs/INTEGRATION.md` – Integrating code from donor repositories + +--- + +## 🀝 Contributing + +We welcome clean, well-tested contributions. + +**Quick checklist before opening a PR:** +- [ ] No backup files +- [ ] No temporary files +- [ ] No commented-out code +- [ ] No debug statements +- [ ] All files in proper directories +- [ ] Tests pass +- [ ] Documentation updated +- [ ] `bash scripts/audit.sh` completes successfully + +--- + +## πŸ“ž Support + +- **Issues**: Use GitHub Issues with appropriate labels +- **Questions**: Create an issue with the `question` label +- **Cleanup Requests**: Use the "Cleanup Request" issue template + +--- + +## πŸ“Š Repository Health + +Run: +```bash +bash scripts/audit.sh +``` +to check repository health at any time. + +**Current standards:** +- βœ… Zero backup files +- βœ… Zero temporary files +- βœ… Organized directory structure +- βœ… Comprehensive `.gitignore` +- βœ… Core documentation in place + +--- + +## πŸ“œ License + +This project is licensed under the MIT License. See `LICENSE` for details. + +--- + +**A clean repository is a calmer brain. πŸŽ‰**