@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-core/skills/workflow-project-context/scripts/validate_initialization.py

@@ -0,0 +1,545 @@
+#!/usr/bin/env python3
+"""Validate that project-context outputs belong to the current initialization run."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+SPEC_TEMPLATE_ROOT = SKILL_ROOT / "assets" / "spec-templates"
+
+CODE_INDEX_FILES = (
+    ".planning/code-index/index.sqlite",
+    ".planning/code-index/files.jsonl",
+    ".planning/code-index/symbols.jsonl",
+    ".planning/code-index/relations.jsonl",
+    ".planning/code-index/AUDIT.md",
+)
+
+DESIGN_RULE_PACK_FILES = (
+    ".context/spec/design/tokens/project-tokens.md",
+    ".context/spec/design/recommendations/accessibility.md",
+    ".context/spec/design/recommendations/component-library.md",
+    ".context/spec/design/tools/ui-ux-pro-max/SKILL.md",
+)
+
+STATUS_FILES = (
+    ".planning/STATE.md",
+    ".planning/PROJECT.md",
+    ".planning/navigation/INDEX.md",
+    ".planning/rules/INDEX.md",
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".")
+    parser.add_argument(
+        "--manifest",
+        default=".planning/project-context-run.json",
+    )
+    return parser.parse_args()
+
+
+def parse_started_at(value: str) -> float:
+    normalized = value.replace("Z", "+00:00")
+    return datetime.fromisoformat(normalized).timestamp()
+
+
+def resolve_project_path(root: Path, relative_path: str) -> Path:
+    candidate = (root / relative_path).resolve()
+    try:
+        candidate.relative_to(root)
+    except ValueError as error:
+        raise ValueError(f"path escapes project root: {relative_path}") from error
+    return candidate
+
+
+def resolve_codebase_root(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path.resolve() if path.is_absolute() else (project_root / path).resolve()
+
+
+def resolve_source_path(codebase_root: Path, relative_path: str) -> Path:
+    candidate = (codebase_root / relative_path).resolve()
+    try:
+        candidate.relative_to(codebase_root)
+    except ValueError as error:
+        raise ValueError(f"source path escapes codebase root: {relative_path}") from error
+    return candidate
+
+
+def source_fingerprint(codebase_root: Path, source_paths: list[str]) -> str:
+    digest = hashlib.sha256()
+    for relative_path in sorted(set(source_paths)):
+        path = resolve_source_path(codebase_root, relative_path)
+        if not path.is_file():
+            raise ValueError(f"source file missing: {relative_path}")
+        file_hash = hashlib.sha256(path.read_bytes()).hexdigest()
+        digest.update(relative_path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(file_hash.encode("ascii"))
+        digest.update(b"\n")
+    return f"sha256:{digest.hexdigest()}"
+
+
+def load_manifest(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError("manifest root must be an object")
+    return value
+
+
+def contains_placeholder(value: Any) -> bool:
+    if isinstance(value, str):
+        return "{{" in value or "}}" in value
+    if isinstance(value, list):
+        return any(contains_placeholder(item) for item in value)
+    if isinstance(value, dict):
+        return any(contains_placeholder(item) for item in value.values())
+    return False
+
+
+def require_fresh_file(path: Path, started_at: float, errors: list[str]) -> None:
+    if not path.is_file():
+        errors.append(f"missing file: {path}")
+        return
+    if path.stat().st_mtime + 1 < started_at:
+        errors.append(f"stale file from before this run: {path}")
+
+
+def validate_status_markers(
+    root: Path,
+    run_id: str,
+    code_index_status: str,
+    code_index_skip_reason: str,
+    errors: list[str],
+) -> None:
+    marker = (
+        f"project_context_run_id: {run_id}; "
+        f"code_index_status: {code_index_status}; "
+        f"code_index_skip_reason: {code_index_skip_reason}"
+    )
+    for relative_path in STATUS_FILES:
+        path = resolve_project_path(root, relative_path)
+        if not path.is_file():
+            errors.append(f"status file missing: {relative_path}")
+            continue
+        content = path.read_text(encoding="utf-8")
+        if marker not in content:
+            errors.append(f"current-run status marker missing: {relative_path}")
+        if relative_path == ".planning/STATE.md" and "PENDING_TEMPLATE" in content:
+            errors.append("STATE.md contains an unresolved PENDING_TEMPLATE blocker")
+
+
+def validate_code_index(
+    root: Path,
+    manifest: dict[str, Any],
+    started_at: float,
+    errors: list[str],
+) -> None:
+    mode = manifest.get("mode")
+    status = manifest.get("code_index_status")
+    if mode == "full":
+        if status != "complete":
+            errors.append("full mode requires code_index_status=complete")
+        if manifest.get("code_index_skip_reason") != "none":
+            errors.append("full mode requires code_index_skip_reason=none")
+        for relative_path in CODE_INDEX_FILES:
+            require_fresh_file(
+                resolve_project_path(root, relative_path),
+                started_at,
+                errors,
+            )
+    elif mode == "fast":
+        if status != "skipped":
+            errors.append("fast mode requires code_index_status=skipped")
+        if manifest.get("code_index_skip_reason") not in {
+            "--fast",
+            "--skip-code-index",
+        }:
+            errors.append("fast mode requires an explicit code-index skip flag")
+    else:
+        errors.append("mode must be full or fast")
+
+
+def validate_design_rule_pack(manifest: dict[str, Any], root: Path, errors: list[str]) -> None:
+    pack = manifest.get("design_rule_pack")
+    if not isinstance(pack, dict):
+        errors.append("design_rule_pack must be an object")
+        return
+
+    status = pack.get("status")
+    reason = pack.get("reason")
+    has_frontend = any(
+        isinstance(item, dict) and item.get("domain") == "frontend"
+        for item in manifest.get("topic_inventory", [])
+    )
+
+    if has_frontend:
+        if status != "installed":
+            errors.append("frontend projects require design_rule_pack.status=installed")
+            return
+        assets = pack.get("assets")
+        if not isinstance(assets, list):
+            errors.append("installed design rule pack requires an assets list")
+        for relative_path in DESIGN_RULE_PACK_FILES:
+            if not resolve_project_path(root, relative_path).is_file():
+                errors.append(f"missing design rule pack asset: {relative_path}")
+    elif status != "not_applicable":
+        errors.append("non-frontend projects require design_rule_pack.status=not_applicable")
+    elif not isinstance(reason, str) or not reason:
+        errors.append("not_applicable design rule pack requires a reason")
+
+
+def validate_depth_specs(
+    root: Path,
+    manifest: dict[str, Any],
+    started_at: float,
+    errors: list[str],
+) -> set[tuple[str, str, str]]:
+    specs = manifest.get("depth_specs")
+    if not isinstance(specs, list):
+        errors.append("depth_specs must be an array")
+        return set()
+
+    seen_keys: set[tuple[str, str, str]] = set()
+    seen_paths: set[str] = set()
+    run_id = str(manifest.get("run_id", ""))
+
+    for index, entry in enumerate(specs):
+        if not isinstance(entry, dict):
+            errors.append(f"depth_specs[{index}] must be an object")
+            continue
+        codebase = str(entry.get("codebase", ""))
+        codebase_root_value = str(entry.get("codebase_root", ""))
+        domain = str(entry.get("domain", ""))
+        topic = str(entry.get("topic", ""))
+        relative_path = str(entry.get("path", ""))
+        key = (codebase, domain, topic)
+
+        if not all(key) or not codebase_root_value or domain not in {"backend", "frontend"}:
+            errors.append(f"invalid depth spec identity at index {index}: {key}")
+            continue
+        if key in seen_keys:
+            errors.append(f"duplicate depth spec identity: {key}")
+        seen_keys.add(key)
+        if relative_path in seen_paths:
+            errors.append(f"multiple depth specs share one output path: {relative_path}")
+        seen_paths.add(relative_path)
+
+        source_paths = entry.get("source_paths")
+        if (
+            not isinstance(source_paths, list)
+            or not source_paths
+            or not all(isinstance(path, str) and path for path in source_paths)
+        ):
+            errors.append(f"depth spec has no source_paths: {key}")
+            continue
+        try:
+            codebase_root = resolve_codebase_root(root, codebase_root_value)
+            if not codebase_root.is_dir():
+                raise ValueError(f"codebase root missing: {codebase_root_value}")
+            actual_fingerprint = source_fingerprint(codebase_root, source_paths)
+        except ValueError as error:
+            errors.append(f"{key}: {error}")
+            continue
+        expected_fingerprint = entry.get("source_fingerprint")
+        if actual_fingerprint != expected_fingerprint:
+            errors.append(f"source fingerprint mismatch: {key}")
+
+        try:
+            path = resolve_project_path(root, relative_path)
+        except ValueError as error:
+            errors.append(str(error))
+            continue
+        require_fresh_file(path, started_at, errors)
+        if not path.is_file():
+            continue
+        content = path.read_text(encoding="utf-8")
+        if f"Run ID: `{run_id}`" not in content:
+            errors.append(f"run ID missing from depth spec: {relative_path}")
+        if f"Source fingerprint: `{actual_fingerprint}`" not in content:
+            errors.append(f"source fingerprint missing from depth spec: {relative_path}")
+    return seen_keys
+
+
+def validate_not_applicable_topics(
+    manifest: dict[str, Any],
+    depth_spec_keys: set[tuple[str, str, str]],
+    errors: list[str],
+) -> set[tuple[str, str, str]]:
+    entries = manifest.get("not_applicable_topics")
+    if not isinstance(entries, list):
+        errors.append("not_applicable_topics must be an array")
+        return set()
+
+    seen: set[tuple[str, str, str]] = set()
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            errors.append(f"not_applicable_topics[{index}] must be an object")
+            continue
+        key = (
+            str(entry.get("codebase", "")),
+            str(entry.get("domain", "")),
+            str(entry.get("topic", "")),
+        )
+        if not all(key) or key[1] not in {"backend", "frontend"}:
+            errors.append(f"invalid not-applicable identity at index {index}: {key}")
+            continue
+        if key in seen:
+            errors.append(f"duplicate not-applicable identity: {key}")
+        if key in depth_spec_keys:
+            errors.append(f"topic is both generated and not applicable: {key}")
+        seen.add(key)
+    return seen
+
+
+def template_topics(domain: str) -> set[str]:
+    template_dir = SPEC_TEMPLATE_ROOT / domain
+    return {path.stem for path in template_dir.glob("*.md") if path.is_file()}
+
+
+def validate_topic_inventory(
+    manifest: dict[str, Any],
+    depth_spec_keys: set[tuple[str, str, str]],
+    not_applicable_keys: set[tuple[str, str, str]],
+    errors: list[str],
+) -> None:
+    entries = manifest.get("topic_inventory")
+    if not isinstance(entries, list):
+        errors.append("topic_inventory must be an array")
+        return
+
+    seen_identities: set[tuple[str, str]] = set()
+    accounted_keys: set[tuple[str, str, str]] = set()
+
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            errors.append(f"topic_inventory[{index}] must be an object")
+            continue
+        codebase = str(entry.get("codebase", ""))
+        domain = str(entry.get("domain", ""))
+        identity = (codebase, domain)
+        if not codebase or domain not in {"backend", "frontend"}:
+            errors.append(f"invalid topic inventory identity at index {index}: {identity}")
+            continue
+        if identity in seen_identities:
+            errors.append(f"duplicate topic inventory identity: {identity}")
+        seen_identities.add(identity)
+
+        candidates_value = entry.get("candidate_topics")
+        discovered_value = entry.get("discovered_topics")
+        if (
+            not isinstance(candidates_value, list)
+            or not all(isinstance(topic, str) and topic for topic in candidates_value)
+        ):
+            errors.append(f"invalid candidate_topics for: {identity}")
+            continue
+        if (
+            not isinstance(discovered_value, list)
+            or not all(isinstance(topic, str) and topic for topic in discovered_value)
+        ):
+            errors.append(f"invalid discovered_topics for: {identity}")
+            continue
+
+        candidate_counts = Counter(candidates_value)
+        discovered_counts = Counter(discovered_value)
+        duplicate_candidates = sorted(
+            topic for topic, count in candidate_counts.items() if count > 1
+        )
+        duplicate_discovered = sorted(
+            topic for topic, count in discovered_counts.items() if count > 1
+        )
+        if duplicate_candidates:
+            errors.append(
+                f"duplicate candidate topics for {identity}: {duplicate_candidates}"
+            )
+        if duplicate_discovered:
+            errors.append(
+                f"duplicate discovered topics for {identity}: {duplicate_discovered}"
+            )
+
+        candidates = set(candidates_value)
+        discovered = set(discovered_value)
+        expected_candidates = template_topics(domain)
+        if candidates != expected_candidates:
+            errors.append(
+                f"candidate topics do not match current templates for {identity}: "
+                f"expected={sorted(expected_candidates)} actual={sorted(candidates)}"
+            )
+        unexpected_discovered = discovered - candidates
+        if unexpected_discovered:
+            errors.append(
+                f"discovered topics are not candidates for {identity}: "
+                f"{sorted(unexpected_discovered)}"
+            )
+
+        expected_generated = {
+            (codebase, domain, topic) for topic in discovered
+        }
+        expected_not_applicable = {
+            (codebase, domain, topic) for topic in candidates - discovered
+        }
+        actual_generated = {
+            key for key in depth_spec_keys if key[:2] == identity
+        }
+        actual_not_applicable = {
+            key for key in not_applicable_keys if key[:2] == identity
+        }
+        if actual_generated != expected_generated:
+            errors.append(
+                f"generated topic partition mismatch for {identity}: "
+                f"expected={sorted(expected_generated)} actual={sorted(actual_generated)}"
+            )
+        if actual_not_applicable != expected_not_applicable:
+            errors.append(
+                f"not-applicable topic partition mismatch for {identity}: "
+                f"expected={sorted(expected_not_applicable)} "
+                f"actual={sorted(actual_not_applicable)}"
+            )
+        accounted_keys.update(expected_generated)
+        accounted_keys.update(expected_not_applicable)
+
+    unaccounted_keys = (depth_spec_keys | not_applicable_keys) - accounted_keys
+    if unaccounted_keys:
+        errors.append(
+            "topics exist without a topic_inventory entry: "
+            f"{sorted(unaccounted_keys)}"
+        )
+
+
+def validate_domain_indexes(
+    root: Path,
+    manifest: dict[str, Any],
+    started_at: float,
+    errors: list[str],
+) -> None:
+    run_id = str(manifest.get("run_id", ""))
+    expected_by_domain: dict[str, set[str]] = {}
+
+    for entry in manifest.get("depth_specs", []):
+        if not isinstance(entry, dict):
+            continue
+        codebase = str(entry.get("codebase", ""))
+        domain = str(entry.get("domain", ""))
+        topic = str(entry.get("topic", ""))
+        path = str(entry.get("path", ""))
+        if not codebase or domain not in {"backend", "frontend"} or not topic or not path:
+            continue
+        expected_by_domain.setdefault(domain, set()).add(
+            f"<!-- depth_spec: codebase={codebase}; domain={domain}; "
+            f"topic={topic}; status=present; path={path} -->"
+        )
+
+    for entry in manifest.get("not_applicable_topics", []):
+        if not isinstance(entry, dict):
+            continue
+        codebase = str(entry.get("codebase", ""))
+        domain = str(entry.get("domain", ""))
+        topic = str(entry.get("topic", ""))
+        if not codebase or domain not in {"backend", "frontend"} or not topic:
+            continue
+        expected_by_domain.setdefault(domain, set()).add(
+            f"<!-- depth_spec: codebase={codebase}; domain={domain}; "
+            f"topic={topic}; status=not_applicable; path=none -->"
+        )
+
+    for domain, expected_markers in expected_by_domain.items():
+        relative_path = f".context/spec/{domain}/index.md"
+        path = resolve_project_path(root, relative_path)
+        require_fresh_file(path, started_at, errors)
+        if not path.is_file():
+            continue
+        content = path.read_text(encoding="utf-8")
+        if f"Run ID: `{run_id}`" not in content:
+            errors.append(f"run ID missing from domain index: {relative_path}")
+        marker_lines = [
+            line.strip()
+            for line in content.splitlines()
+            if line.strip().startswith("<!-- depth_spec:")
+        ]
+        if len(marker_lines) != len(set(marker_lines)):
+            errors.append(f"duplicate depth-spec markers in domain index: {relative_path}")
+        actual_markers = set(marker_lines)
+        missing = sorted(expected_markers - actual_markers)
+        stale = sorted(actual_markers - expected_markers)
+        if missing:
+            errors.append(f"domain index missing markers in {relative_path}: {missing}")
+        if stale:
+            errors.append(f"domain index has stale markers in {relative_path}: {stale}")
+
+
+def main() -> int:
+    args = parse_args()
+    root = Path(args.root).resolve()
+    manifest_path = resolve_project_path(root, args.manifest)
+    errors: list[str] = []
+
+    try:
+        manifest = load_manifest(manifest_path)
+        if manifest.get("version") != 1:
+            raise ValueError("manifest version must be 1")
+        if contains_placeholder(manifest):
+            raise ValueError("manifest contains unresolved template placeholders")
+        run_id = str(manifest.get("run_id", ""))
+        if not run_id:
+            raise ValueError("run_id is required")
+        started_at = parse_started_at(str(manifest.get("started_at", "")))
+        code_index_status = str(manifest.get("code_index_status", ""))
+        code_index_skip_reason = (
+            str(manifest.get("code_index_skip_reason"))
+            if manifest.get("code_index_skip_reason")
+            else "none"
+        )
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"Initialization validation failed: {error}", file=sys.stderr)
+        return 1
+
+    validate_status_markers(
+        root,
+        run_id,
+        code_index_status,
+        code_index_skip_reason,
+        errors,
+    )
+    validate_code_index(root, manifest, started_at, errors)
+    validate_design_rule_pack(manifest, root, errors)
+    depth_spec_keys = validate_depth_specs(root, manifest, started_at, errors)
+    not_applicable_keys = validate_not_applicable_topics(
+        manifest,
+        depth_spec_keys,
+        errors,
+    )
+    validate_topic_inventory(
+        manifest,
+        depth_spec_keys,
+        not_applicable_keys,
+        errors,
+    )
+    validate_domain_indexes(root, manifest, started_at, errors)
+
+    if errors:
+        print("Initialization validation failed:", file=sys.stderr)
+        for error in errors:
+            print(f"- {error}", file=sys.stderr)
+        return 1
+
+    print(
+        "Initialization validation passed: "
+        f"run_id={run_id} depth_specs={len(manifest['depth_specs'])} "
+        f"code_index={code_index_status}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/devflow-design/agents/contract-auditor.md

@@ -0,0 +1,18 @@
+---
+name: contract-auditor
+description: Read-only cross-layer auditor for API, UI, frontend, backend, data, and integration design consistency.
+tools:
+  - read
+  - grep
+  - find
+  - lsp
+model: "@slow"
+thinkingLevel: high
+autoloadSkills:
+  - workflow-api-contract
+  - workflow-integration-verify
+---
+
+Audit contracts across requirement slices, API schemas, UI states, frontend calls, backend handlers, persistence, and verification cases.
+
+Look for divergent names and types, missing error states, ownership ambiguity, unhandled compatibility, premature implementation of later slices, and claims not supported by code. Return a compact trace matrix plus severity-ordered gaps. Do not edit artifacts or workflow state.

package/plugins/devflow-design/extensions/devflow-design.ts

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function devflowDesign(pi: ExtensionAPI) {
+  const { z } = pi.zod;
+  pi.registerTool({
+    name: "devflow_design_rule",
+    label: "Devflow Design Rule Pack",
+    description: "Install the versioned Devflow design rule pack into the current project.",
+    parameters: z.object({ args: z.array(z.string()).default([]) }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+      const roots = [
+        process.env.DEVFLOW_KIT_ROOT,
+        path.join(ctx.cwd, ".skills"),
+        path.resolve(moduleDirectory, "../skills"),
+        path.resolve(moduleDirectory, "../../.."),
+      ].filter(Boolean) as string[];
+      const skillRoot = roots.find(root =>
+        existsSync(path.join(root, "workflow-design-rule-pack/scripts/install.py")),
+      );
+      if (!skillRoot) throw new Error("Devflow design skills not found");
+      const script = path.join(skillRoot, "workflow-design-rule-pack/scripts/install.py");
+      const child = Bun.spawn(["python3", script, ...params.args], {
+        cwd: ctx.cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const [exitCode, stdout, stderr] = await Promise.all([
+        child.exited,
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+      ]);
+      const out = stdout.trim();
+      const err = stderr.trim();
+      return {
+        content: [{ type: "text" as const, text: out || err || `Process exited with ${exitCode}` }],
+        details: { exitCode, stderr: err || undefined },
+        isError: exitCode !== 0,
+      };
+    },
+  });
+}

package/plugins/devflow-design/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@devflow/omp-design",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": "*"
+  },
+  "omp": {
+    "extensions": [
+      "./extensions/devflow-design.ts"
+    ]
+  }
+}