cleanup of the working tree. Created docs/{policies,reports} folders to keep documentation organized

1 files changed, 351 insertions, 0 deletions

diff --git a/docs/policies/BRANCHING-POLICY.md b/docs/policies/BRANCHING-POLICY.md
new file mode 100644
index 0000000..ddc5138
--- /dev/null
+++ b/docs/policies/BRANCHING-POLICY.md
@@ -0,0 +1,351 @@
+# Weekly Branching Policy
+
+**Effective Date:** Week 3 (2026-04-17 onwards)  
+**Status:** ✅ Active
+
+---
+
+## Executive Summary
+
+Starting with Week 3, each week of implementation work will use a **feature branch** to isolate changes, enable code review, and ensure safe integration into the main `master` branch.
+
+**Format:** `week-<number>-<description>`  
+**Example:** `week-3-cards-nav`, `week-4-forms-interactions`
+
+---
+
+## Why Weekly Branching?
+
+### 1. Code Review
+Each week's work can be reviewed as a complete unit before merging to master.
+
+### 2. Safety
+If issues are discovered, the feature branch can be easily discarded without affecting master. Easy rollback if needed.
+
+### 3. Isolation
+Each week's work is independent. Less chance of accidental changes or conflicts affecting master.
+
+### 4. Clean History
+Git log shows logical, week-based commits instead of intermingled changes.
+
+### 5. Testing
+Entire week's work can be tested on the feature branch before merging. Catch issues before they affect master.
+
+---
+
+## Weekly Workflow
+
+### Week 3 (and beyond)
+
+```
+┌─── master (stable, always works)
+│
+├─ week-3-cards-nav (feature branch)
+│  ├─ commit 1: add card component
+│  ├─ commit 2: add navigation header
+│  ├─ commit 3: add hamburger menu
+│  ├─ commit 4: add breadcrumbs
+│  └─ [TESTED & REVIEWED]
+│
+└─ Merge to master when ready
+   └─ master now has Week 3 changes
+```
+
+---
+
+## Step-by-Step Instructions
+
+### 1. Start of Week
+
+```bash
+# Ensure master is up to date
+git checkout master
+git pull origin master  # if using remote
+
+# Create feature branch
+git checkout -b week-3-cards-nav
+
+# Verify branch created
+git branch -v
+```
+
+### 2. Throughout the Week
+
+```bash
+# Make changes (CSS, templates, docs)
+vim themes/danix-xyz-hacker/assets/css/main.css
+
+# Rebuild CSS
+npm run build
+
+# Test in browser
+hugo server
+
+# Commit regularly after each component
+git add .
+git commit -m "feat: add article card component"
+
+# Commit again when next component done
+git add .
+git commit -m "feat: add navigation header"
+```
+
+### 3. End of Week (Before Merging)
+
+```bash
+# Review all changes
+git diff master..week-3-cards-nav
+
+# Review commit history
+git log master..week-3-cards-nav --oneline
+
+# View file changes summary
+git diff --stat master..week-3-cards-nav
+
+# Test thoroughly in browser
+# - All dark mode
+# - All light mode
+# - Mobile, tablet, desktop
+# - Keyboard navigation
+# - All interactive elements
+
+# Check CSS builds without errors
+npm run build
+
+# Check for console errors in browser
+# (DevTools → Console)
+
+# Check git log looks good
+git log --oneline -10
+```
+
+### 4. Merge to Master
+
+Once testing is complete:
+
+```bash
+# Switch to master
+git checkout master
+
+# Merge feature branch
+git merge week-3-cards-nav
+
+# Optional: Delete feature branch
+git branch -d week-3-cards-nav
+
+# Verify merge
+git log --oneline -5
+```
+
+### 5. Start Next Week
+
+```bash
+# Create next week's branch
+git checkout -b week-4-forms-interactions
+
+# Continue with Week 4 work...
+```
+
+---
+
+## Branching Policy Details
+
+### Branch Creation
+
+- **Source:** Always branch from `master`
+- **Timing:** At the start of each week
+- **Naming:** `week-<N>-<description>` (lowercase, hyphens)
+
+Examples:
+```
+week-3-cards-nav
+week-4-forms-interactions
+week-5-animations-a11y
+week-6-pages-testing
+```
+
+### Commits During Week
+
+- **Frequency:** Commit after each component is complete
+- **Messages:** Clear, descriptive, following format
+- **Size:** Small, logical chunks (not one big commit)
+
+Example commits for Week 3:
+```
+feat: add article card component
+feat: add card hover effects (lift, shadow)
+feat: add navigation header
+feat: add hamburger menu
+feat: add breadcrumb navigation
+docs: week 3 implementation complete
+```
+
+### Testing Before Merge
+
+**Required testing:**
+- [ ] Dark mode (all pages, all components)
+- [ ] Light mode (toggle, verify all pages)
+- [ ] Mobile responsive (320px)
+- [ ] Tablet responsive (768px)
+- [ ] Desktop responsive (1060px+)
+- [ ] Keyboard navigation (Tab, Shift+Tab, Enter, Space, Escape)
+- [ ] Focus indicators visible on all interactive elements
+- [ ] No hard-coded colors in new CSS
+- [ ] CSS builds with no errors (<200ms)
+- [ ] No console errors in browser DevTools
+- [ ] Color contrast WCAG AA verified
+- [ ] All interactive components working (buttons, menus, etc.)
+
+### Merge to Master
+
+**Before merging:**
+1. Review all changes: `git diff master..week-N-...`
+2. Complete testing checklist above
+3. Verify git log is clean and clear
+
+**Merge command:**
+```bash
+git checkout master
+git merge week-N-...
+```
+
+**After merge:**
+1. Delete feature branch: `git branch -d week-N-...`
+2. Verify all changes are in master: `git log --oneline -10`
+3. Start next week's branch
+
+---
+
+## Retroactive Application
+
+**Weeks 1-2** were completed on `master` before this policy was adopted.
+
+**Week 3 onwards** will follow weekly branching policy.
+
+All Week 3+ work will be properly isolated on feature branches.
+
+---
+
+## Commit Message Format
+
+### Simple Format
+```
+<type>: <subject>
+```
+
+Example:
+```
+feat: add article card component
+```
+
+### Detailed Format
+```
+<type>: <subject>
+
+<body>
+```
+
+Example:
+```
+feat: add article card component
+
+- Image with 16:9 aspect ratio
+- Title, excerpt, type badge, CTA button
+- Hover: lift -2px, shadow enhancement
+- Dark/light mode support
+- WCAG AA accessible
+```
+
+### Types
+- `feat:` — New feature (component, layout, page)
+- `fix:` — Bug fix
+- `style:` — CSS/styling changes
+- `refactor:` — Code restructuring
+- `docs:` — Documentation changes
+- `chore:` — Build, tooling, config
+
+---
+
+## Quick Reference
+
+### Common Commands
+
+```bash
+# Create branch
+git checkout -b week-3-cards-nav
+
+# Switch branches
+git checkout master
+git checkout week-3-cards-nav
+
+# View changes
+git diff master..week-3-cards-nav
+git diff --stat master..week-3-cards-nav
+
+# Commit
+git add .
+git commit -m "feat: add card component"
+
+# View history
+git log master..week-3-cards-nav --oneline
+git log --oneline -10
+
+# Merge
+git checkout master
+git merge week-3-cards-nav
+
+# Delete branch
+git branch -d week-3-cards-nav
+
+# List branches
+git branch -a
+```
+
+See `GIT-WORKFLOW-QUICK-REF.md` for more commands.
+
+---
+
+## FAQ
+
+**Q: Can I work across multiple branches?**  
+A: No. Work on one week's feature branch at a time. After merging to master, delete the branch and create a new one for the next week.
+
+**Q: What if master changes while I'm working on Week 3?**  
+A: Merge master into your branch: `git checkout week-3-cards-nav && git merge master`. Then resolve any conflicts.
+
+**Q: Can I commit to master directly?**  
+A: Not during the week. All changes happen on the feature branch. Merge after testing.
+
+**Q: How long should a feature branch exist?**  
+A: One week. Created at start of week, merged to master at end of week, then deleted.
+
+**Q: What if I discover an urgent bug during Week 3?**  
+A: Fix it on the feature branch (or fix it on master separately, then merge into feature branch). All work in one week's feature branch.
+
+**Q: Can I create sub-branches off week branches?**  
+A: Generally no. Keep it simple: one branch per week. If you need isolation within the week, use clear commit messages instead.
+
+---
+
+## Related Documentation
+
+- **GIT-WORKFLOW.md** — Complete workflow guide with examples
+- **GIT-WORKFLOW-QUICK-REF.md** — Common commands quick reference
+- **WEEK3-START.md** — Week 3 quick start (includes branching instructions)
+
+---
+
+## Summary
+
+**Weekly branching:**
+
+1. ✅ Create feature branch at week start
+2. ✅ Implement work, commit regularly
+3. ✅ Test thoroughly before end of week
+4. ✅ Review all changes
+5. ✅ Merge to master when ready
+6. ✅ Delete feature branch
+7. ✅ Repeat for next week
+
+This policy ensures clean code, thorough testing, and safe integration.
+