Feature/bundle 26 essentia real extraction

.env.example

@@ -17,3 +17,13 @@ REDIS_URL=redis://redis:6379/0
 API_TOKEN=change-me
 JWT_SECRET=change-me
 JWT_ALGORITHM=HS256
+
+# Canonical writer remains OFF by default. Enable only in a bounded non-live
+# environment together with an explicit JSONL receipt path.
+APPLAYLIST_CANONICAL_WRITER_ENABLED=0
+APPLAYLIST_CANONICAL_WRITER_RECEIPTS_PATH=
+
+# Optional comparison evidence. This remains OFF unless the bounded non-live
+# canonical writer profile is enabled and both values below are explicit.
+APPLAYLIST_CANONICAL_COMPARISON_ENABLED=0
+APPLAYLIST_CANONICAL_COMPARISON_RECEIPTS_PATH=

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+- 
+
+## Verification
+- 
+
+## Notes
+- 
+
+## Bundle Context
+- Bundle:
+- Base branch:
+- Related issue:

.github/workflows/pr-guard.yml

@@ -0,0 +1,24 @@
+name: PR Guard
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  validate-pr:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate branch name
+        run: |
+          bash scripts/check_branch_name.sh "${{ github.head_ref }}"
+
+      - name: Validate PR structure
+        run: |
+          PR_TITLE="${{ github.event.pull_request.title }}"
+          PR_BODY="${{ github.event.pull_request.body }}"
+          export PR_TITLE PR_BODY
+          bash scripts/check_pr_standard.sh

.gitignore

@@ -36,3 +36,112 @@ exports/
 # Frontend
 frontend/node_modules/
 frontend/dist/
+
+# STOP DUPLICATES + ICLOUD
+*.icloud
+* 2.*
+* 3.*
+* 4.*
+
+# macOS / iCloud junk
+*.icloud
+* 2.*
+* 3.*
+* 4.*
+
+# macOS / iCloud garbage
+*.icloud
+.DS_Store
+
+# runtime
+data/cache/
+data/config/path_profiles.json
+
+# backups
+.backup_*
+
+# --- VOODOO CLEAN RULES ---
+*.icloud
+.DS_Store
+*.log
+*.tmp
+*.bak
+__pycache__/
+*.pyc
+.backup_*
+data/cache/
+data/tmp/
+node_modules/
+.env
+# --- APPLAYLIST HARDENING ---
+*.icloud
+.DS_Store
+*.log
+*.tmp
+*.bak
+*.swp
+*.swo
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.backup_*/
+data/tmp/
+.env
+.env.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+api/main.py.bak.*
+
+# --- VOODOO LOCAL / RUNTIME / SENSITIVE ---
+.env
+.env.*
+!.env.example
+
+.venv/
+venv/
+ENV/
+
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.DS_Store
+__MACOSX/
+
+*.db
+*.sqlite
+*.sqlite3
+
+*.egg-info/
+dist/
+build/
+
+.local_backups/
+artifacts/
+exports/
+logs/
+tmp/
+
+# --- APPLAYLIST ICLOUD DUPLICATE GUARD ---
+* 2.py

.python-version

@@ -0,0 +1 @@
+3.11

ARCHITECTURE.md

@@ -0,0 +1,88 @@
+---
+id: FOUNDATION-ARCHITECTURE
+title: APPLAYLIST Architecture
+status: ACCEPTED
+owner: APPLAYLIST Engineering
+created: 2026-07-30
+updated: 2026-07-30
+supersedes:
+  - docs/architecture/APPLAYLIST_PHASE1_ARCHITECTURE.md
+related:
+  - PRODUCT.md
+  - STATUS.md
+  - docs/architecture/APPLAYLIST_PROVIDER_ANALYSIS_ROLLOUT.md
+  - docs/architecture/APPLAYLIST_RHYTHMIC_STRUCTURE_EVIDENCE_V1.md
+---
+
+# APPLAYLIST Architecture
+
+## Source-of-truth rule
+
+For current behavior, use this order:
+
+1. current repository content,
+2. Git state,
+3. executed local verification,
+4. runtime configuration/evidence,
+5. CI evidence,
+6. architecture and operations documentation,
+7. README statements.
+
+Historical bundle documents are evidence of their work block, not automatic authority for the
+current runtime.
+
+## Current component boundaries
+
+```text
+API
+  -> application services
+      -> domain/core logic
+      -> repositories / SQLite
+      -> jobs / workers
+      -> analysis providers
+      -> composer / transition / explainability
+```
+
+Primary directories:
+
+- `api/` — HTTP boundary, routes, middleware and API security;
+- `core/` — domain logic, analysis/provider contracts, transition logic and configuration;
+- `services/` — application orchestration;
+- `data/` — models, repositories and persistence;
+- `workers/` — background processing scaffolds;
+- `tests/` — regression and contract evidence;
+- `docs/` — architecture, operations, governance and work-block evidence;
+- `scripts/` — local verification and maintenance tooling.
+
+## Analysis boundary
+
+Heavy audio backends must remain behind explicit provider boundaries and must not become mandatory
+API-startup imports.
+
+The current repository still contains analysis-contract drift: `core/analysis/normalize.py`
+contains a compatibility fallback for richer analysis types that are not defined by the current
+`core/analysis/contracts.py`. This is explicit deferred **EPIC-003** debt and is not resolved by
+WB001.
+
+## Transition boundary
+
+Transition assessment, recommendation, explanation, and user decision are separate concerns.
+Transition Intelligence runtime activation remains off.
+
+WB006C adds source-bound beat-grid shadow evidence and reconciliation only. It does not provide
+accepted downbeat, phrase, structure-segment, vocal, bass, or overlap runtime authority.
+
+## Runtime and data safety
+
+- optional-provider failure must not break mandatory startup;
+- missing measurements must not be fabricated;
+- source identity and provenance must be preserved where a work block requires them;
+- local and production configuration must remain separate;
+- public API/schema changes require an explicit isolated work block;
+- database migrations require backup and rollback evidence.
+
+## Evolution rule
+
+Documentation/governance structure may be improved independently. Runtime module moves,
+contract migrations, provider activation, and desktop integration must remain separate,
+testable work blocks.

Makefile

@@ -1,13 +1,40 @@
-.PHONY: dev test lint tree
+PYTHON ?= .venv/bin/python
+PYTHON_BOOTSTRAP ?= python3.12
+BUNDLE_DIR ?= artifacts
 
-dev:
-	uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
+.PHONY: bootstrap doctor lint type test security verify bundle dev tree
 
-test:
-	pytest -q
+bootstrap:
+	./scripts/bootstrap_local.sh "$(PYTHON_BOOTSTRAP)" ".venv"
+
+doctor:
+	APPLAYLIST_PYTHON="$(PYTHON)" ./scripts/doctor.sh
 
 lint:
-	ruff check .
+	APPLAYLIST_PYTHON="$(PYTHON)" ./scripts/lint_gate.sh
+
+type:
+	APPLAYLIST_PYTHON="$(PYTHON)" ./scripts/type_gate.sh
+
+test:
+	PYTHONDONTWRITEBYTECODE=1 "$(PYTHON)" -m pytest -q
+
+security:
+	APPLAYLIST_PYTHON="$(PYTHON)" ./scripts/security_gate.sh
+
+verify:
+	$(MAKE) doctor PYTHON="$(PYTHON)"
+	$(MAKE) lint PYTHON="$(PYTHON)"
+	$(MAKE) type PYTHON="$(PYTHON)"
+	$(MAKE) test PYTHON="$(PYTHON)"
+	$(MAKE) security PYTHON="$(PYTHON)"
+	APPLAYLIST_PYTHON="$(PYTHON)" ./scripts/restore_smoke.sh
+
+bundle:
+	./scripts/bundle_local.sh "$(BUNDLE_DIR)"
+
+dev:
+	"$(PYTHON)" -m uvicorn api.main:app --reload --host 127.0.0.1 --port 8000
 
 tree:
 	find . -maxdepth 3 -type f | sort