Doc/spec kit and project sync

.github/workflows/test.yml

@@ -107,7 +107,7 @@ jobs:
         run: echo "PYTHONPATH=${GITHUB_WORKSPACE}/release_notes_generator/release_notes_generator" >> $GITHUB_ENV
 
       - name: Check code coverage with Pytest
-        run: pytest --cov=. -v tests/ --cov-fail-under=80
+        run: pytest --cov=. -v tests/unit --cov-fail-under=80
 
   mypy-check:
     runs-on: ubuntu-latest

.specify/constitution.md

@@ -1,11 +1,12 @@
 <!--
 Sync Impact Report
-Version change: 1.0.0 -> 1.0.1
-Modified sections: Governance & Ownership (maintainers list)
-Added sections: None
+Version change: 1.3.0 -> 1.4.0
+Modified sections: Principle 13 expanded to include fix/, docs/, chore/; Quality Gates branch naming; Compliance Review
+Added sections: Allowed prefix list & category descriptions; CI workflow enforcement `.github/workflows/branch-prefix-check.yml`
 Removed sections: None
-Change type: PATCH (metadata clarification, no principle change)
-Templates requiring updates: None (no template impact)
+Change type: MINOR (expanded enforceable governance rule)
+Templates requiring updates: plan-template.md (✅), tasks-template.md (✅), spec-template.md (✅), DEVELOPER.md (✅), CONTRIBUTING.md (✅), branch-prefix-check.yml (✅)
+Deferred TODOs: None
 -->
 
 # Release Notes Scrapper Action Constitution
@@ -65,11 +66,23 @@ manage version tagging; it consumes existing tags.
 7. `ReleaseNotesBuilder` iterates chapters → collects matching records → applies row format templates / duplicity markers.
 8. Final Markdown string emitted; composite action sets `release-notes` output.
 
-### Boundary Rules
+### Boundary Rules (Refined)
 - Action inputs boundary: all configurable behavior must pass via declared inputs (no hidden runtime switches).
 - GitHub API boundary: all repository data access encapsulated within miner and rate limiter logic.
 - Formatting boundary: only row format templates and chapters influence visible line structure; business logic must not
   directly embed presentation markup elsewhere.
+- Error boundary: modules MUST NOT leak raw exceptions across boundaries; they must convert failures into logged events
+  and structured return values (see Principle 9). Internal exceptions MAY be raised and caught within the same module.
+- Utility boundary: functions in `utils/` MUST be demonstrably used by at least one importing module or removed (see Principle 8 & 10).
+
+### Module Boundary Follow-Up
+A scheduled audit SHALL verify:
+- `utils/` contains only actively referenced functions (dead code removal list to be created).
+- `generator.py` remains orchestration-only (no direct formatting or low-level API calls beyond miner invocation).
+- `builder/` never performs mining; strictly transforms records to Markdown.
+- `record/factory` isolates construction logic; future refactors MAY extract validation into a separate `validators/` module.
+- Logging configuration centralization: confirm no duplicate ad-hoc log setup outside `main.py`.
+Outcome: Produce a follow-up task list referencing each violation if found; merge only with accompanying unit tests.
 
 ## 3. Data & Integrations
 
@@ -119,13 +132,39 @@ manage version tagging; it consumes existing tags.
 ## 5. Quality & Testing
 
 ### Test Types
-- Unit tests (expected for pure utility and formatting functions).
+- Unit tests for pure utility, transformation, formatting, and record construction functions.
 - Integration tests (e.g. `integration_test.py`) covering end-to-end generation using mocked or controlled data.
-- No explicit contract tests yet; future addition may define record/chapter contract snapshots.
+- Future: contract/snapshot tests MAY be introduced for chapter output stability (not mandatory yet).
+
+### Test Directory Structure (New)
+```
+tests/
+  unit/                # All Python unit tests (test_<module>.py) - REQUIRED location
+  integration/         # Future integration tests (current single file may migrate here)
+  fixtures/            # Shared static test data & factories (optional)
+  helpers/             # Helper utilities used only by tests (must be imported by tests/*)
+  release_notes/       # Domain-specific sample data (review for possible move under fixtures/)
+  utils/               # Test-only utility functions (rename to helpers/ or remove if redundant)
+```
+Rules:
+- All unit tests MUST reside under `tests/unit/` (root-level `test_*.py` files SHALL be relocated).
+- Naming: `test_<target>.py`; multiple related small targets MAY share one file if cohesive.
+- Test style: uses ONLY `pytest` (no unittest classes). Prefer functions + fixtures.
+- Fixtures: define shared objects in `tests/conftest.py` or per-file fixtures; keep scope minimal.
+- Parametrization: use `@pytest.mark.parametrize` for input matrix instead of loops.
+- Coverage: new logic MUST raise overall coverage or keep it steady; dropping coverage requires explicit justification.
+- NEW: Unit test file path MUST mirror source relative package path (Principle 12). For source file `release_notes_generator/utils/constants.py`, the test lives at `tests/unit/release_notes_generator/utils/test_constants.py`.
+- Branch Naming: Feature / fix / docs / chore PRs MUST originate from correctly prefixed branch (Principle 13); CI may validate.
+
+### Organization & Integration
+- Integration tests MUST import public interfaces only (`main`, `ReleaseNotesGenerator`) not internal private helpers.
+- Unit tests MUST avoid real network calls; use mocking or local sample data.
+- Cross-test independence: tests MUST NOT rely on execution order; no shared mutation outside fixture scope.
+- Relocation of existing root-level unit tests into `tests/unit/` SHALL be part of first compliance PR post-amendment.
 
 ### Coverage
-- `pytest-cov` integrated; HTML coverage artifacts seen in `htmlcov/`. Target: maintain or improve existing coverage
-  (implicit baseline > minimal demonstration). New core logic MUST include tests before implementation (Test‑First Principle).
+- `pytest-cov` integrated; HTML coverage artifacts under `htmlcov/`. Baseline maintained or improved. New core logic MUST
+  include tests before implementation (Test‑First Principle).
 
 ### Static Analysis & Review
 - `pylint`, `mypy` required to pass (configuration present).
@@ -135,7 +174,9 @@ manage version tagging; it consumes existing tags.
 ### Quality Gates (Minimum Acceptance)
 - Tests: ALL must pass.
 - Lint + type: zero blocking errors.
+- No unused functions/methods (see Principle 10) — introduce usage or delete in same PR.
 - Backward compatibility: no silent change to input names or placeholder semantics without version bump & documentation update.
+- Branch naming compliance (Principle 13) — allowed prefixes: feature/, fix/, docs/, chore/; rename if violated.
 
 ## 6. Constraints & Compatibility
 
@@ -169,6 +210,7 @@ manage version tagging; it consumes existing tags.
 - Hierarchy expansion could incur additional API calls increasing latency.
 - Duplicate detection edge cases may confuse users if same issue intentionally spans categories.
 - CodeRabbit integration features may parse unintended summary content (format variance risk).
+- Dead code accumulation in `utils/` may reduce clarity if Principle 10 not enforced promptly.
 
 ### Assumptions
 - Repository uses semantic version tags (prefixed optionally by `v`).
@@ -200,6 +242,7 @@ manage version tagging; it consumes existing tags.
 ### Compliance Review
 - PR template or automated check SHOULD reference Constitution principles (especially Test‑First & Stability) before merge.
 - Violations require explicit justification section in PR description.
+- Review checklist MUST confirm Principle 13 prefix correctness and scope alignment.
 
 ### Release Management
 - Tagging strategy external; this action consumes tags. Recommend semantic versioning for repository releases.
@@ -236,7 +279,7 @@ Ensure Constitution Check section in `plan.md` passes before advancing to detail
 
 ## Change Log / Versioning
 - Project releases follow Git tags; this constitution uses semantic versioning independent of code releases.
-- Current Constitution Version: 1.0.1 (initial ratification).
+- Current Constitution Version: 1.4.0 (amended with new principles & test structure).
 - Future amendments tracked via Sync Impact Report at top of this file.
 
 ## Core Principles
@@ -277,5 +320,53 @@ Mining MUST use rate limiter abstraction; avoid redundant API calls (e.g. re-fet
 MUST short-circuit when disabled. Performance considerations addressed before accepting features that multiply API calls.
 Rationale: Preserves quota & improves speed on large repositories.
 
+### Principle 8: Lean Python Design
+Prefer simple functions and modules over unnecessary classes. A class MUST only be introduced when stateful behavior or
+polymorphism is required. Utility modules SHOULD expose pure functions. Avoid deep inheritance; favor composition.
+Rationale: Reduces complexity and improves readability & testability.
+
+### Principle 9: Localized Error Handling & Non-Exceptional Flow
+Modules MUST catch internal exceptions and convert them into structured return values plus logged messages. Cross-module
+exception propagation (raising raw exceptions across boundaries) is prohibited except for truly unrecoverable setup
+failures at the entry point (`main`). Return either a valid result or a clearly logged empty/partial result.
+Rationale: Ensures predictable action behavior and prevents silent termination in CI pipelines.
+
+### Principle 10: Dead Code Prohibition
+No unused methods/functions SHALL remain in the codebase (properties or inherited abstract/interface methods excepted).
+Utility files MUST contain only actively invoked functions. Removal of unused code MUST occur in the same PR that
+introduces its obsolescence.
+Rationale: Prevents confusion, reduces maintenance overhead, and keeps coverage meaningful.
+
+### Principle 11: Focused & Informative Comments
+Comments MUST explain non-obvious logic, constraints, or reasoning succinctly. Prohibited: narrative, outdated, or
+speculative comments. Allowed: brief context before complex loops, rationale for workaround, links to issue references.
+Comments SHOULD be maintained or updated alongside code changes; stale comments MUST be removed.
+Rationale: Enhances clarity without adding noise.
+
+### Principle 12: Test Path Mirroring
+Each unit test file MUST reside under `tests/unit/` mirroring the source package path and file name: `tests/unit/<source_root_relative_path>/test_<original_file_name>.py`.
+Mandatory Rules:
+- One test file per source file unless tightly coupled logic demands grouping (justify in PR).
+- Legacy non-mirrored category folders are deprecated; migrate incrementally without reducing coverage.
+- New or refactored modules require mirrored test path in same PR.
+Rationale: Ensures predictable test discovery, simplifies navigation between code and tests, and supports scalable refactors.
+
+### Principle 13: Branch Naming Consistency
+All new branches for work MUST start with one of the approved prefixes followed by a concise kebab-case descriptor (optional numeric ID).
+Approved prefixes:
+- `feature/` – new features & enhancements
+- `fix/` – bug fixes / defect resolutions
+- `docs/` – documentation-only updates
+- `chore/` – maintenance, dependency bumps, CI, non-behavioral refactors
+Examples:
+`feature/add-hierarchy-support`, `fix/567-handle-empty-chapters`, `docs/improve-readme-start`, `chore/upgrade-semver-lib`
+Rules:
+- Prefix REQUIRED and MUST be in approved set; rename non-compliant branches prior to PR.
+- Descriptor: lowercase kebab-case; hyphen separators; no spaces/underscores/trailing slash.
+- Optional numeric ID may precede description (`fix/987-null-title`).
+- Category alignment: branch prefix MUST match primary scope of PR contents.
+- Avoid vague descriptors (`update`, `changes`). Prefer action or subject (`improve-logging`, `remove-dead-code`).
+Rationale: Standardizes history, enables automated governance checks, clarifies intent for reviewers & tooling.
+
 ## Governance Metadata
-**Version**: 1.0.1 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-12
+**Version**: 1.4.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-14