agentic-project-kit 1.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentic_project_kit/__init__.py +1 -0
- agentic_project_kit/absolute_path_portability_audit.py +241 -0
- agentic_project_kit/access_level_policy.py +14 -0
- agentic_project_kit/access_levels.py +22 -0
- agentic_project_kit/action_registry.py +195 -0
- agentic_project_kit/action_specs.py +286 -0
- agentic_project_kit/agent_command_runner.py +516 -0
- agentic_project_kit/audit_test_matrix.py +36 -0
- agentic_project_kit/audit_test_matrix_cli.py +43 -0
- agentic_project_kit/chat_bootloader.py +257 -0
- agentic_project_kit/chat_entrypoint_contract.py +297 -0
- agentic_project_kit/checks.py +511 -0
- agentic_project_kit/ci_readiness.py +211 -0
- agentic_project_kit/cli.py +147 -0
- agentic_project_kit/cli_commands/__init__.py +1 -0
- agentic_project_kit/cli_commands/absolute_path_audit.py +25 -0
- agentic_project_kit/cli_commands/actions.py +21 -0
- agentic_project_kit/cli_commands/artifact_gc.py +240 -0
- agentic_project_kit/cli_commands/boot.py +55 -0
- agentic_project_kit/cli_commands/chat.py +34 -0
- agentic_project_kit/cli_commands/checks.py +305 -0
- agentic_project_kit/cli_commands/cockpit.py +103 -0
- agentic_project_kit/cli_commands/command_taxonomy.py +25 -0
- agentic_project_kit/cli_commands/commands.py +129 -0
- agentic_project_kit/cli_commands/dev.py +23 -0
- agentic_project_kit/cli_commands/direction.py +92 -0
- agentic_project_kit/cli_commands/doc_currency_audit.py +25 -0
- agentic_project_kit/cli_commands/doc_registry.py +126 -0
- agentic_project_kit/cli_commands/docs.py +223 -0
- agentic_project_kit/cli_commands/dpa.py +1338 -0
- agentic_project_kit/cli_commands/evidence.py +251 -0
- agentic_project_kit/cli_commands/github.py +34 -0
- agentic_project_kit/cli_commands/governance.py +14 -0
- agentic_project_kit/cli_commands/gui.py +23 -0
- agentic_project_kit/cli_commands/gui_readiness_gate.py +27 -0
- agentic_project_kit/cli_commands/handoff.py +183 -0
- agentic_project_kit/cli_commands/human_workflows.py +430 -0
- agentic_project_kit/cli_commands/init.py +132 -0
- agentic_project_kit/cli_commands/instruction.py +75 -0
- agentic_project_kit/cli_commands/mutation_lock_audit.py +24 -0
- agentic_project_kit/cli_commands/ns_legacy_audit.py +25 -0
- agentic_project_kit/cli_commands/pass_already_done.py +66 -0
- agentic_project_kit/cli_commands/patch_failure_discipline_audit.py +26 -0
- agentic_project_kit/cli_commands/patch_preflight.py +37 -0
- agentic_project_kit/cli_commands/path_literal_audit.py +39 -0
- agentic_project_kit/cli_commands/patterns.py +40 -0
- agentic_project_kit/cli_commands/planning_docs_audit.py +25 -0
- agentic_project_kit/cli_commands/pr.py +133 -0
- agentic_project_kit/cli_commands/pr_hygiene.py +27 -0
- agentic_project_kit/cli_commands/profiles.py +26 -0
- agentic_project_kit/cli_commands/program_redundancy_audit.py +25 -0
- agentic_project_kit/cli_commands/project_direction.py +25 -0
- agentic_project_kit/cli_commands/release.py +392 -0
- agentic_project_kit/cli_commands/release_publish_orchestration.py +36 -0
- agentic_project_kit/cli_commands/remote_branch_hygiene.py +152 -0
- agentic_project_kit/cli_commands/remote_next.py +57 -0
- agentic_project_kit/cli_commands/removed_ns_commands.py +65 -0
- agentic_project_kit/cli_commands/rule_registry.py +129 -0
- agentic_project_kit/cli_commands/rules.py +222 -0
- agentic_project_kit/cli_commands/scaffold.py +46 -0
- agentic_project_kit/cli_commands/slice.py +21 -0
- agentic_project_kit/cli_commands/standard_gates_audit_suite.py +27 -0
- agentic_project_kit/cli_commands/state.py +51 -0
- agentic_project_kit/cli_commands/status_current_state_audit.py +30 -0
- agentic_project_kit/cli_commands/todo.py +53 -0
- agentic_project_kit/cli_commands/transfer.py +19 -0
- agentic_project_kit/cli_commands/transfer_context_flow.py +398 -0
- agentic_project_kit/cli_commands/transfer_context_helpers.py +398 -0
- agentic_project_kit/cli_commands/transfer_diagnostics.py +767 -0
- agentic_project_kit/cli_commands/transfer_evidence_flow.py +368 -0
- agentic_project_kit/cli_commands/transfer_handoff_flow.py +594 -0
- agentic_project_kit/cli_commands/transfer_order_contract.py +74 -0
- agentic_project_kit/cli_commands/transfer_post_merge_complete.py +442 -0
- agentic_project_kit/cli_commands/transfer_post_merge_settle.py +171 -0
- agentic_project_kit/cli_commands/transfer_pr_closeout_complete.py +124 -0
- agentic_project_kit/cli_commands/transfer_pr_create_flow.py +743 -0
- agentic_project_kit/cli_commands/transfer_pr_merge_flow.py +547 -0
- agentic_project_kit/cli_commands/transfer_repo_after_pr.py +160 -0
- agentic_project_kit/cli_commands/transfer_repo_pre_pr.py +664 -0
- agentic_project_kit/cli_commands/transfer_runner_flow.py +131 -0
- agentic_project_kit/cli_commands/transfer_runtime_initial.py +194 -0
- agentic_project_kit/cli_commands/transfer_shared.py +274 -0
- agentic_project_kit/cli_commands/validation.py +200 -0
- agentic_project_kit/cli_commands/version.py +27 -0
- agentic_project_kit/cli_commands/work_orders.py +219 -0
- agentic_project_kit/cli_commands/workflow.py +471 -0
- agentic_project_kit/cli_commands/workflow_guard.py +26 -0
- agentic_project_kit/cli_commands/workspace.py +252 -0
- agentic_project_kit/cockpit.py +608 -0
- agentic_project_kit/cockpit_readiness.py +67 -0
- agentic_project_kit/command_authority_audit.py +192 -0
- agentic_project_kit/command_inbox_check.py +103 -0
- agentic_project_kit/command_manifest.py +591 -0
- agentic_project_kit/command_queue_contract.py +161 -0
- agentic_project_kit/command_selector.py +245 -0
- agentic_project_kit/command_taxonomy.py +264 -0
- agentic_project_kit/commit_guard.py +67 -0
- agentic_project_kit/communication_artifact_gc.py +495 -0
- agentic_project_kit/communication_rule_context.py +437 -0
- agentic_project_kit/communication_state.py +115 -0
- agentic_project_kit/composed_wrapper_invariants.py +97 -0
- agentic_project_kit/composite_short_circuit.py +140 -0
- agentic_project_kit/contract.py +251 -0
- agentic_project_kit/control_state.py +83 -0
- agentic_project_kit/doc_currency_audit.py +536 -0
- agentic_project_kit/doc_lifecycle.py +1179 -0
- agentic_project_kit/doc_lifecycle_signals.py +446 -0
- agentic_project_kit/doc_lifecycle_sweep.py +639 -0
- agentic_project_kit/doc_mesh.py +491 -0
- agentic_project_kit/doctor.py +379 -0
- agentic_project_kit/documentation_registry.py +1122 -0
- agentic_project_kit/documentation_system_audit.py +310 -0
- agentic_project_kit/dpa_current_handoff_lifecycle.py +549 -0
- agentic_project_kit/dpa_dp2_decision_readiness.py +362 -0
- agentic_project_kit/dpa_dp3_dp4_adjudication.py +604 -0
- agentic_project_kit/dpa_dp5_block_new_gate.py +294 -0
- agentic_project_kit/dpa_dp5_stage_adoption.py +615 -0
- agentic_project_kit/dpa_dp5_strict_gate.py +187 -0
- agentic_project_kit/dpa_final_closeout.py +627 -0
- agentic_project_kit/dpa_fixture_evidence.py +680 -0
- agentic_project_kit/dpa_maintainer_record_check.py +711 -0
- agentic_project_kit/dpa_post_dp2_scope_assessment.py +734 -0
- agentic_project_kit/dpa_probe_002_readiness.py +509 -0
- agentic_project_kit/dpa_probe_003_readiness.py +417 -0
- agentic_project_kit/dpa_probe_004_readiness.py +437 -0
- agentic_project_kit/dpa_readiness.py +505 -0
- agentic_project_kit/dpa_readonly_probe_execution.py +500 -0
- agentic_project_kit/dpa_registry_contracts.py +312 -0
- agentic_project_kit/dpa_renderer_readiness.py +407 -0
- agentic_project_kit/dpa_repo_adoption_assessment.py +574 -0
- agentic_project_kit/dpa_stable_readiness.py +743 -0
- agentic_project_kit/dpa_successor_projection.py +168 -0
- agentic_project_kit/dpa_workspace_init_projection.py +93 -0
- agentic_project_kit/dpa_wrt_ch001_evidence.py +327 -0
- agentic_project_kit/entrypoint_slice_runner.py +153 -0
- agentic_project_kit/evidence_clean.py +152 -0
- agentic_project_kit/evidence_commit_paths.py +214 -0
- agentic_project_kit/evidence_finalize_log.py +204 -0
- agentic_project_kit/evidence_guard.py +114 -0
- agentic_project_kit/evidence_inspector.py +507 -0
- agentic_project_kit/evidence_state_contract.py +99 -0
- agentic_project_kit/execution_mode_state.py +148 -0
- agentic_project_kit/final_summary_contract.py +85 -0
- agentic_project_kit/finalize_guard.py +139 -0
- agentic_project_kit/gatekeeper_core.py +232 -0
- agentic_project_kit/github.py +25 -0
- agentic_project_kit/governance.py +59 -0
- agentic_project_kit/gui_action_execution.py +105 -0
- agentic_project_kit/gui_action_renderer.py +81 -0
- agentic_project_kit/gui_action_run_intent.py +98 -0
- agentic_project_kit/gui_action_views.py +195 -0
- agentic_project_kit/gui_activity_log.py +76 -0
- agentic_project_kit/gui_button_catalog.py +605 -0
- agentic_project_kit/gui_cockpit.py +365 -0
- agentic_project_kit/gui_cockpit_actions.py +695 -0
- agentic_project_kit/gui_cockpit_common.py +172 -0
- agentic_project_kit/gui_cockpit_header.py +501 -0
- agentic_project_kit/gui_cockpit_sidebar.py +387 -0
- agentic_project_kit/gui_cockpit_task.py +748 -0
- agentic_project_kit/gui_command_projection.py +355 -0
- agentic_project_kit/gui_communication_modes.py +130 -0
- agentic_project_kit/gui_dry_run.py +219 -0
- agentic_project_kit/gui_gatekeeper_status.py +259 -0
- agentic_project_kit/gui_layout_plan.py +148 -0
- agentic_project_kit/gui_open_folder.py +18 -0
- agentic_project_kit/gui_output_status_panel.py +61 -0
- agentic_project_kit/gui_panel_state.py +47 -0
- agentic_project_kit/gui_presenter.py +62 -0
- agentic_project_kit/gui_readiness_gate.py +206 -0
- agentic_project_kit/gui_release_flow.py +59 -0
- agentic_project_kit/gui_task_editor.py +1077 -0
- agentic_project_kit/gui_tk_widgets.py +177 -0
- agentic_project_kit/gui_tkinter_renderer.py +87 -0
- agentic_project_kit/gui_tkinter_shell.py +1176 -0
- agentic_project_kit/gui_transfer_contract.py +28 -0
- agentic_project_kit/gui_viewmodel.py +698 -0
- agentic_project_kit/gui_window_guard.py +46 -0
- agentic_project_kit/handoff_freshness.py +390 -0
- agentic_project_kit/handoff_prompt.py +180 -0
- agentic_project_kit/handoff_state.py +254 -0
- agentic_project_kit/instruction_lint.py +455 -0
- agentic_project_kit/llm_context_carriers.py +66 -0
- agentic_project_kit/llm_execution_context.py +285 -0
- agentic_project_kit/local_command_stack.py +133 -0
- agentic_project_kit/local_feature_gate.py +82 -0
- agentic_project_kit/local_garbage_collector.py +269 -0
- agentic_project_kit/models.py +18 -0
- agentic_project_kit/mutation_lock_audit.py +421 -0
- agentic_project_kit/next_turn_evidence.py +253 -0
- agentic_project_kit/next_turn_merge_if_green.py +459 -0
- agentic_project_kit/next_turn_pr_status.py +255 -0
- agentic_project_kit/next_turn_result.py +183 -0
- agentic_project_kit/next_turn_runner.py +159 -0
- agentic_project_kit/next_turn_slot.py +107 -0
- agentic_project_kit/next_turn_status.py +274 -0
- agentic_project_kit/ns_legacy_reference_audit.py +258 -0
- agentic_project_kit/ns_slice_runner.py +16 -0
- agentic_project_kit/operational_handoff_projection.py +124 -0
- agentic_project_kit/output_contract.py +80 -0
- agentic_project_kit/output_repair.py +61 -0
- agentic_project_kit/pass_already_done.py +216 -0
- agentic_project_kit/patch_artifact_preflight.py +147 -0
- agentic_project_kit/patch_cycle_workflow.py +440 -0
- agentic_project_kit/patch_failure_discipline_audit.py +223 -0
- agentic_project_kit/patch_preflight.py +215 -0
- agentic_project_kit/path_literal_audit.py +612 -0
- agentic_project_kit/patterns.py +99 -0
- agentic_project_kit/planning_docs_consolidation_audit.py +313 -0
- agentic_project_kit/portability_shell_gate.py +40 -0
- agentic_project_kit/post_merge_handoff_refresh.py +56 -0
- agentic_project_kit/post_release.py +252 -0
- agentic_project_kit/post_release_closeout.py +616 -0
- agentic_project_kit/pr_cleanup.py +172 -0
- agentic_project_kit/pr_closeout.py +50 -0
- agentic_project_kit/pr_closeout_complete.py +344 -0
- agentic_project_kit/pr_create_or_skip.py +71 -0
- agentic_project_kit/pr_hygiene.py +210 -0
- agentic_project_kit/program_redundancy_audit.py +251 -0
- agentic_project_kit/project_direction.py +840 -0
- agentic_project_kit/protected_change_planner.py +194 -0
- agentic_project_kit/release.py +401 -0
- agentic_project_kit/release_doi_safety.py +24 -0
- agentic_project_kit/release_gate_core.py +174 -0
- agentic_project_kit/release_metadata_authority_gate.py +328 -0
- agentic_project_kit/release_metadata_prep.py +43 -0
- agentic_project_kit/release_notes.py +823 -0
- agentic_project_kit/release_prep_core.py +204 -0
- agentic_project_kit/release_prepare.py +369 -0
- agentic_project_kit/release_process_guardrails.py +247 -0
- agentic_project_kit/release_publish_core.py +114 -0
- agentic_project_kit/release_publish_orchestration.py +469 -0
- agentic_project_kit/release_state.py +552 -0
- agentic_project_kit/release_verify_core.py +175 -0
- agentic_project_kit/remote_branch_hygiene.py +223 -0
- agentic_project_kit/remote_next.py +89 -0
- agentic_project_kit/remote_next_closeout.py +101 -0
- agentic_project_kit/remote_next_order_contract.py +391 -0
- agentic_project_kit/removed_ns_commands.py +458 -0
- agentic_project_kit/removed_source_audit.py +225 -0
- agentic_project_kit/rendering.py +13 -0
- agentic_project_kit/repair_report.py +79 -0
- agentic_project_kit/repo_identity.py +59 -0
- agentic_project_kit/result_report_classifier.py +57 -0
- agentic_project_kit/rule_ack.py +105 -0
- agentic_project_kit/rule_preservation.py +58 -0
- agentic_project_kit/rule_refresh.py +174 -0
- agentic_project_kit/rule_registry_registration.py +322 -0
- agentic_project_kit/rule_registry_report.py +206 -0
- agentic_project_kit/rule_registry_validator.py +704 -0
- agentic_project_kit/rule_snapshot.py +98 -0
- agentic_project_kit/rule_source_validator.py +133 -0
- agentic_project_kit/run_summary.py +68 -0
- agentic_project_kit/run_summary_renderer.py +238 -0
- agentic_project_kit/runtime_validator.py +68 -0
- agentic_project_kit/safe_file_replace.py +35 -0
- agentic_project_kit/safe_patch.py +47 -0
- agentic_project_kit/safe_push.py +218 -0
- agentic_project_kit/safe_remove_diagnostic.py +51 -0
- agentic_project_kit/scaffold.py +69 -0
- agentic_project_kit/site_claims.py +444 -0
- agentic_project_kit/site_generator.py +1140 -0
- agentic_project_kit/slice_gate.py +225 -0
- agentic_project_kit/slice_runner.py +75 -0
- agentic_project_kit/standard_gates_audit_suite.py +167 -0
- agentic_project_kit/state_freshness.py +135 -0
- agentic_project_kit/status_current_state_audit.py +762 -0
- agentic_project_kit/successor_handoff_package.py +1763 -0
- agentic_project_kit/templates.py +292 -0
- agentic_project_kit/terminal_block_guard.py +166 -0
- agentic_project_kit/terminal_logging.py +275 -0
- agentic_project_kit/todo.py +97 -0
- agentic_project_kit/transfer_closeout.py +136 -0
- agentic_project_kit/transfer_continue.py +215 -0
- agentic_project_kit/transfer_local_runner.py +101 -0
- agentic_project_kit/transfer_operation_monitor.py +236 -0
- agentic_project_kit/transfer_post_merge_lifecycle.py +356 -0
- agentic_project_kit/transfer_post_merge_settle.py +383 -0
- agentic_project_kit/transfer_pr_actions.py +164 -0
- agentic_project_kit/transfer_remote_next.py +959 -0
- agentic_project_kit/transfer_repo_actions.py +2253 -0
- agentic_project_kit/transfer_runner.py +347 -0
- agentic_project_kit/transfer_safety_context.py +291 -0
- agentic_project_kit/transfer_state.py +483 -0
- agentic_project_kit/transfer_uplink.py +471 -0
- agentic_project_kit/transfer_workflow_next.py +148 -0
- agentic_project_kit/typed_work_order_evidence.py +58 -0
- agentic_project_kit/typed_work_order_queue.py +166 -0
- agentic_project_kit/typed_work_order_runner.py +168 -0
- agentic_project_kit/work_cycle.py +317 -0
- agentic_project_kit/work_discard_changes.py +129 -0
- agentic_project_kit/work_order_patch.py +199 -0
- agentic_project_kit/work_order_runner.py +120 -0
- agentic_project_kit/work_order_uploader.py +220 -0
- agentic_project_kit/work_order_validator.py +185 -0
- agentic_project_kit/work_orders.py +246 -0
- agentic_project_kit/workflow_guard.py +262 -0
- agentic_project_kit/workflow_summary_runner.py +124 -0
- agentic_project_kit/workspace.py +665 -0
- agentic_project_kit/workspace_adopt.py +471 -0
- agentic_project_kit/workspace_dpa_intake.py +406 -0
- agentic_project_kit/workspace_init.py +487 -0
- agentic_project_kit/workspace_lock.py +129 -0
- agentic_project_kit/workspace_remove.py +381 -0
- agentic_project_kit/workspace_upgrade.py +324 -0
- agentic_project_kit/wrapper_live_status.py +104 -0
- agentic_project_kit-1.0.1.dist-info/METADATA +724 -0
- agentic_project_kit-1.0.1.dist-info/RECORD +310 -0
- agentic_project_kit-1.0.1.dist-info/WHEEL +4 -0
- agentic_project_kit-1.0.1.dist-info/entry_points.txt +3 -0
- agentic_project_kit-1.0.1.dist-info/licenses/LICENSE +10 -0
|
@@ -0,0 +1,840 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
import json
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
import re
|
|
7
|
+
from typing import Any, Literal
|
|
8
|
+
|
|
9
|
+
try:
|
|
10
|
+
import tomllib
|
|
11
|
+
except ModuleNotFoundError: # pragma: no cover - Python 3.10 fallback
|
|
12
|
+
tomllib = None # type: ignore[assignment]
|
|
13
|
+
|
|
14
|
+
import yaml
|
|
15
|
+
|
|
16
|
+
from agentic_project_kit.workspace import KitConfig, load_workspace
|
|
17
|
+
|
|
18
|
+
_DEFAULT_CONFIG = KitConfig()
|
|
19
|
+
PROJECT_DIRECTION_PATH = Path(_DEFAULT_CONFIG.planning_root) / _DEFAULT_CONFIG.project_direction_file
|
|
20
|
+
VALID_SECTIONS = ("all", "strategy", "roadmap", "plans", "ideas", "done", "discarded")
|
|
21
|
+
VALID_FORMATS = ("text", "markdown", "json")
|
|
22
|
+
ALLOWED_TOP_LEVEL_KEYS = frozenset(
|
|
23
|
+
{"schema_version", "meta", "strategy", "roadmap", "plans", "ideas", "done", "discarded"}
|
|
24
|
+
)
|
|
25
|
+
SECTION_STATUS_VALUES = {
|
|
26
|
+
"strategy": frozenset({"active", "superseded", "done", "discarded"}),
|
|
27
|
+
"roadmap": frozenset({"next", "planned", "blocked", "done", "discarded"}),
|
|
28
|
+
"plans": frozenset({"active", "planned", "blocked", "done", "discarded"}),
|
|
29
|
+
"ideas": frozenset({"candidate", "accepted", "rejected", "superseded"}),
|
|
30
|
+
}
|
|
31
|
+
ACTIVE_STATUSES = frozenset({"active", "next", "planned", "blocked", "candidate", "accepted"})
|
|
32
|
+
UPDATED_AFTER_PR_SEMANTICS = frozenset({"strategic_direction_refresh"})
|
|
33
|
+
PLANNING_SCAN_ROOTS = (
|
|
34
|
+
Path(_DEFAULT_CONFIG.docs_root) / "strategy",
|
|
35
|
+
Path(_DEFAULT_CONFIG.planning_root),
|
|
36
|
+
Path(_DEFAULT_CONFIG.docs_root) / "plans",
|
|
37
|
+
Path(_DEFAULT_CONFIG.docs_root) / "ideas",
|
|
38
|
+
Path(_DEFAULT_CONFIG.docs_root) / "roadmap",
|
|
39
|
+
)
|
|
40
|
+
CANONICAL_DIRECTION_FILES = {
|
|
41
|
+
"docs/planning/PROJECT_DIRECTION.yaml",
|
|
42
|
+
"docs/planning/PROJECT_DIRECTION.md",
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True)
|
|
47
|
+
class ProjectDirection:
|
|
48
|
+
data: dict[str, Any]
|
|
49
|
+
path: Path
|
|
50
|
+
authority_path: str = PROJECT_DIRECTION_PATH.as_posix()
|
|
51
|
+
|
|
52
|
+
def validate(self) -> list[str]:
|
|
53
|
+
result = validate_project_direction_data(
|
|
54
|
+
self.data,
|
|
55
|
+
root=self.path.parent.parent.parent,
|
|
56
|
+
authority_path=self.authority_path,
|
|
57
|
+
)
|
|
58
|
+
return [finding.message for finding in result.findings]
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass(frozen=True)
|
|
62
|
+
class DirectionFinding:
|
|
63
|
+
code: str
|
|
64
|
+
message: str
|
|
65
|
+
path: str = "docs/planning/PROJECT_DIRECTION.yaml"
|
|
66
|
+
|
|
67
|
+
def as_dict(self) -> dict[str, str]:
|
|
68
|
+
return {"code": self.code, "message": self.message, "path": self.path}
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
@dataclass(frozen=True)
|
|
72
|
+
class DirectionValidationResult:
|
|
73
|
+
path: str
|
|
74
|
+
findings: tuple[DirectionFinding, ...]
|
|
75
|
+
|
|
76
|
+
@property
|
|
77
|
+
def ok(self) -> bool:
|
|
78
|
+
return not self.findings
|
|
79
|
+
|
|
80
|
+
@property
|
|
81
|
+
def status(self) -> str:
|
|
82
|
+
return "PASS" if self.ok else "FAIL"
|
|
83
|
+
|
|
84
|
+
@property
|
|
85
|
+
def returncode(self) -> int:
|
|
86
|
+
return 0 if self.ok else 1
|
|
87
|
+
|
|
88
|
+
def as_dict(self) -> dict[str, object]:
|
|
89
|
+
return {
|
|
90
|
+
"schema_version": 1,
|
|
91
|
+
"kind": "project_direction_validation",
|
|
92
|
+
"status": self.status,
|
|
93
|
+
"path": self.path,
|
|
94
|
+
"finding_count": len(self.findings),
|
|
95
|
+
"findings": [finding.as_dict() for finding in self.findings],
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
@dataclass(frozen=True)
|
|
100
|
+
class DirectionDriftRecord:
|
|
101
|
+
path: str
|
|
102
|
+
classification: str
|
|
103
|
+
recommendation: str
|
|
104
|
+
in_source_files: bool
|
|
105
|
+
reference_count: int
|
|
106
|
+
item_id: str | None = None
|
|
107
|
+
item_status: str | None = None
|
|
108
|
+
|
|
109
|
+
def as_dict(self) -> dict[str, object]:
|
|
110
|
+
data: dict[str, object] = {
|
|
111
|
+
"path": self.path,
|
|
112
|
+
"classification": self.classification,
|
|
113
|
+
"recommendation": self.recommendation,
|
|
114
|
+
"in_source_files": self.in_source_files,
|
|
115
|
+
"reference_count": self.reference_count,
|
|
116
|
+
}
|
|
117
|
+
if self.item_id is not None:
|
|
118
|
+
data["item_id"] = self.item_id
|
|
119
|
+
if self.item_status is not None:
|
|
120
|
+
data["item_status"] = self.item_status
|
|
121
|
+
return data
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@dataclass(frozen=True)
|
|
125
|
+
class DirectionDriftAuditResult:
|
|
126
|
+
root: str
|
|
127
|
+
records: tuple[DirectionDriftRecord, ...]
|
|
128
|
+
missing_source_files: tuple[str, ...]
|
|
129
|
+
|
|
130
|
+
@property
|
|
131
|
+
def ok(self) -> bool:
|
|
132
|
+
return True
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def status(self) -> str:
|
|
136
|
+
return "PASS"
|
|
137
|
+
|
|
138
|
+
@property
|
|
139
|
+
def returncode(self) -> int:
|
|
140
|
+
return 0
|
|
141
|
+
|
|
142
|
+
def as_dict(self) -> dict[str, object]:
|
|
143
|
+
return {
|
|
144
|
+
"schema_version": 1,
|
|
145
|
+
"kind": "project_direction_drift_audit",
|
|
146
|
+
"root": self.root,
|
|
147
|
+
"status": self.status,
|
|
148
|
+
"record_count": len(self.records),
|
|
149
|
+
"missing_source_file_count": len(self.missing_source_files),
|
|
150
|
+
"missing_source_files": list(self.missing_source_files),
|
|
151
|
+
"records": [record.as_dict() for record in self.records],
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def load_project_direction(root: Path | str = ".") -> ProjectDirection:
|
|
156
|
+
base = Path(root)
|
|
157
|
+
path = load_workspace(base).project_direction_path()
|
|
158
|
+
raw = path.read_text(encoding="utf-8")
|
|
159
|
+
data = yaml.safe_load(raw)
|
|
160
|
+
if not isinstance(data, dict):
|
|
161
|
+
raise ValueError(f"{PROJECT_DIRECTION_PATH.as_posix()} must contain a YAML mapping")
|
|
162
|
+
try:
|
|
163
|
+
authority_path = path.relative_to(base).as_posix()
|
|
164
|
+
except ValueError:
|
|
165
|
+
authority_path = PROJECT_DIRECTION_PATH.as_posix()
|
|
166
|
+
return ProjectDirection(data=data, path=path, authority_path=authority_path)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def validate_project_direction(
|
|
170
|
+
root: Path | str = ".",
|
|
171
|
+
*,
|
|
172
|
+
strict_planning_files: bool = False,
|
|
173
|
+
) -> DirectionValidationResult:
|
|
174
|
+
direction = load_project_direction(root)
|
|
175
|
+
return validate_project_direction_data(
|
|
176
|
+
direction.data,
|
|
177
|
+
root=Path(root),
|
|
178
|
+
authority_path=direction.authority_path,
|
|
179
|
+
strict_planning_files=strict_planning_files,
|
|
180
|
+
)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def validate_project_direction_data(
|
|
184
|
+
data: dict[str, Any],
|
|
185
|
+
*,
|
|
186
|
+
root: Path,
|
|
187
|
+
authority_path: str = PROJECT_DIRECTION_PATH.as_posix(),
|
|
188
|
+
strict_planning_files: bool = False,
|
|
189
|
+
) -> DirectionValidationResult:
|
|
190
|
+
findings: list[DirectionFinding] = []
|
|
191
|
+
root = Path(root)
|
|
192
|
+
|
|
193
|
+
for key in data:
|
|
194
|
+
if key not in ALLOWED_TOP_LEVEL_KEYS:
|
|
195
|
+
findings.append(DirectionFinding("unknown-top-level-key", f"unknown top-level key: {key}"))
|
|
196
|
+
for key in ALLOWED_TOP_LEVEL_KEYS:
|
|
197
|
+
if key not in data:
|
|
198
|
+
findings.append(DirectionFinding("missing-required-key", f"missing required key: {key}"))
|
|
199
|
+
if data.get("schema_version") != 1:
|
|
200
|
+
findings.append(DirectionFinding("invalid-schema-version", "schema_version must be 1"))
|
|
201
|
+
|
|
202
|
+
meta = data.get("meta")
|
|
203
|
+
if not isinstance(meta, dict):
|
|
204
|
+
findings.append(DirectionFinding("invalid-meta", "meta must be a mapping"))
|
|
205
|
+
else:
|
|
206
|
+
if meta.get("status") != "active":
|
|
207
|
+
findings.append(DirectionFinding("invalid-meta-status", "meta.status must be active"))
|
|
208
|
+
if meta.get("authority") != authority_path:
|
|
209
|
+
findings.append(
|
|
210
|
+
DirectionFinding("invalid-authority", f"meta.authority must be {authority_path}")
|
|
211
|
+
)
|
|
212
|
+
if meta.get("updated_after_pr") is not None:
|
|
213
|
+
semantics = meta.get("updated_after_pr_semantics")
|
|
214
|
+
if semantics not in UPDATED_AFTER_PR_SEMANTICS:
|
|
215
|
+
findings.append(
|
|
216
|
+
DirectionFinding(
|
|
217
|
+
"invalid-updated-after-pr-semantics",
|
|
218
|
+
"meta.updated_after_pr_semantics must be strategic_direction_refresh "
|
|
219
|
+
"when meta.updated_after_pr is set",
|
|
220
|
+
)
|
|
221
|
+
)
|
|
222
|
+
if meta.get("updated_after_pr_current_main_claimed") is not False:
|
|
223
|
+
findings.append(
|
|
224
|
+
DirectionFinding(
|
|
225
|
+
"invalid-updated-after-pr-current-main-claim",
|
|
226
|
+
"meta.updated_after_pr_current_main_claimed must be false; "
|
|
227
|
+
"PROJECT_DIRECTION updated_after_pr is not a current-main freshness claim",
|
|
228
|
+
)
|
|
229
|
+
)
|
|
230
|
+
|
|
231
|
+
ids_by_section: dict[str, str] = {}
|
|
232
|
+
dependency_checks: list[tuple[str, str]] = []
|
|
233
|
+
source_files = _collect_source_file_entries(data)
|
|
234
|
+
_validate_no_private_absolute_paths(data, findings)
|
|
235
|
+
current_release = _read_project_version(root)
|
|
236
|
+
|
|
237
|
+
for section in ("strategy", "roadmap", "plans", "ideas", "done", "discarded"):
|
|
238
|
+
raw_items = data.get(section)
|
|
239
|
+
if not isinstance(raw_items, list):
|
|
240
|
+
findings.append(DirectionFinding("invalid-section", f"{section} must be a list"))
|
|
241
|
+
continue
|
|
242
|
+
for index, item in enumerate(raw_items):
|
|
243
|
+
path = f"{section}[{index}]"
|
|
244
|
+
if not isinstance(item, dict):
|
|
245
|
+
findings.append(DirectionFinding("invalid-item", f"{path} must be a mapping"))
|
|
246
|
+
continue
|
|
247
|
+
item_id = str(item.get("id") or "").strip()
|
|
248
|
+
if not item_id:
|
|
249
|
+
findings.append(DirectionFinding("missing-id", f"{path}.id must not be empty"))
|
|
250
|
+
elif item_id in ids_by_section:
|
|
251
|
+
findings.append(
|
|
252
|
+
DirectionFinding(
|
|
253
|
+
"duplicate-id",
|
|
254
|
+
f"id {item_id!r} appears in both {ids_by_section[item_id]} and {path}",
|
|
255
|
+
)
|
|
256
|
+
)
|
|
257
|
+
else:
|
|
258
|
+
ids_by_section[item_id] = path
|
|
259
|
+
if section in SECTION_STATUS_VALUES:
|
|
260
|
+
status = str(item.get("status") or "").strip()
|
|
261
|
+
allowed = SECTION_STATUS_VALUES[section]
|
|
262
|
+
if status not in allowed:
|
|
263
|
+
findings.append(
|
|
264
|
+
DirectionFinding(
|
|
265
|
+
"invalid-status",
|
|
266
|
+
f"{path}.status must be one of {', '.join(sorted(allowed))}",
|
|
267
|
+
)
|
|
268
|
+
)
|
|
269
|
+
if status in ACTIVE_STATUSES and not str(item.get("title") or "").strip():
|
|
270
|
+
findings.append(DirectionFinding("empty-active-title", f"{path}.title must not be empty"))
|
|
271
|
+
_validate_target_release_currency(
|
|
272
|
+
item,
|
|
273
|
+
path,
|
|
274
|
+
status=status,
|
|
275
|
+
current_release=current_release,
|
|
276
|
+
findings=findings,
|
|
277
|
+
)
|
|
278
|
+
if section in {"roadmap", "plans"}:
|
|
279
|
+
for dependency in _string_list(item.get("depends_on"), f"{path}.depends_on", findings):
|
|
280
|
+
dependency_checks.append((path, dependency))
|
|
281
|
+
if section == "done":
|
|
282
|
+
if item.get("completed_by_pr") is None and not str(item.get("completion_exception") or "").strip():
|
|
283
|
+
findings.append(
|
|
284
|
+
DirectionFinding(
|
|
285
|
+
"done-missing-completion",
|
|
286
|
+
f"{path} needs completed_by_pr or completion_exception",
|
|
287
|
+
)
|
|
288
|
+
)
|
|
289
|
+
if section == "discarded" and not str(item.get("reason") or "").strip():
|
|
290
|
+
findings.append(DirectionFinding("discarded-missing-reason", f"{path}.reason must not be empty"))
|
|
291
|
+
_validate_item_sources(item, path, root, findings)
|
|
292
|
+
_validate_item_evidence(item, path, root, findings)
|
|
293
|
+
|
|
294
|
+
for path, dependency in dependency_checks:
|
|
295
|
+
if dependency not in ids_by_section:
|
|
296
|
+
findings.append(
|
|
297
|
+
DirectionFinding("unknown-dependency", f"{path}.depends_on references unknown id {dependency!r}")
|
|
298
|
+
)
|
|
299
|
+
|
|
300
|
+
if strict_planning_files:
|
|
301
|
+
referenced = {entry for entry in source_files if isinstance(entry, str)}
|
|
302
|
+
for candidate in _iter_planning_files(root):
|
|
303
|
+
if candidate in CANONICAL_DIRECTION_FILES:
|
|
304
|
+
continue
|
|
305
|
+
if candidate.startswith("docs/planning/") and candidate not in referenced:
|
|
306
|
+
findings.append(
|
|
307
|
+
DirectionFinding(
|
|
308
|
+
"forbidden-free-planning-file",
|
|
309
|
+
f"{candidate} is not a canonical direction file or referenced source",
|
|
310
|
+
)
|
|
311
|
+
)
|
|
312
|
+
|
|
313
|
+
return DirectionValidationResult(path=authority_path, findings=tuple(findings))
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
def render_project_direction(
|
|
317
|
+
direction: ProjectDirection,
|
|
318
|
+
*,
|
|
319
|
+
section: Literal["all", "strategy", "roadmap", "plans", "ideas", "done", "discarded"] = "all",
|
|
320
|
+
output_format: Literal["text", "markdown", "json"] = "text",
|
|
321
|
+
) -> str:
|
|
322
|
+
findings = direction.validate()
|
|
323
|
+
if findings:
|
|
324
|
+
raise ValueError("; ".join(findings))
|
|
325
|
+
|
|
326
|
+
if output_format == "json":
|
|
327
|
+
if section == "all":
|
|
328
|
+
payload: Any = direction.data
|
|
329
|
+
else:
|
|
330
|
+
payload = {section: direction.data[section]}
|
|
331
|
+
return json.dumps(payload, default=str, indent=2, sort_keys=True) + "\n"
|
|
332
|
+
|
|
333
|
+
if output_format == "markdown":
|
|
334
|
+
return _render_markdown(direction.data, section)
|
|
335
|
+
|
|
336
|
+
return _render_text(direction.data, section)
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def audit_project_direction_drift(root: Path | str = ".") -> DirectionDriftAuditResult:
|
|
340
|
+
root_path = Path(root)
|
|
341
|
+
direction = load_project_direction(root_path)
|
|
342
|
+
source_files = {
|
|
343
|
+
entry
|
|
344
|
+
for entry in _collect_source_file_entries(direction.data)
|
|
345
|
+
if isinstance(entry, str) and entry not in CANONICAL_DIRECTION_FILES
|
|
346
|
+
}
|
|
347
|
+
existing_sources = {entry for entry in source_files if (root_path / entry).exists()}
|
|
348
|
+
missing_sources = tuple(sorted(entry for entry in source_files if not (root_path / entry).exists()))
|
|
349
|
+
|
|
350
|
+
records: list[DirectionDriftRecord] = []
|
|
351
|
+
reference_counts = _reference_counts(root_path, set(_iter_planning_files(root_path)) | source_files)
|
|
352
|
+
for relative in _iter_planning_files(root_path):
|
|
353
|
+
if relative in CANONICAL_DIRECTION_FILES:
|
|
354
|
+
classification = "canonical_direction"
|
|
355
|
+
recommendation = "keep"
|
|
356
|
+
elif relative in existing_sources:
|
|
357
|
+
classification = "listed_source"
|
|
358
|
+
recommendation = "migrate_or_retain_until_slice_cleanup"
|
|
359
|
+
elif reference_counts.get(relative, 0):
|
|
360
|
+
classification = "unlisted_referenced_file"
|
|
361
|
+
recommendation = "migrate_or_reference_clean_before_delete"
|
|
362
|
+
else:
|
|
363
|
+
classification = "unlisted_unreferenced_file"
|
|
364
|
+
recommendation = "safe_delete_candidate_after_review"
|
|
365
|
+
records.append(
|
|
366
|
+
DirectionDriftRecord(
|
|
367
|
+
path=relative,
|
|
368
|
+
classification=classification,
|
|
369
|
+
recommendation=recommendation,
|
|
370
|
+
in_source_files=relative in source_files,
|
|
371
|
+
reference_count=reference_counts.get(relative, 0),
|
|
372
|
+
)
|
|
373
|
+
)
|
|
374
|
+
records.extend(_closed_item_active_source_records(direction.data, root_path, reference_counts))
|
|
375
|
+
records.extend(_open_release_planning_drift_records(direction.data, root_path, direction.authority_path))
|
|
376
|
+
return DirectionDriftAuditResult(
|
|
377
|
+
root=root_path.resolve().as_posix(),
|
|
378
|
+
records=tuple(sorted(records, key=lambda record: record.path)),
|
|
379
|
+
missing_source_files=missing_sources,
|
|
380
|
+
)
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
def render_direction_validation(result: DirectionValidationResult) -> str:
|
|
384
|
+
lines = [
|
|
385
|
+
"PROJECT_DIRECTION_VALIDATE",
|
|
386
|
+
f"STATUS={result.status}",
|
|
387
|
+
f"FINDING_COUNT={len(result.findings)}",
|
|
388
|
+
]
|
|
389
|
+
for finding in result.findings:
|
|
390
|
+
lines.append(f"FINDING={finding.code}|{finding.path}|{finding.message}")
|
|
391
|
+
return "\n".join(lines) + "\n"
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def render_direction_drift_audit(result: DirectionDriftAuditResult) -> str:
|
|
395
|
+
lines = [
|
|
396
|
+
"PROJECT_DIRECTION_DRIFT_AUDIT",
|
|
397
|
+
f"STATUS={result.status}",
|
|
398
|
+
f"RECORD_COUNT={len(result.records)}",
|
|
399
|
+
f"MISSING_SOURCE_FILE_COUNT={len(result.missing_source_files)}",
|
|
400
|
+
]
|
|
401
|
+
for missing in result.missing_source_files:
|
|
402
|
+
lines.append(f"MISSING_SOURCE={missing}")
|
|
403
|
+
for record in result.records:
|
|
404
|
+
item_suffix = (
|
|
405
|
+
f"|item={record.item_id}|item_status={record.item_status}"
|
|
406
|
+
if record.item_id is not None
|
|
407
|
+
else ""
|
|
408
|
+
)
|
|
409
|
+
lines.append(
|
|
410
|
+
"RECORD="
|
|
411
|
+
f"{record.classification}|{record.recommendation}|{record.path}|"
|
|
412
|
+
f"source={record.in_source_files}|refs={record.reference_count}"
|
|
413
|
+
f"{item_suffix}"
|
|
414
|
+
)
|
|
415
|
+
return "\n".join(lines) + "\n"
|
|
416
|
+
|
|
417
|
+
|
|
418
|
+
def _render_text(data: dict[str, Any], section: str) -> str:
|
|
419
|
+
meta = data.get("meta", {})
|
|
420
|
+
lines: list[str] = [
|
|
421
|
+
"PROJECT DIRECTION",
|
|
422
|
+
f"Status: {meta.get('status')}",
|
|
423
|
+
f"{_updated_after_pr_render_label(meta)}: {meta.get('updated_after_pr')}",
|
|
424
|
+
f"Authority: {meta.get('authority')}",
|
|
425
|
+
"",
|
|
426
|
+
]
|
|
427
|
+
if section in {"all", "strategy"}:
|
|
428
|
+
_append_strategy_text(lines, data["strategy"])
|
|
429
|
+
if section in {"all", "roadmap"}:
|
|
430
|
+
_append_roadmap_text(lines, data["roadmap"])
|
|
431
|
+
if section in {"all", "plans"}:
|
|
432
|
+
_append_items_text(lines, "Plans", data["plans"])
|
|
433
|
+
if section in {"all", "ideas"}:
|
|
434
|
+
_append_items_text(lines, "Ideas", data["ideas"])
|
|
435
|
+
if section in {"all", "done"}:
|
|
436
|
+
_append_items_text(lines, "Done", data["done"])
|
|
437
|
+
if section in {"all", "discarded"}:
|
|
438
|
+
_append_items_text(lines, "Discarded", data["discarded"])
|
|
439
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
def _render_markdown(data: dict[str, Any], section: str) -> str:
|
|
443
|
+
meta = data.get("meta", {})
|
|
444
|
+
lines: list[str] = [
|
|
445
|
+
"# Project Direction",
|
|
446
|
+
"",
|
|
447
|
+
f"- Status: `{meta.get('status')}`",
|
|
448
|
+
f"- {_updated_after_pr_render_label(meta)}: `{meta.get('updated_after_pr')}`",
|
|
449
|
+
f"- Authority: `{meta.get('authority')}`",
|
|
450
|
+
"",
|
|
451
|
+
]
|
|
452
|
+
if section in {"all", "strategy"}:
|
|
453
|
+
_append_strategy_markdown(lines, data["strategy"])
|
|
454
|
+
if section in {"all", "roadmap"}:
|
|
455
|
+
_append_roadmap_markdown(lines, data["roadmap"])
|
|
456
|
+
if section in {"all", "plans"}:
|
|
457
|
+
_append_items_markdown(lines, "Plans", data["plans"])
|
|
458
|
+
if section in {"all", "ideas"}:
|
|
459
|
+
_append_items_markdown(lines, "Ideas", data["ideas"])
|
|
460
|
+
if section in {"all", "done"}:
|
|
461
|
+
_append_items_markdown(lines, "Done", data["done"])
|
|
462
|
+
if section in {"all", "discarded"}:
|
|
463
|
+
_append_items_markdown(lines, "Discarded", data["discarded"])
|
|
464
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
465
|
+
|
|
466
|
+
|
|
467
|
+
def _updated_after_pr_render_label(meta: dict[str, Any]) -> str:
|
|
468
|
+
if meta.get("updated_after_pr_semantics") == "strategic_direction_refresh":
|
|
469
|
+
return "Strategic direction updated after PR"
|
|
470
|
+
return "Updated after PR"
|
|
471
|
+
|
|
472
|
+
|
|
473
|
+
def _append_strategy_text(lines: list[str], strategy: list[dict[str, Any]]) -> None:
|
|
474
|
+
lines.append("Strategy")
|
|
475
|
+
for item in strategy:
|
|
476
|
+
lines.append(f"- {item.get('id')}: {item.get('title')} [{item.get('status')}]")
|
|
477
|
+
rationale = item.get("rationale")
|
|
478
|
+
if rationale:
|
|
479
|
+
lines.append(f" {rationale}")
|
|
480
|
+
lines.append("")
|
|
481
|
+
|
|
482
|
+
|
|
483
|
+
def _append_roadmap_text(lines: list[str], roadmap: list[dict[str, Any]]) -> None:
|
|
484
|
+
lines.append("Roadmap")
|
|
485
|
+
for item in roadmap:
|
|
486
|
+
lines.append(
|
|
487
|
+
f"- {item.get('id')}: {item.get('title')} "
|
|
488
|
+
f"[{item.get('phase')}/{item.get('status')}]"
|
|
489
|
+
)
|
|
490
|
+
lines.append("")
|
|
491
|
+
|
|
492
|
+
|
|
493
|
+
def _append_items_text(lines: list[str], title: str, items: list[dict[str, Any]]) -> None:
|
|
494
|
+
lines.append(title)
|
|
495
|
+
for item in items:
|
|
496
|
+
detail = item.get("rationale") or item.get("reason") or item.get("title") or ""
|
|
497
|
+
lines.append(f"- {item.get('id')}: {item.get('title')} [{item.get('status', item.get('completed_by_pr'))}]")
|
|
498
|
+
if detail and detail != item.get("title"):
|
|
499
|
+
lines.append(f" {detail}")
|
|
500
|
+
lines.append("")
|
|
501
|
+
|
|
502
|
+
|
|
503
|
+
def _append_strategy_markdown(lines: list[str], strategy: list[dict[str, Any]]) -> None:
|
|
504
|
+
lines.append("## Strategy")
|
|
505
|
+
lines.append("")
|
|
506
|
+
for item in strategy:
|
|
507
|
+
lines.append(f"- `{item.get('id')}` - **{item.get('title')}** (`{item.get('status')}`)")
|
|
508
|
+
if item.get("rationale"):
|
|
509
|
+
lines.append(f" {item.get('rationale')}")
|
|
510
|
+
lines.append("")
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
def _append_roadmap_markdown(lines: list[str], roadmap: list[dict[str, Any]]) -> None:
|
|
514
|
+
lines.append("## Roadmap")
|
|
515
|
+
lines.append("")
|
|
516
|
+
for item in roadmap:
|
|
517
|
+
lines.append(
|
|
518
|
+
f"- `{item.get('id')}` - **{item.get('title')}** "
|
|
519
|
+
f"(`{item.get('phase')}`, `{item.get('status')}`)"
|
|
520
|
+
)
|
|
521
|
+
lines.append("")
|
|
522
|
+
|
|
523
|
+
|
|
524
|
+
def _append_items_markdown(lines: list[str], title: str, items: list[dict[str, Any]]) -> None:
|
|
525
|
+
lines.append(f"## {title}")
|
|
526
|
+
lines.append("")
|
|
527
|
+
for item in items:
|
|
528
|
+
status = item.get("status", item.get("completed_by_pr"))
|
|
529
|
+
detail = item.get("rationale") or item.get("reason") or ""
|
|
530
|
+
lines.append(f"- `{item.get('id')}` - **{item.get('title')}** (`{status}`)")
|
|
531
|
+
if detail:
|
|
532
|
+
lines.append(f" {detail}")
|
|
533
|
+
lines.append("")
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def _string_list(value: object, path: str, findings: list[DirectionFinding]) -> list[str]:
|
|
537
|
+
if value in (None, []):
|
|
538
|
+
return []
|
|
539
|
+
if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
|
|
540
|
+
findings.append(DirectionFinding("invalid-string-list", f"{path} must be a list of strings"))
|
|
541
|
+
return []
|
|
542
|
+
return [item for item in value if item]
|
|
543
|
+
|
|
544
|
+
|
|
545
|
+
def _collect_source_file_entries(data: object) -> list[object]:
|
|
546
|
+
entries: list[object] = []
|
|
547
|
+
if isinstance(data, dict):
|
|
548
|
+
source_files = data.get("source_files")
|
|
549
|
+
if isinstance(source_files, list):
|
|
550
|
+
entries.extend(source_files)
|
|
551
|
+
for value in data.values():
|
|
552
|
+
entries.extend(_collect_source_file_entries(value))
|
|
553
|
+
elif isinstance(data, list):
|
|
554
|
+
for item in data:
|
|
555
|
+
entries.extend(_collect_source_file_entries(item))
|
|
556
|
+
return entries
|
|
557
|
+
|
|
558
|
+
|
|
559
|
+
def _closed_item_active_source_records(
|
|
560
|
+
data: dict[str, Any],
|
|
561
|
+
root: Path,
|
|
562
|
+
reference_counts: dict[str, int],
|
|
563
|
+
) -> list[DirectionDriftRecord]:
|
|
564
|
+
records: list[DirectionDriftRecord] = []
|
|
565
|
+
for section in ("strategy", "roadmap", "plans", "ideas", "done", "discarded"):
|
|
566
|
+
items = data.get(section)
|
|
567
|
+
if not isinstance(items, list):
|
|
568
|
+
continue
|
|
569
|
+
for item in items:
|
|
570
|
+
if not isinstance(item, dict):
|
|
571
|
+
continue
|
|
572
|
+
item_id = item.get("id")
|
|
573
|
+
if not isinstance(item_id, str) or not item_id:
|
|
574
|
+
continue
|
|
575
|
+
status = _direction_item_status(section, item)
|
|
576
|
+
if status not in {"done", "discarded"}:
|
|
577
|
+
continue
|
|
578
|
+
source_files = item.get("source_files")
|
|
579
|
+
if not isinstance(source_files, list):
|
|
580
|
+
continue
|
|
581
|
+
for source in source_files:
|
|
582
|
+
if not isinstance(source, str) or not source.endswith(".md"):
|
|
583
|
+
continue
|
|
584
|
+
if _markdown_status(root / source) != "active":
|
|
585
|
+
continue
|
|
586
|
+
records.append(
|
|
587
|
+
DirectionDriftRecord(
|
|
588
|
+
path=source,
|
|
589
|
+
classification="SOURCE_OF_CLOSED_ITEM_STILL_ACTIVE",
|
|
590
|
+
recommendation="retire_source_header_or_reopen_direction_item",
|
|
591
|
+
in_source_files=True,
|
|
592
|
+
reference_count=reference_counts.get(source, 0),
|
|
593
|
+
item_id=item_id,
|
|
594
|
+
item_status=status,
|
|
595
|
+
)
|
|
596
|
+
)
|
|
597
|
+
return records
|
|
598
|
+
|
|
599
|
+
|
|
600
|
+
def _open_release_planning_drift_records(
|
|
601
|
+
data: dict[str, Any],
|
|
602
|
+
root: Path,
|
|
603
|
+
authority_path: str,
|
|
604
|
+
) -> list[DirectionDriftRecord]:
|
|
605
|
+
current_release = _read_project_version(root)
|
|
606
|
+
if not current_release:
|
|
607
|
+
return []
|
|
608
|
+
current_tuple = _release_tuple(current_release)
|
|
609
|
+
records: list[DirectionDriftRecord] = []
|
|
610
|
+
for section in ("roadmap", "plans"):
|
|
611
|
+
items = data.get(section)
|
|
612
|
+
if not isinstance(items, list):
|
|
613
|
+
continue
|
|
614
|
+
for item in items:
|
|
615
|
+
if not isinstance(item, dict):
|
|
616
|
+
continue
|
|
617
|
+
item_id = item.get("id")
|
|
618
|
+
status = _direction_item_status(section, item)
|
|
619
|
+
if not isinstance(item_id, str) or not item_id or status not in ACTIVE_STATUSES:
|
|
620
|
+
continue
|
|
621
|
+
release_evidence_count = _current_release_evidence_count(item, current_release)
|
|
622
|
+
if release_evidence_count:
|
|
623
|
+
records.append(
|
|
624
|
+
DirectionDriftRecord(
|
|
625
|
+
path=authority_path,
|
|
626
|
+
classification="OPEN_ITEM_REFERENCES_CURRENT_RELEASE",
|
|
627
|
+
recommendation="close_item_or_explain_why_current_release_evidence_is_not_acceptance",
|
|
628
|
+
in_source_files=True,
|
|
629
|
+
reference_count=release_evidence_count,
|
|
630
|
+
item_id=item_id,
|
|
631
|
+
item_status=status,
|
|
632
|
+
)
|
|
633
|
+
)
|
|
634
|
+
target_release = item.get("target_release")
|
|
635
|
+
target_tuple = _release_tuple(target_release) if isinstance(target_release, str) else None
|
|
636
|
+
if current_tuple is not None and target_tuple is not None and target_tuple < current_tuple:
|
|
637
|
+
records.append(
|
|
638
|
+
DirectionDriftRecord(
|
|
639
|
+
path=authority_path,
|
|
640
|
+
classification="OPEN_ITEM_TARGET_RELEASE_PASSED",
|
|
641
|
+
recommendation="revalidate_target_release_or_close_item",
|
|
642
|
+
in_source_files=True,
|
|
643
|
+
reference_count=0,
|
|
644
|
+
item_id=item_id,
|
|
645
|
+
item_status=status,
|
|
646
|
+
)
|
|
647
|
+
)
|
|
648
|
+
return records
|
|
649
|
+
|
|
650
|
+
|
|
651
|
+
def _current_release_evidence_count(item: dict[str, Any], current_release: str) -> int:
|
|
652
|
+
evidence = item.get("evidence")
|
|
653
|
+
if not isinstance(evidence, list):
|
|
654
|
+
return 0
|
|
655
|
+
release_pattern = re.compile(rf"(?<![0-9A-Za-z_.-])v?{re.escape(current_release)}(?![0-9A-Za-z_.-])")
|
|
656
|
+
return sum(1 for entry in evidence if isinstance(entry, str) and release_pattern.search(entry))
|
|
657
|
+
|
|
658
|
+
|
|
659
|
+
def _direction_item_status(section: str, item: dict[str, Any]) -> str:
|
|
660
|
+
if section in {"done", "discarded"}:
|
|
661
|
+
return section
|
|
662
|
+
status = item.get("status")
|
|
663
|
+
return status if isinstance(status, str) else ""
|
|
664
|
+
|
|
665
|
+
|
|
666
|
+
def _markdown_status(path: Path) -> str | None:
|
|
667
|
+
if not path.exists() or not path.is_file():
|
|
668
|
+
return None
|
|
669
|
+
try:
|
|
670
|
+
text = path.read_text(encoding="utf-8")
|
|
671
|
+
except OSError:
|
|
672
|
+
return None
|
|
673
|
+
for line in text.splitlines():
|
|
674
|
+
if line.startswith("Status:"):
|
|
675
|
+
value = line.removeprefix("Status:").strip()
|
|
676
|
+
return value or None
|
|
677
|
+
return None
|
|
678
|
+
|
|
679
|
+
|
|
680
|
+
def _validate_item_sources(
|
|
681
|
+
item: dict[str, Any],
|
|
682
|
+
path: str,
|
|
683
|
+
root: Path,
|
|
684
|
+
findings: list[DirectionFinding],
|
|
685
|
+
) -> None:
|
|
686
|
+
source_files = item.get("source_files")
|
|
687
|
+
if not isinstance(source_files, list) or not source_files:
|
|
688
|
+
findings.append(DirectionFinding("missing-source-files", f"{path}.source_files must not be empty"))
|
|
689
|
+
return
|
|
690
|
+
for index, source in enumerate(source_files):
|
|
691
|
+
source_path = f"{path}.source_files[{index}]"
|
|
692
|
+
if isinstance(source, str):
|
|
693
|
+
if _is_private_absolute_path(source):
|
|
694
|
+
findings.append(DirectionFinding("private-absolute-path", f"{source_path} is private/absolute"))
|
|
695
|
+
elif not (root / source).exists():
|
|
696
|
+
findings.append(DirectionFinding("missing-source-file", f"{source_path} does not exist: {source}"))
|
|
697
|
+
continue
|
|
698
|
+
if isinstance(source, dict) and source.get("deleted_source") is True:
|
|
699
|
+
deleted_path = source.get("path")
|
|
700
|
+
if not isinstance(deleted_path, str) or not deleted_path.strip():
|
|
701
|
+
findings.append(DirectionFinding("invalid-deleted-source", f"{source_path}.path must be set"))
|
|
702
|
+
continue
|
|
703
|
+
findings.append(
|
|
704
|
+
DirectionFinding(
|
|
705
|
+
"invalid-source-file",
|
|
706
|
+
f"{source_path} must be a repo path or a deleted_source mapping",
|
|
707
|
+
)
|
|
708
|
+
)
|
|
709
|
+
|
|
710
|
+
|
|
711
|
+
def _validate_item_evidence(
|
|
712
|
+
item: dict[str, Any],
|
|
713
|
+
path: str,
|
|
714
|
+
root: Path,
|
|
715
|
+
findings: list[DirectionFinding],
|
|
716
|
+
) -> None:
|
|
717
|
+
evidence = item.get("evidence")
|
|
718
|
+
if evidence in (None, []):
|
|
719
|
+
return
|
|
720
|
+
if not isinstance(evidence, list):
|
|
721
|
+
findings.append(DirectionFinding("invalid-evidence", f"{path}.evidence must be a list"))
|
|
722
|
+
return
|
|
723
|
+
for index, entry in enumerate(evidence):
|
|
724
|
+
if not isinstance(entry, str):
|
|
725
|
+
findings.append(DirectionFinding("invalid-evidence", f"{path}.evidence[{index}] must be a string"))
|
|
726
|
+
continue
|
|
727
|
+
if _looks_like_repo_file(entry) and not (root / entry).exists():
|
|
728
|
+
findings.append(DirectionFinding("missing-evidence-file", f"{path}.evidence[{index}] missing: {entry}"))
|
|
729
|
+
|
|
730
|
+
|
|
731
|
+
def _validate_target_release_currency(
|
|
732
|
+
item: dict[str, Any],
|
|
733
|
+
path: str,
|
|
734
|
+
*,
|
|
735
|
+
status: str,
|
|
736
|
+
current_release: str | None,
|
|
737
|
+
findings: list[DirectionFinding],
|
|
738
|
+
) -> None:
|
|
739
|
+
if status not in ACTIVE_STATUSES or not current_release:
|
|
740
|
+
return
|
|
741
|
+
target_release = item.get("target_release")
|
|
742
|
+
if not isinstance(target_release, str) or not target_release.strip():
|
|
743
|
+
return
|
|
744
|
+
current_tuple = _release_tuple(current_release)
|
|
745
|
+
target_tuple = _release_tuple(target_release)
|
|
746
|
+
if current_tuple is None or target_tuple is None:
|
|
747
|
+
return
|
|
748
|
+
if target_tuple < current_tuple:
|
|
749
|
+
findings.append(
|
|
750
|
+
DirectionFinding(
|
|
751
|
+
"stale-target-release",
|
|
752
|
+
f"{path}.target_release {target_release!r} has passed current release "
|
|
753
|
+
f"{current_release!r}; revalidate the item or remove the stale target",
|
|
754
|
+
)
|
|
755
|
+
)
|
|
756
|
+
|
|
757
|
+
|
|
758
|
+
def _read_project_version(root: Path) -> str | None:
|
|
759
|
+
pyproject = root / "pyproject.toml"
|
|
760
|
+
if not pyproject.exists():
|
|
761
|
+
return None
|
|
762
|
+
text = pyproject.read_text(encoding="utf-8")
|
|
763
|
+
if tomllib is not None:
|
|
764
|
+
try:
|
|
765
|
+
project = tomllib.loads(text).get("project")
|
|
766
|
+
except tomllib.TOMLDecodeError:
|
|
767
|
+
return None
|
|
768
|
+
if isinstance(project, dict):
|
|
769
|
+
version = project.get("version")
|
|
770
|
+
if isinstance(version, str) and version.strip():
|
|
771
|
+
return version
|
|
772
|
+
return None
|
|
773
|
+
match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
|
|
774
|
+
return match.group(1) if match else None
|
|
775
|
+
|
|
776
|
+
|
|
777
|
+
def _release_tuple(value: str) -> tuple[int, int, int] | None:
|
|
778
|
+
match = re.match(r"^v?(\d+)\.(\d+)(?:\.(\d+|x))?$", value.strip())
|
|
779
|
+
if not match:
|
|
780
|
+
return None
|
|
781
|
+
major, minor, patch = match.groups()
|
|
782
|
+
if patch is None:
|
|
783
|
+
patch_value = 0
|
|
784
|
+
elif patch == "x":
|
|
785
|
+
patch_value = 9999
|
|
786
|
+
else:
|
|
787
|
+
patch_value = int(patch)
|
|
788
|
+
return int(major), int(minor), patch_value
|
|
789
|
+
|
|
790
|
+
|
|
791
|
+
def _validate_no_private_absolute_paths(data: object, findings: list[DirectionFinding]) -> None:
|
|
792
|
+
if isinstance(data, dict):
|
|
793
|
+
for value in data.values():
|
|
794
|
+
_validate_no_private_absolute_paths(value, findings)
|
|
795
|
+
elif isinstance(data, list):
|
|
796
|
+
for item in data:
|
|
797
|
+
_validate_no_private_absolute_paths(item, findings)
|
|
798
|
+
elif isinstance(data, str) and _is_private_absolute_path(data):
|
|
799
|
+
findings.append(DirectionFinding("private-absolute-path", f"private absolute path is not allowed: {data}"))
|
|
800
|
+
|
|
801
|
+
|
|
802
|
+
def _is_private_absolute_path(value: str) -> bool:
|
|
803
|
+
return value.startswith(("/Users/", "/home/", "/private/", "C:\\", "D:\\"))
|
|
804
|
+
|
|
805
|
+
|
|
806
|
+
def _looks_like_repo_file(value: str) -> bool:
|
|
807
|
+
return value.startswith((".agentic/", "docs/", "src/", "tests/", "artifacts/"))
|
|
808
|
+
|
|
809
|
+
|
|
810
|
+
def _iter_planning_files(root: Path) -> list[str]:
|
|
811
|
+
files: list[str] = []
|
|
812
|
+
for base in PLANNING_SCAN_ROOTS:
|
|
813
|
+
absolute = root / base
|
|
814
|
+
if not absolute.exists():
|
|
815
|
+
continue
|
|
816
|
+
files.extend(
|
|
817
|
+
path.relative_to(root).as_posix()
|
|
818
|
+
for path in absolute.rglob("*")
|
|
819
|
+
if path.is_file() and path.suffix in {".md", ".yaml", ".yml"}
|
|
820
|
+
)
|
|
821
|
+
return sorted(files)
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
def _reference_counts(root: Path, targets: set[str]) -> dict[str, int]:
|
|
825
|
+
counts = {target: 0 for target in targets}
|
|
826
|
+
ignored_parts = {".git", ".venv", "node_modules", "__pycache__"}
|
|
827
|
+
for path in root.rglob("*"):
|
|
828
|
+
if not path.is_file() or ignored_parts & set(path.parts):
|
|
829
|
+
continue
|
|
830
|
+
try:
|
|
831
|
+
text = path.read_text(encoding="utf-8")
|
|
832
|
+
except UnicodeDecodeError:
|
|
833
|
+
continue
|
|
834
|
+
except OSError:
|
|
835
|
+
continue
|
|
836
|
+
relative = path.relative_to(root).as_posix()
|
|
837
|
+
for target in targets:
|
|
838
|
+
if target != relative and target in text:
|
|
839
|
+
counts[target] += 1
|
|
840
|
+
return counts
|