agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/patterns.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+CATALOG_PATH = Path(".agentic/patterns/catalog.yaml")
+VALID_KINDS = {"pattern", "anti-pattern"}
+
+
+class PatternCatalogError(ValueError):
+    """Raised when the local pattern catalog is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class PatternEntry:
+    id: str
+    title: str
+    kind: str
+    summary: str
+    doc: Path
+
+
+@dataclass(frozen=True)
+class PatternCatalog:
+    version: int
+    patterns: list[PatternEntry]
+
+
+@dataclass(frozen=True)
+class PatternDetail:
+    entry: PatternEntry
+    markdown: str
+
+
+def load_pattern_catalog(root: Path) -> PatternCatalog:
+    catalog_path = root / CATALOG_PATH
+    if not catalog_path.exists():
+        raise PatternCatalogError(f"missing pattern catalog: {CATALOG_PATH}")
+
+    data = yaml.safe_load(catalog_path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise PatternCatalogError("pattern catalog must be a mapping")
+
+    version = data.get("version")
+    if version != 1:
+        raise PatternCatalogError(f"unsupported pattern catalog version: {version}")
+
+    raw_patterns = data.get("patterns")
+    if not isinstance(raw_patterns, list):
+        raise PatternCatalogError("pattern catalog must contain a patterns list")
+
+    seen: set[str] = set()
+    entries: list[PatternEntry] = []
+    for raw in raw_patterns:
+        if not isinstance(raw, dict):
+            raise PatternCatalogError("pattern entry must be a mapping")
+        entry_id = _required_string(raw, "id")
+        if entry_id in seen:
+            raise PatternCatalogError(f"duplicate pattern id: {entry_id}")
+        seen.add(entry_id)
+        kind = _required_string(raw, "kind")
+        if kind not in VALID_KINDS:
+            raise PatternCatalogError(f"invalid pattern kind: {kind}")
+        entries.append(
+            PatternEntry(
+                id=entry_id,
+                title=_required_string(raw, "title"),
+                kind=kind,
+                summary=_required_string(raw, "summary"),
+                doc=Path(_required_string(raw, "doc")),
+            )
+        )
+
+    return PatternCatalog(version=version, patterns=entries)
+
+
+def load_pattern_detail(root: Path, entry: PatternEntry) -> PatternDetail:
+    doc_path = root / entry.doc
+    if not doc_path.exists():
+        raise PatternCatalogError(f"missing pattern document: {entry.doc}")
+    return PatternDetail(entry=entry, markdown=doc_path.read_text(encoding="utf-8"))
+
+
+def find_pattern(catalog: PatternCatalog, pattern_id: str) -> PatternEntry:
+    for entry in catalog.patterns:
+        if entry.id == pattern_id:
+            return entry
+    raise PatternCatalogError(f"unknown pattern id: {pattern_id}")
+
+
+def _required_string(raw: dict[str, Any], key: str) -> str:
+    value = raw.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise PatternCatalogError(f"missing or invalid pattern field: {key}")
+    return value

agentic_project_kit/planning_docs_consolidation_audit.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+PLANNING_ROOTS = (
+    "docs/planning",
+    "docs/handoff",
+)
+
+ACTIVE_MARKERS = (
+    "active",
+    "current",
+    "next",
+    "pending",
+    "todo",
+    "roadmap",
+    "slice",
+    "gate",
+    "pre-gui",
+    "gui",
+)
+
+STALE_MARKERS = (
+    "obsolete",
+    "superseded",
+    "archived",
+    "deprecated",
+    "removed",
+    "legacy",
+    "done",
+    "completed",
+    "closed",
+)
+
+POST_V049_MARKERS = (
+    "v0.4.9",
+    "0.4.9",
+    "post-v0.4.9",
+    "release command authority",
+    "audit-doc-currency",
+    "audit-absolute-path",
+    "audit-ns",
+    "gui",
+    "0.5.0",
+)
+
+AUTHORITATIVE_PLANNING_DOCS = {
+    "docs/planning/PROJECT_DIRECTION.yaml",
+}
+
+PLANNING_VIEW_DOCS = {
+    "docs/planning/PROJECT_DIRECTION.md",
+}
+
+SCOPED_AUTHORITATIVE_PLANNING_DOCS = {
+    "docs/archive/PRE_GUI_HARDENING_TASKS.md",
+}
+
+HANDOFF_PROJECTION_DOCS = {
+    "docs/handoff/NEXT_CHAT_BOOTSTRAP.md",
+    "docs/handoff/START_NEW_CHAT_PROMPT.md",
+}
+
+HISTORICAL_PLANNING_DOCS = {
+    "docs/archive/WORKFLOW_REDUCTION_FOCUS.md",
+    "docs/planning/WORKFLOW_REDUCTION_FOCUS.md",
+    "docs/planning/GUI_DETERMINISTIC_GATEKEEPER_PLAN.md",
+    "docs/planning/V0.3.8_SCOPE.md",
+}
+
+KNOWN_ACTIVE_PLANNING_DOCS = set()
+
+
+LEGACY_REVIEW_DOCS = {
+    "docs/handoff/CLOSEOUT_BEFORE_CHAT_SWITCH_PROMPT.md",
+    "docs/governance/WORK_ORDER_WORKFLOW_CONTRACT.md",
+    "docs/archive/FAILURE_MODE_REVIEW_AUTOMATION_PLAN.md",
+    "docs/archive/RULE_REFRESH_HANDSHAKE_PLAN.md",
+}
+
+
+
+DUPLICATION_TOPICS = {
+    "release_command_authority": (
+        "release command authority",
+        "release metadata",
+        "release-prep",
+        "release publish",
+        "doi closeout",
+    ),
+    "ns_migration": (
+        "./ns",
+        "ns-menu",
+        "ns migration",
+        "legacy ns",
+    ),
+    "handoff": (
+        "handoff",
+        "successor",
+        "next chat",
+        "bootstrap",
+    ),
+    "gui": (
+        "gui",
+        "cockpit",
+        "tkinter",
+    ),
+    "docs_currency": (
+        "doc currency",
+        "documentation currency",
+        "current state",
+        "status doc",
+    ),
+}
+
+
+@dataclass(frozen=True)
+class PlanningDocRecord:
+    path: str
+    title: str | None
+    line_count: int
+    active_score: int
+    stale_score: int
+    post_v049_score: int
+    topics: tuple[str, ...]
+    classification: str
+    reason: str
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class PlanningDocsConsolidationAuditResult:
+    root: str
+    records: tuple[PlanningDocRecord, ...]
+    blockers: tuple[PlanningDocRecord, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.blockers
+
+    @property
+    def status(self) -> str:
+        return "PASS" if self.ok else "FAIL"
+
+    @property
+    def returncode(self) -> int:
+        return 0 if self.ok else 1
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "kind": "planning_docs_consolidation_audit",
+            "root": self.root,
+            "status": self.status,
+            "record_count": len(self.records),
+            "blocker_count": len(self.blockers),
+            "records": [item.as_dict() for item in self.records],
+            "blockers": [item.as_dict() for item in self.blockers],
+        }
+
+
+def _title(lines: list[str]) -> str | None:
+    for line in lines[:40]:
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            return stripped.lstrip("#").strip() or None
+    return None
+
+
+def _score(text: str, markers: tuple[str, ...]) -> int:
+    lowered = text.lower()
+    return sum(lowered.count(marker.lower()) for marker in markers)
+
+
+def _topics(text: str) -> tuple[str, ...]:
+    lowered = text.lower()
+    found: list[str] = []
+    for topic, markers in DUPLICATION_TOPICS.items():
+        if any(marker.lower() in lowered for marker in markers):
+            found.append(topic)
+    return tuple(found)
+
+
+def _classify(relative: str, text: str, active_score: int, stale_score: int, post_v049_score: int, topics: tuple[str, ...]) -> tuple[str, str]:
+    lowered = text.lower()
+
+    if relative.endswith("CURRENT_HANDOFF.md"):
+        return "authoritative_current_handoff", "current handoff is an authoritative state carrier"
+
+    if relative in AUTHORITATIVE_PLANNING_DOCS:
+        return "authoritative_planning_anchor", "explicit current planning authority"
+
+    if relative in PLANNING_VIEW_DOCS:
+        return "planning_authority_view", "human-readable view of the current planning authority"
+
+    if relative in SCOPED_AUTHORITATIVE_PLANNING_DOCS:
+        return "authoritative_scoped_planning_anchor", "explicit scoped planning authority"
+
+    if relative in HANDOFF_PROJECTION_DOCS:
+        return "handoff_projection", "generated handoff prompt projection, not planning authority"
+
+    if relative in HISTORICAL_PLANNING_DOCS:
+        return "historical_planning_doc", "known historical planning/handoff artifact"
+
+    if relative in LEGACY_REVIEW_DOCS:
+        return "legacy_review_candidate", "known follow-up review candidate, not current authority"
+
+    if relative in KNOWN_ACTIVE_PLANNING_DOCS:
+        return "active_planning_candidate", "known active planning document, not current overall authority"
+
+    if "current source of truth" in lowered or "source of truth" in lowered:
+        return "possible_authoritative_plan", "document claims source-of-truth status"
+
+    if stale_score > active_score and post_v049_score == 0:
+        return "stale_or_archival_candidate", "stale markers dominate and no current release marker was found"
+
+    if post_v049_score > 0 and active_score > 0:
+        return "active_planning_candidate", "current release and active planning markers found"
+
+    if len(topics) >= 3 and active_score > 0:
+        return "consolidation_candidate", "multiple active planning topics in one document"
+
+    if active_score > 0:
+        return "active_but_needs_review", "active markers found but no current release anchor"
+
+    return "low_priority_reference", "no strong active or stale signal"
+
+
+def _iter_docs(root: Path) -> list[Path]:
+    docs: list[Path] = []
+    for planning_root in PLANNING_ROOTS:
+        base = root / planning_root
+        if not base.exists():
+            continue
+        docs.extend(path for path in base.rglob("*") if path.is_file() and path.suffix in {".md", ".yaml", ".yml"})
+    return sorted(docs)
+
+
+def audit_planning_docs_consolidation(root: Path = Path(".")) -> PlanningDocsConsolidationAuditResult:
+    root = root.resolve()
+    records: list[PlanningDocRecord] = []
+
+    for path in _iter_docs(root):
+        relative = path.relative_to(root).as_posix()
+        text = path.read_text(encoding="utf-8", errors="replace")
+        lines = text.splitlines()
+        active_score = _score(text, ACTIVE_MARKERS)
+        stale_score = _score(text, STALE_MARKERS)
+        post_v049_score = _score(text, POST_V049_MARKERS)
+        topics = _topics(text)
+        classification, reason = _classify(
+            relative,
+            text,
+            active_score,
+            stale_score,
+            post_v049_score,
+            topics,
+        )
+        records.append(
+            PlanningDocRecord(
+                path=relative,
+                title=_title(lines),
+                line_count=len(lines),
+                active_score=active_score,
+                stale_score=stale_score,
+                post_v049_score=post_v049_score,
+                topics=topics,
+                classification=classification,
+                reason=reason,
+            )
+        )
+
+    blockers = tuple(
+        record
+        for record in records
+        if record.classification in {
+            "possible_authoritative_plan",
+            "consolidation_candidate",
+            "active_but_needs_review",
+        }
+    )
+
+    return PlanningDocsConsolidationAuditResult(
+        root=root.as_posix(),
+        records=tuple(records),
+        blockers=blockers,
+    )
+
+
+def render_planning_docs_consolidation_audit(result: PlanningDocsConsolidationAuditResult) -> str:
+    lines = [
+        "PLANNING_DOCS_CONSOLIDATION_AUDIT",
+        f"STATUS={result.status}",
+        f"RECORD_COUNT={len(result.records)}",
+        f"BLOCKER_COUNT={len(result.blockers)}",
+    ]
+    for item in result.blockers:
+        lines.append(
+            "BLOCKER="
+            f"{item.classification}|{item.path}|topics={','.join(item.topics)}|"
+            f"active={item.active_score}|stale={item.stale_score}|post_v049={item.post_v049_score}|{item.title}"
+        )
+    for item in result.records:
+        lines.append(
+            "RECORD="
+            f"{item.classification}|{item.path}|topics={','.join(item.topics)}|"
+            f"active={item.active_score}|stale={item.stale_score}|post_v049={item.post_v049_score}|{item.title}"
+        )
+    return "\n".join(lines) + "\n"

agentic_project_kit/portability_shell_gate.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_EXCLUDED_PARTS = {".git", ".venv", "dist", "build", "__pycache__"}
+DEFAULT_ALLOWED_PREFIXES = ("tmp/",)
+
+@dataclass(frozen=True)
+class PortabilityShellGateResult:
+    ok: bool
+    shell_files: tuple[str, ...]
+    blocking_shell_files: tuple[str, ...]
+
+def _is_excluded(path: Path) -> bool:
+    return any(part in DEFAULT_EXCLUDED_PARTS for part in path.parts)
+
+def _is_allowed(path_text: str, allowed_prefixes: tuple[str, ...]) -> bool:
+    normalized = path_text.removeprefix("./")
+    return any(normalized.startswith(prefix) for prefix in allowed_prefixes)
+
+def build_portability_shell_gate_report(project_root: Path, allowed_prefixes: tuple[str, ...] = DEFAULT_ALLOWED_PREFIXES) -> PortabilityShellGateResult:
+    shell_files: list[str] = []
+    for path in sorted(project_root.rglob("*.sh")):
+        rel = path.relative_to(project_root)
+        if _is_excluded(rel):
+            continue
+        shell_files.append(rel.as_posix())
+    blocking = tuple(item for item in shell_files if not _is_allowed(item, allowed_prefixes))
+    return PortabilityShellGateResult(ok=not blocking, shell_files=tuple(shell_files), blocking_shell_files=blocking)
+
+def render_portability_shell_gate_report(result: PortabilityShellGateResult) -> str:
+    lines = ["Portability shell gate report"]
+    lines.append(f"shell_file_count={len(result.shell_files)}")
+    lines.append(f"blocking_shell_file_count={len(result.blocking_shell_files)}")
+    if result.blocking_shell_files:
+        lines.append("Blocking shell files:")
+        lines.extend(f"- {item}" for item in result.blocking_shell_files)
+    lines.append("### RESULT: PASS ###" if result.ok else "### RESULT: FAIL ###")
+    return "\n".join(lines)

agentic_project_kit/post_merge_handoff_refresh.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+import subprocess
+from typing import Any
+from agentic_project_kit.handoff_freshness import assess_handoff_prompt_freshness
+from agentic_project_kit.handoff_prompt import render_handoff_prompt
+from agentic_project_kit.handoff_state import load_handoff_state
+
+@dataclass(frozen=True)
+class PostMergeHandoffRefreshStatus:
+    current_head: str
+    freshness_warning_present: bool
+    refresh_required: bool
+    latest_successor_prompt: str | None
+    result: str
+    next_safe_action: str
+
+def evaluate_post_merge_handoff_refresh(project_root: Path = Path('.'), *, state_path: str = '.agentic/handoff_state.yaml') -> PostMergeHandoffRefreshStatus:
+    state_file = project_root / state_path
+    data = load_handoff_state(str(state_file))
+    rendered_prompt = render_handoff_prompt(data)
+    current_head = _git_short_head(project_root)
+    current_subject = _git_commit_subject(project_root)
+    warnings = assess_handoff_prompt_freshness(
+        data,
+        str(state_file),
+        current_head=current_head,
+        current_subject=current_subject,
+        successor_prompt_text=rendered_prompt,
+    )
+    warning = bool(warnings)
+    return PostMergeHandoffRefreshStatus(current_head, warning, warning, _latest_successor_prompt(data), 'REFRESH_REQUIRED' if warning else 'NOOP', 'create_administrative_handoff_refresh' if warning else 'continue_without_post_merge_handoff_refresh')
+
+def render_post_merge_handoff_refresh_status(status: PostMergeHandoffRefreshStatus) -> str:
+    return '\n'.join(['POST_MERGE_HANDOFF_REFRESH', f'current_head={status.current_head}', f'freshness_warning_present={str(status.freshness_warning_present)}', f'refresh_required={str(status.refresh_required)}', f'latest_successor_prompt={status.latest_successor_prompt or ""}', f'result={status.result}', f'next_safe_action={status.next_safe_action}']) + '\n'
+
+def _git_short_head(project_root: Path) -> str:
+    try:
+        return subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD'], cwd=project_root, stderr=subprocess.DEVNULL, text=True).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ''
+
+def _git_commit_subject(project_root: Path) -> str:
+    try:
+        return subprocess.check_output(['git', 'log', '-1', '--pretty=%s'], cwd=project_root, stderr=subprocess.DEVNULL, text=True).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ''
+
+
+def _latest_successor_prompt(data: dict[str, Any]) -> str | None:
+    for key in ('handoff_maintenance', 'administrative_evidence_state'):
+        section = data.get(key, {})
+        if isinstance(section, dict) and section.get('latest_successor_prompt'):
+            return str(section['latest_successor_prompt'])
+    return None