Feat/evidence freshness detector#2
Merged
maliah1010 merged 5 commits intomainfrom Mar 23, 2026
Merged
Conversation
added 5 commits
March 14, 2026 09:01
Introduces the core data model for the Evidence Freshness Detector: - FreshnessConfig — configurable thresholds, weights, and optional gate date for fresh-paint burst-edit detection. - RevisionEntry — a single timestamped revision history entry. - DocumentMetadata — metadata extracted from PM files combining OS-level and format-specific provenance (author, versions, revision history, content hash). - FreshnessAlert — structured alert with type, severity, score, and format-specific detail dict. - DocumentFreshnessResult — per-document scoring result (staleness, velocity, provenance sub-scores, composite score, RAG status, alerts). - PackFreshnessResult — aggregated pack-level result (overall/min score, per-status counts, all alerts). All types are frozen dataclasses with to_dict() JSON serialisation.
- Registers FreshnessAnalyser, FreshnessConfig, and extract_metadata in
pm_data_tools.__init__ for top-level import convenience.
- Adds pm-data-tools freshness <path> CLI subcommand supporting:
- Single-file and directory (evidence pack) analysis.
- --gate-date, --fresh-days, --stale-days, --recursive flags.
- --json / --output flags for machine-readable output.
- Colour-coded RAG status in terminal output.
- Non-zero exit code when pack/document is not green.
Registers a new check_freshness tool in the pm-validate MCP server: - Accepts file_path (file or directory), optional file_format, gate_date, fresh_threshold_days, stale_threshold_days, and recursive parameters. - Delegates to FreshnessAnalyser.analyse_file or analyse_pack. - Returns the full to_dict() result (scores, RAG status, per-document breakdown, all alerts) as JSON via TextContent. - Gracefully degrades with a structured error response if pm-data-tools freshness module is unavailable.
136 tests across four files covering: - test_models.py — immutability, serialisation, str representations, and edge cases for all six model types. - test_analyser.py — all helper functions (_clamp, _days_since, _rag_from_score), staleness/velocity/provenance sub-scores with boundary and edge cases, all four alert types (stale, fresh_paint, incomplete_provenance, never_updated), FreshnessAnalyser.score_metadata, analyse_file, analyse_pack (empty, recursive, multi-file, all-alerts aggregated). - test_metadata_extractor.py — ISO date parser, SHA-256 hashing, format auto-detection heuristics, OS-level fallback, Jira/Monday/Asana/ Smartsheet/NISTA/GMPP/MSPDI format-specific extraction, format override. - test_metadata_extractor_extra.py — P6 XER and XML extraction, MSPDI edge cases (non-integer revision, created_at not overwritten), Monday and Asana payload variants, Jira list payload, unknown formats. Overall coverage on pm_data_tools.freshness: 90%.
- README: adds Evidence Freshness Detector section with scoring model table, alert type table, quick-start code block, and updated CLI examples. Adds freshness to the features list and architecture layer. - examples/freshness_analysis.py: five self-contained examples covering single-file analysis, evidence pack analysis, fresh-paint gate-date detection, custom metadata pipeline (score_metadata directly), and JSON export. Runs with no external files using tempfile fixtures.
maliah1010
added a commit
that referenced
this pull request
Mar 28, 2026
maliah1010
pushed a commit
that referenced
this pull request
Mar 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #
Changes
Checklist
pytest packages/<name>/tests/)ruff check packages/<name>/)