agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/planning/acceptance_markdown.py

@@ -0,0 +1,159 @@
+"""Validate human acceptance checklists against plan manifests."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError
+
+
+_BACKTICK_RE = re.compile(r"`([^`]+)`")
+
+
+@dataclass(frozen=True)
+class AcceptanceChecklistRow:
+    id: str
+    requirement_ids: tuple[str, ...]
+    evidence_ids: tuple[str, ...]
+
+
+def validate_acceptance_checklist(manifest: dict[str, Any], markdown: str) -> dict[str, Any]:
+    """Validate checklist criterion IDs and links against manifest authority."""
+
+    package_id = _package_id(manifest)
+    manifest_rows = _manifest_rows(manifest)
+    markdown_rows = _markdown_rows(markdown)
+
+    manifest_by_id = {row.id: row for row in manifest_rows}
+    markdown_by_id = {row.id: row for row in markdown_rows}
+    duplicate_markdown_ids = _duplicates([row.id for row in markdown_rows])
+    missing_in_markdown = [row.id for row in manifest_rows if row.id not in markdown_by_id]
+    extra_in_markdown = [row.id for row in markdown_rows if row.id not in manifest_by_id]
+    link_mismatches = _link_mismatches(manifest_rows, markdown_by_id)
+
+    result = {
+        "schemaVersion": "agent-acceptance-checklist-validation.v1",
+        "packageId": package_id,
+        "criterionCount": len(manifest_rows),
+        "markdownCriterionCount": len(markdown_rows),
+        "missingInMarkdown": missing_in_markdown,
+        "extraInMarkdown": extra_in_markdown,
+        "duplicateMarkdownIds": duplicate_markdown_ids,
+        "linkMismatches": link_mismatches,
+        "status": "PASS",
+    }
+    if missing_in_markdown or extra_in_markdown or duplicate_markdown_ids or link_mismatches:
+        result["status"] = "FAIL"
+        raise LifecycleError("acceptance-checklist-mismatch", "acceptance checklist does not match manifest", result)
+    return result
+
+
+def _package_id(manifest: dict[str, Any]) -> str:
+    package = manifest.get("package")
+    if not isinstance(package, dict) or not isinstance(package.get("id"), str):
+        raise LifecycleError("invalid-plan-manifest", "package.id is required")
+    return package["id"]
+
+
+def _manifest_rows(manifest: dict[str, Any]) -> list[AcceptanceChecklistRow]:
+    acceptance = manifest.get("acceptance")
+    criteria = acceptance.get("criteria") if isinstance(acceptance, dict) else None
+    if not isinstance(criteria, list) or not criteria:
+        raise LifecycleError("invalid-plan-manifest", "acceptance.criteria are required")
+    rows: list[AcceptanceChecklistRow] = []
+    for item in criteria:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            raise LifecycleError("invalid-plan-manifest", "acceptance criteria require id")
+        rows.append(
+            AcceptanceChecklistRow(
+                id=item["id"],
+                requirement_ids=_string_tuple(item.get("requirementIds"), label=f"{item['id']}.requirementIds"),
+                evidence_ids=_string_tuple(item.get("evidenceIds"), label=f"{item['id']}.evidenceIds"),
+            )
+        )
+    return rows
+
+
+def _markdown_rows(markdown: str) -> list[AcceptanceChecklistRow]:
+    rows: list[AcceptanceChecklistRow] = []
+    for line_number, line in enumerate(markdown.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if len(cells) < 4:
+            continue
+        criterion_id = _first_backtick(cells[0])
+        if criterion_id is None:
+            continue
+        if not criterion_id.startswith("AC"):
+            continue
+        rows.append(
+            AcceptanceChecklistRow(
+                id=criterion_id,
+                requirement_ids=_backtick_tuple(cells[1], line_number=line_number, column="Requirements"),
+                evidence_ids=_backtick_tuple(cells[2], line_number=line_number, column="Evidence"),
+            )
+        )
+    if not rows:
+        raise LifecycleError("invalid-acceptance-checklist", "acceptance checklist table has no AC rows")
+    return rows
+
+
+def _string_tuple(value: object, *, label: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise LifecycleError("invalid-plan-manifest", f"{label} must be a list of strings")
+    return tuple(value)
+
+
+def _first_backtick(cell: str) -> str | None:
+    match = _BACKTICK_RE.search(cell)
+    return match.group(1) if match else None
+
+
+def _backtick_tuple(cell: str, *, line_number: int, column: str) -> tuple[str, ...]:
+    values = tuple(match.group(1).strip() for match in _BACKTICK_RE.finditer(cell))
+    if not values:
+        raise LifecycleError(
+            "invalid-acceptance-checklist",
+            f"{column} cell has no backticked IDs",
+            {"line": line_number, "column": column},
+        )
+    return values
+
+
+def _duplicates(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    duplicates: list[str] = []
+    for value in values:
+        if value in seen and value not in duplicates:
+            duplicates.append(value)
+        seen.add(value)
+    return duplicates
+
+
+def _link_mismatches(
+    manifest_rows: list[AcceptanceChecklistRow],
+    markdown_by_id: dict[str, AcceptanceChecklistRow],
+) -> list[dict[str, object]]:
+    mismatches: list[dict[str, object]] = []
+    for manifest_row in manifest_rows:
+        markdown_row = markdown_by_id.get(manifest_row.id)
+        if markdown_row is None:
+            continue
+        if (
+            manifest_row.requirement_ids != markdown_row.requirement_ids
+            or manifest_row.evidence_ids != markdown_row.evidence_ids
+        ):
+            mismatches.append(
+                {
+                    "id": manifest_row.id,
+                    "manifestRequirementIds": list(manifest_row.requirement_ids),
+                    "markdownRequirementIds": list(markdown_row.requirement_ids),
+                    "manifestEvidenceIds": list(manifest_row.evidence_ids),
+                    "markdownEvidenceIds": list(markdown_row.evidence_ids),
+                }
+            )
+    return mismatches

agent_lifecycle/planning/completeness.py

@@ -0,0 +1,362 @@
+"""Structural completeness checks for SDD plan tiers."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object
+
+PROFILE_SCHEMA = "agent-plan-completeness-profile.v1"
+VALIDATION_SCHEMA = "agent-plan-completeness-validation.v1"
+SUPPORTED_TIERS = {"S0", "S1", "S2"}
+
+DEFAULT_PROFILE: dict[str, Any] = {
+    "schemaVersion": PROFILE_SCHEMA,
+    "profileId": "alk-default-plan-completeness",
+    "profiles": {
+        "S0": {
+            "description": "Bounded mechanical work with exact write scope and one validation route.",
+            "requiredChecks": [
+                "single-workstream",
+                "write-ownership",
+                "validation-command",
+            ],
+        },
+        "S1": {
+            "description": "Standard single-owner work with requirements, acceptance, evidence and validation.",
+            "requiredChecks": [
+                "requirements",
+                "acceptance",
+                "evidence-route",
+                "write-ownership",
+                "validation-command",
+                "release-impact",
+            ],
+        },
+        "S2": {
+            "description": "Large or risky work with complete authority, evidence, budgets and final gates.",
+            "requiredChecks": [
+                "requirements",
+                "acceptance",
+                "evidence-route",
+                "write-ownership",
+                "dag",
+                "budget-policy",
+                "context-limits",
+                "security-release-gates",
+                "final-audit-gates",
+            ],
+        },
+    },
+}
+
+
+def build_plan_completeness_profile() -> dict[str, Any]:
+    body = deepcopy(DEFAULT_PROFILE)
+    return {**body, "profileDigest": canonical_digest(body)}
+
+
+def load_plan_completeness_profile(path: Path | None = None) -> dict[str, Any]:
+    if path is None:
+        return build_plan_completeness_profile()
+    profile = read_json_object(path, label="plan completeness profile")
+    validation = validate_plan_completeness_profile(profile)
+    if validation["status"] != "PASS":
+        raise LifecycleError(
+            "plan-completeness-profile-invalid",
+            "plan completeness profile validation failed",
+            {"validation": validation},
+        )
+    return profile
+
+
+def validate_plan_completeness_profile(profile: dict[str, Any]) -> dict[str, Any]:
+    blockers: list[dict[str, Any]] = []
+    if profile.get("schemaVersion") != PROFILE_SCHEMA:
+        blockers.append(_blocker("invalid-profile-schema", "profile schemaVersion is unsupported"))
+    profiles = profile.get("profiles")
+    if not isinstance(profiles, dict):
+        blockers.append(_blocker("missing-tier-profiles", "profiles must contain S0, S1 and S2"))
+    else:
+        missing = sorted(SUPPORTED_TIERS.difference(profiles))
+        if missing:
+            blockers.append(_blocker("missing-tier-profiles", "profiles must contain S0, S1 and S2", {"missing": missing}))
+        for tier in sorted(SUPPORTED_TIERS.intersection(profiles)):
+            required = profiles[tier].get("requiredChecks") if isinstance(profiles[tier], dict) else None
+            if not isinstance(required, list) or not all(isinstance(item, str) and item for item in required):
+                blockers.append(_blocker("invalid-required-checks", "tier profile requiredChecks must be a string list", {"tier": tier}))
+    expected_digest = profile.get("profileDigest")
+    if expected_digest is not None:
+        body = {key: value for key, value in profile.items() if key != "profileDigest"}
+        if expected_digest != canonical_digest(body):
+            blockers.append(_blocker("profile-digest-mismatch", "profileDigest does not match profile body"))
+    body = {
+        "schemaVersion": "agent-plan-completeness-profile-validation.v1",
+        "status": "PASS" if not blockers else "FAIL",
+        "profileId": profile.get("profileId"),
+        "blockers": blockers,
+        "profileDigest": profile.get("profileDigest"),
+    }
+    return {**body, "validationDigest": canonical_digest(body)}
+
+
+def validate_plan_completeness(
+    manifest: dict[str, Any],
+    *,
+    profile: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    active_profile = profile or build_plan_completeness_profile()
+    profile_validation = validate_plan_completeness_profile(active_profile)
+    blockers = list(profile_validation["blockers"])
+    tier = _tier(manifest)
+    if tier not in SUPPORTED_TIERS:
+        blockers.append(_blocker("invalid-plan-tier", "plan tier must be S0, S1 or S2", {"tier": tier}))
+        tier = "S2"
+    required_checks = _required_checks(active_profile, tier)
+    for check in required_checks:
+        _CHECKS[check](manifest, tier, blockers)
+    body = {
+        "schemaVersion": VALIDATION_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "packageId": _package_id(manifest),
+        "tier": tier,
+        "requiredChecks": required_checks,
+        "blockers": blockers,
+        "profileDigest": active_profile.get("profileDigest") or canonical_digest(active_profile),
+        "planDigest": canonical_digest(manifest),
+    }
+    return {**body, "validationDigest": canonical_digest(body)}
+
+
+def require_plan_completeness_pass(validation: dict[str, Any]) -> dict[str, Any]:
+    if validation.get("status") != "PASS":
+        raise LifecycleError(
+            "plan-completeness-failed",
+            "plan completeness check failed",
+            {"validation": validation},
+        )
+    return validation
+
+
+def _tier(manifest: dict[str, Any]) -> str:
+    specification = manifest.get("specification")
+    if isinstance(specification, dict) and isinstance(specification.get("tier"), str):
+        return specification["tier"]
+    raw = manifest.get("tier")
+    return raw if isinstance(raw, str) else "S1"
+
+
+def _package_id(manifest: dict[str, Any]) -> str | None:
+    package = manifest.get("package")
+    return package.get("id") if isinstance(package, dict) and isinstance(package.get("id"), str) else None
+
+
+def _required_checks(profile: dict[str, Any], tier: str) -> list[str]:
+    profiles = profile.get("profiles") if isinstance(profile.get("profiles"), dict) else {}
+    tier_profile = profiles.get(tier) if isinstance(profiles, dict) else None
+    required = tier_profile.get("requiredChecks") if isinstance(tier_profile, dict) else []
+    return [item for item in required if isinstance(item, str)]
+
+
+def _check_single_workstream(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    workstreams = _workstreams(manifest)
+    if len(workstreams) != 1:
+        blockers.append(_blocker("s0-single-workstream-missing", "S0 plans must contain exactly one workstream", {"tier": tier}))
+
+
+def _check_requirements(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    specification = manifest.get("specification")
+    requirements = specification.get("requirements") if isinstance(specification, dict) else None
+    if not isinstance(requirements, list) or not requirements:
+        blockers.append(_blocker("missing-requirements", "plan specification must contain requirements", {"tier": tier}))
+
+
+def _check_acceptance(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    criteria = _acceptance_criteria(manifest)
+    if not criteria:
+        blockers.append(_blocker("missing-acceptance", "plan must contain acceptance criteria", {"tier": tier}))
+        return
+    for criterion in criteria:
+        if not isinstance(criterion.get("id"), str) or not criterion["id"]:
+            blockers.append(_blocker("missing-acceptance-id", "acceptance criterion id is required", {"tier": tier}))
+
+
+def _check_evidence_route(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    criteria = _acceptance_criteria(manifest)
+    evidence_ids = set()
+    for criterion in criteria:
+        ids = _strings(criterion.get("evidenceIds"))
+        if not ids:
+            blockers.append(_blocker("missing-evidence-route", "acceptance criterion must reference evidence ids", {"criterionId": criterion.get("id")}))
+        evidence_ids.update(ids)
+    routed = set()
+    for workstream in _workstreams(manifest):
+        routed.update(_strings(workstream.get("evidenceIds")))
+    validation = manifest.get("validation")
+    if isinstance(validation, dict):
+        routed.update(_strings(validation.get("extraEvidence")))
+    missing = sorted(evidence_ids.difference(routed))
+    if missing:
+        blockers.append(_blocker("missing-evidence-route", "evidence ids must be routed to workstreams or validation evidence", {"missing": missing}))
+
+
+def _check_write_ownership(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    workstreams = _workstreams(manifest)
+    if not workstreams:
+        blockers.append(_blocker("missing-write-ownership", "plan must contain workstreams", {"tier": tier}))
+        return
+    for workstream in workstreams:
+        writes = _strings(workstream.get("writes"))
+        if not isinstance(workstream.get("id"), str) or not workstream["id"]:
+            blockers.append(_blocker("missing-workstream-id", "workstream id is required", {"tier": tier}))
+        if not writes:
+            blockers.append(_blocker("missing-write-ownership", "workstream writes are required", {"workstreamId": workstream.get("id")}))
+
+
+def _check_validation_command(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    validation = manifest.get("validation")
+    commands = validation.get("commands") if isinstance(validation, dict) else None
+    if not isinstance(commands, list) or not any(isinstance(item, str) and item.strip() for item in commands):
+        blockers.append(_blocker("missing-validation-command", "plan validation.commands must contain at least one command", {"tier": tier}))
+
+
+def _check_release_impact(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    if not any(key in manifest for key in ("releaseTarget", "releaseImpact", "nonGoals", "finalAuditGates")):
+        blockers.append(_blocker("missing-release-impact", "S1 plans must state release impact or non-release boundary", {"tier": tier}))
+
+
+def _check_dag(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    workstreams = _workstreams(manifest)
+    ids = [item.get("id") for item in workstreams if isinstance(item.get("id"), str)]
+    duplicates = sorted({item for item in ids if ids.count(item) > 1})
+    if duplicates:
+        blockers.append(_blocker("duplicate-workstream-id", "workstream ids must be unique", {"duplicates": duplicates}))
+    id_set = set(ids)
+    for workstream in workstreams:
+        depends_on = workstream.get("dependsOn")
+        if not isinstance(depends_on, list):
+            blockers.append(_blocker("missing-dag", "S2 workstreams must declare dependsOn", {"workstreamId": workstream.get("id")}))
+            continue
+        unknown = sorted(item for item in _strings(depends_on) if item not in id_set)
+        if unknown:
+            blockers.append(_blocker("unknown-workstream-dependency", "workstream dependsOn references unknown ids", {"workstreamId": workstream.get("id"), "unknown": unknown}))
+    if _has_cycle(workstreams):
+        blockers.append(_blocker("cyclic-workstream-dag", "workstream DAG must be acyclic"))
+
+
+def _check_budget_policy(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    validation = manifest.get("validation")
+    has_budget = any(
+        _has_path(manifest, path)
+        for path in (
+            ("budgets",),
+            ("budgetPolicy",),
+            ("budgetTargets",),
+            ("resourceBudgets",),
+            ("validation", "budgetPolicy"),
+            ("validation", "budgetTargets"),
+        )
+    )
+    if isinstance(validation, dict):
+        has_budget = has_budget or any("budget" in str(item).lower() for item in _strings(validation.get("commands")))
+    if not has_budget:
+        blockers.append(_blocker("missing-budget-policy", "S2 plans must declare token/resource budget policy or validation", {"tier": tier}))
+
+
+def _check_context_limits(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    specification = manifest.get("specification")
+    tier_request = specification.get("tierResolutionRequest") if isinstance(specification, dict) else None
+    has_limits = any(
+        _has_path(manifest, path)
+        for path in (
+            ("contextLimits",),
+            ("contextBudget",),
+            ("smallContext",),
+            ("validation", "contextLimits"),
+        )
+    )
+    if isinstance(tier_request, dict):
+        has_limits = has_limits or isinstance(tier_request.get("requirementsBytes"), int)
+    if not has_limits:
+        blockers.append(_blocker("missing-context-limits", "S2 plans must define context limits or tier byte bounds", {"tier": tier}))
+
+
+def _check_security_release_gates(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    has_security = bool(_strings(manifest.get("forbiddenWrites"))) or any(key in manifest for key in ("securityGates", "sandbox", "runtimePolicy"))
+    has_release = "releaseTarget" not in manifest or bool(_strings(manifest.get("finalAuditGates"))) or _has_path(manifest, ("validation", "commands"))
+    if not has_security:
+        blockers.append(_blocker("missing-security-gate", "S2 plans must declare security or containment gates", {"tier": tier}))
+    if not has_release:
+        blockers.append(_blocker("missing-release-gate", "release S2 plans must declare release validation gates", {"tier": tier}))
+
+
+def _check_final_audit_gates(manifest: dict[str, Any], tier: str, blockers: list[dict[str, Any]]) -> None:
+    if not _strings(manifest.get("finalAuditGates")):
+        blockers.append(_blocker("s2-final-audit-gate-missing", "S2 plans must declare final audit gates", {"tier": tier}))
+
+
+def _workstreams(manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    workstreams = manifest.get("workstreams")
+    return [item for item in workstreams if isinstance(item, dict)] if isinstance(workstreams, list) else []
+
+
+def _acceptance_criteria(manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    acceptance = manifest.get("acceptance")
+    criteria = acceptance.get("criteria") if isinstance(acceptance, dict) else manifest.get("acceptanceCriteria")
+    return [item for item in criteria if isinstance(item, dict)] if isinstance(criteria, list) else []
+
+
+def _strings(value: Any) -> list[str]:
+    return [item for item in value if isinstance(item, str) and item] if isinstance(value, list) else []
+
+
+def _has_path(payload: dict[str, Any], path: tuple[str, ...]) -> bool:
+    current: Any = payload
+    for part in path:
+        if not isinstance(current, dict) or part not in current:
+            return False
+        current = current[part]
+    return current not in (None, {}, [], "")
+
+
+def _has_cycle(workstreams: list[dict[str, Any]]) -> bool:
+    graph = {item.get("id"): _strings(item.get("dependsOn")) for item in workstreams if isinstance(item.get("id"), str)}
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(node: str) -> bool:
+        if node in visiting:
+            return True
+        if node in visited:
+            return False
+        visiting.add(node)
+        for child in graph.get(node, []):
+            if child in graph and visit(child):
+                return True
+        visiting.remove(node)
+        visited.add(node)
+        return False
+
+    return any(visit(node) for node in graph)
+
+
+def _blocker(code: str, message: str, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    return {"code": code, "message": message, "context": context or {}}
+
+
+_CHECKS = {
+    "single-workstream": _check_single_workstream,
+    "requirements": _check_requirements,
+    "acceptance": _check_acceptance,
+    "evidence-route": _check_evidence_route,
+    "write-ownership": _check_write_ownership,
+    "validation-command": _check_validation_command,
+    "release-impact": _check_release_impact,
+    "dag": _check_dag,
+    "budget-policy": _check_budget_policy,
+    "context-limits": _check_context_limits,
+    "security-release-gates": _check_security_release_gates,
+    "final-audit-gates": _check_final_audit_gates,
+}