chore: add docs sync guardrails and spec documents

README.md

@@ -113,6 +113,35 @@ PORTFOLIOHUB_DB_ENABLED=true portfoliohub portfolio list
 
 This repository now uses Alembic for versioned schema migrations. Future schema changes should be added under `migrations/versions`.
 
+## Docs Sync Guardrail
+
+To keep implementation and specification documents in sync, this repository provides an automated check.
+
+Rules enforced:
+
+- If files under `app/` change, `docs/portfoliohub-spec.md` must be updated in the same commit/PR.
+- If files under `app/api/` or `app/schemas/` change, `docs/api-examples.md` must be updated in the same commit/PR.
+- If files under `migrations/versions/` change, `docs/db-schema-spec.md` must be updated in the same commit/PR.
+- Changed migration revision IDs must appear in `docs/db-schema-spec.md`.
+
+Enable local pre-commit check:
+
+```bash
+pip install -e .[dev]
+pre-commit install
+```
+
+Run manually:
+
+```bash
+python3 scripts/check_docs_sync.py --staged
+```
+
+CI check:
+
+- GitHub Actions workflow: `.github/workflows/docs-sync-check.yml`
+- Runs automatically on pull requests.
+
 ## Authentication model
 
 PortfolioHub currently supports bearer tokens with three permission levels.