@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-intel/skills/workflow-context-sync/SKILL.md

@@ -0,0 +1,381 @@
+---
+name: workflow-context-sync
+description: Execute project-context reconciliation only when the context-sync Stop hook reports CONTEXT_SYNC_REQUIRED, or when the user explicitly requests a context refresh. Consume the hook's changed-file list and Light/Medium/Full verdict, update only the required code index, navigation, or specs, validate, then acknowledge the exact hook session.
+---
+
+# Workflow Context Sync
+
+Use this skill to keep project facts trustworthy after code changes. It is a coordinator, not a new indexing system: classify the change, choose the smallest safe sync level, call existing workflow skills or their deterministic commands, validate, and report.
+
+## Trigger Contract
+
+Do not activate this skill merely because code changed. The lifecycle hooks own detection and triggering:
+
+1. `PostToolUse` records successful edits and shell activity.
+2. `Stop` computes the current change set and classifies it as Light, Medium, or Full.
+3. Light is handled automatically when deterministic code-index refresh succeeds.
+4. This skill runs only for a `CONTEXT_SYNC_REQUIRED` verdict, a failed Light auto-sync, or an explicit user request.
+
+Treat the hook-provided file list, level, and session ID as authoritative inputs. Do not widen the change set unless validation produces concrete stale evidence.
+
+## First Principles
+
+The invariant is:
+
+```text
+code facts changed -> project context must remain trustworthy
+```
+
+Preserve these properties:
+
+- **Freshness**: `.planning/code-index/`, `.planning/navigation/`, and `.context/spec/` must not describe old routes, APIs, entries, services, commands, or codebase roots.
+- **Minimality**: do not run a full project initialization when changed-file indexing is enough.
+- **Evidence**: do not update navigation/spec from memory or inference alone; read the changed source or manifest evidence first.
+- **Non-destruction**: do not overwrite user-authored business context; append logs or update machine-derived sections only.
+- **Cursor correctness**: after-pull sync must compare each Git repository from the last successfully synced commit to current `HEAD`, not rely only on Git's volatile `ORIG_HEAD`.
+
+## Related Skills
+
+| Skill | Role | When to Use |
+|---|---|---|
+| project indexes | Accelerate rule/spec/navigation discovery; fall back to LSP/search/source when stale | Advisory evidence, never a source-read blocker |
+| `workflow-code-index` | Refresh, validate, and audit machine facts | Light, Medium, Full; audit/staleness problems |
+| `workflow-update-navigation` | Update `.planning/navigation/*.md` | Medium route/API/page/service/command changes |
+| `workflow-project-context` | Full reinitialization | Full only |
+| `workflow-bug-fix` | Bug-fix main workflow | Must call this skill after verification and lesson capture |
+| `workflow-execute-phase` | Feature implementation workflow | Must call this skill after implementation verification |
+| `workflow-verify-work` | Validate implementation | Usually before after-bugfix sync |
+
+## Inputs
+
+Supported intent flags:
+
+- `--after-pull`: sync after pulling external changes.
+- `--after-bugfix`: sync after local bug-fix code changes.
+- `--after-implementation`: sync after normal feature implementation or direct OMP code edits.
+- `--changed-files`: sync explicit files supplied by the user.
+- `--full`: force full project context refresh.
+- `--dry-run`: classify and output a plan without modifying files.
+
+If no flag is provided, default to `--dry-run` and infer changed files from git.
+
+## Main Chain
+
+```text
+workflow-context-sync
+  -> read .planning/rules/INDEX.md
+  -> read .context/spec/index.md
+  -> read .planning/navigation/INDEX.md
+  -> collect changed files with per-repo cursor
+  -> classify files and affected codebases
+  -> choose Light / Medium / Full
+  -> run selected sync actions
+  -> validate / audit
+  -> mark per-repo cursor synced after successful after-pull sync
+  -> update STATE change log when files were modified
+  -> report result and residual risk
+```
+
+## Cursor State
+
+Maintain pull synchronization state in:
+
+```text
+.planning/context-sync-state.json
+```
+
+This file is workflow-owned machine state. It stores one cursor per independently discovered Git repository:
+
+```json
+{
+  "version": 1,
+  "updated_at": "2026-07-23T10:00:00+00:00",
+  "repos": {
+    "skit": {
+      "path": "skit",
+      "last_synced_head": "6f1847b66cbf19d9cf040d6e4e71d4f3d7a9942a",
+      "last_synced_branch": "master",
+      "last_synced_at": "2026-07-23T10:00:00+00:00",
+      "last_mode": "after-pull"
+    }
+  }
+}
+```
+
+Rules:
+
+- Discover repositories from `.planning/navigation/INDEX.md` Codebase Registry, then deduplicate by `git rev-parse --show-toplevel`.
+- For `--after-pull`, diff `last_synced_head..HEAD` per repo.
+- If a repo has no cursor yet, fall back to `ORIG_HEAD..HEAD` for that repo.
+- If the stored cursor is unavailable or not an ancestor of `HEAD`, use the script-reported fallback/warning and prefer a broader sync level.
+- Do not mark a cursor before sync, validation, and audit succeed.
+- On repeat execution with cursor equal to `HEAD`, report no new pull changes and do not reprocess the same commit range.
+- For local uncommitted `--after-bugfix` or `--after-implementation`, keep using worktree diffs; do not advance the pull cursor unless the mode is explicitly after-pull or the changed facts are committed and intentionally marked synced.
+
+## Changed File Collection
+
+Use the first reliable source:
+
+| Mode | Command |
+|---|---|
+| `--after-pull` | `devflow_context_cursor(args=["--project-root", ".", "collect", "--after-pull"])` |
+| `--after-bugfix` | `git diff --name-only` plus `git diff --cached --name-only` |
+| `--after-implementation` | `git diff --name-only` plus `git diff --cached --name-only` |
+| `--changed-files` | user-provided list |
+| fallback | `git status --short` |
+
+For `--after-pull`, parse the script JSON and use its top-level `changed_files`. Paths are already normalized relative to the project root, for example `skit/frontend/h5/src/root.tsx`.
+
+The script handles multiple repositories and repeated pulls:
+
+```text
+devflow_context_cursor(args=["--project-root", ".", "collect", "--after-pull"])
+devflow_context_cursor(args=["--project-root", ".", "collect", "--after-pull", "--format", "files"])
+```
+
+If the script is unavailable or fails, fall back to `git -C skit diff --name-only ORIG_HEAD..HEAD`, clearly report the degraded cursor behavior, and prefer Medium or Full when safety is unclear.
+
+After a successful `--after-pull` sync, update the cursor:
+
+```text
+devflow_context_cursor(args=["--project-root", ".", "mark-synced", "--mode", "after-pull"])
+```
+
+## Classification
+
+Map paths to codebases:
+
+| Codebase | Paths |
+|---|---|
+| skit-admin | `skit/frontend/admin/**` |
+| skit-h5 | `skit/frontend/h5/**` |
+| skit-backend | `skit/internal/**`, `skit/ioc/**`, `skit/pkg/**`, `skit/backend/migrations/**`, `skit/go.mod`, `skit/Makefile`, `skit/main.go` |
+| project context | `.planning/**`, `.context/spec/**`, `.omp/**`, `AGENTS.md` |
+
+Classify impact:
+
+| Impact | Examples | Default Level |
+|---|---|---|
+| tests-only | `*_test.go`, `*.test.ts`, `*.test.tsx`, `tests/**` | Light |
+| code-only | implementation internals, component-only edits, helper logic | Light |
+| route/api/page | `src/routes.ts`, `src/routes/*.tsx`, `src/lib/api/*.ts`, `src/admin/pages/*.tsx` | Medium |
+| backend boundary | `internal/web/*handler.go`, `ioc/web.go`, `internal/job/**`, public service interfaces | Medium |
+| toolchain/manifest | `package.json`, `go.mod`, `Makefile`, vite/router config | Medium or Full |
+| structure | codebase roots, large directory moves, new top-level/second-level directories | Full |
+| context docs | `.planning/**`, `.context/spec/**` | validate consistency; avoid blind overwrite |
+
+## Sync Levels
+
+### Light
+
+Use for ordinary bug fixes, tests-only changes, and internal implementation edits.
+
+Actions:
+
+```text
+devflow_code_index(action="scan", changedFiles=["<changed-file>", "..."])
+devflow_code_index(action="validate")
+devflow_code_index(action="audit")
+```
+
+Then append a concise `.planning/STATE.md` change-log line if this skill modified files.
+
+### Medium
+
+Use when changed files can alter human navigation or rule docs: routes, API clients, handler registrations, jobs, page inventory, service boundaries, package commands, manifests.
+
+Actions:
+
+1. Run Light changed-file indexing.
+2. Read relevant changed source files.
+3. Read matching navigation/spec entry for each affected codebase.
+4. Update only stale sections, usually:
+   - `.planning/navigation/{codebase}.md`
+   - `.context/spec/frontend|backend/{codebase}.md` only when a codebase rule or stack fact changed
+   - `.planning/toolchain.md` only when commands/manifests changed
+   - `.planning/STATE.md` change log
+5. Validate and audit code-index again if navigation/spec edits introduce new files or references.
+
+### Full
+
+Use only when minimal sync cannot preserve trust.
+
+Triggers:
+
+- User passes `--full`.
+- Changed files count exceeds 30 and includes structural or manifest changes.
+- Codebase root or package layout changes.
+- Framework/package-manager major version changes.
+- Full route/controller/page inventory is no longer trustworthy.
+- `code_index.py audit` fails or reports stale/missing facts that changed-file sync cannot resolve.
+
+Actions:
+
+```text
+workflow-project-context --with-code-index
+review gate
+STATE update
+```
+
+If Full is not explicitly requested, explain why it is needed before running it unless the user asked for automatic synchronization.
+
+## Escalation Rules
+
+Upgrade to at least Medium when any changed path matches:
+
+```text
+skit/internal/web/*handler.go
+skit/ioc/web.go
+skit/internal/job/**
+skit/frontend/h5/src/routes.ts
+skit/frontend/h5/src/routes/*.tsx
+skit/frontend/h5/src/lib/api/*.ts
+skit/frontend/admin/src/admin/pages/*.tsx
+skit/frontend/admin/src/lib/api/*.ts
+skit/frontend/*/package.json
+skit/frontend/*/vite.config.ts
+skit/frontend/h5/react-router.config.ts
+skit/go.mod
+skit/Makefile
+```
+
+Upgrade to Full when:
+
+```text
+changed files > 30 with structural/manifest impact
+new/deleted top-level or second-level source directories
+codebase root changed
+navigation/spec conflicts with source evidence
+code-index audit fails after a Light/Medium sync
+```
+
+## Adversarial Review
+
+Before modifying context files, challenge the plan:
+
+- **Over-refresh risk**: Am I about to run Full for a local implementation change? Downgrade to Light unless structure changed.
+- **Under-refresh risk**: Did route/API/handler/page/service/toolchain files change? If yes, do not stop at code-index only.
+- **Evidence risk**: Am I updating navigation/spec without reading the changed source/manifest? Read evidence first.
+- **Context pollution risk**: Am I turning a guess into a rule? Mark inferred facts as `代码推断` or do not write them.
+- **User-content risk**: Am I rewriting business context, requirements, or manual notes? Preserve them; append logs instead.
+- **Dirty tree risk**: Are unrelated user changes present? Do not revert or overwrite them.
+
+If any answer is unsafe, stop, report the risk, and choose a narrower action.
+
+## Dry Run Output
+
+For `--dry-run`, report:
+
+```text
+Context Sync Plan
+
+Mode:
+- after-bugfix | after-implementation | after-pull | changed-files
+
+Changed files:
+- ...
+
+Classification:
+- affected codebases: ...
+- impacts: ...
+- recommended level: Light|Medium|Full
+
+Planned actions:
+- ...
+
+Skipped:
+- ...
+
+Questions:
+- only if needed
+```
+
+Do not modify files in dry-run.
+
+## Final Report
+
+After execution, report:
+
+```text
+Context Sync Report
+
+Mode:
+- after-bugfix | after-implementation | after-pull | changed-files
+
+Changed files:
+- ...
+
+Classification:
+- affected codebases: ...
+- sync level: ...
+
+Actions:
+- code-index changed-files: passed
+- navigation checked/updated: ...
+- spec checked/updated: ...
+- cursor state: updated/skipped/fallback
+- STATE change log: appended/skipped
+
+Audit:
+- validate passed/failed
+- audit passed/failed
+
+Residual:
+- pending command gaps or skipped sync areas
+```
+
+If sync was skipped because the user requested it, state that explicitly.
+
+After all required validation succeeds, acknowledge the exact change set through the OMP runtime tool:
+
+```text
+devflow_context_sync(action="ack", level="<Light|Medium|Full>")
+```
+
+Do not acknowledge before the selected sync actions and their validation complete. The acknowledgement stores a content signature, so a later source edit invalidates it and reopens the Stop gate.
+
+## Integration With Other Workflows
+
+For bug fixes:
+
+```text
+workflow-bug-fix
+  -> implement fix
+  -> run verification
+  -> capture lessons
+  -> workflow-context-sync --after-bugfix
+  -> final response
+```
+
+For feature implementation:
+
+```text
+workflow-execute-phase
+  -> implement phase tasks
+  -> run required verification
+  -> update execution state
+  -> workflow-context-sync --after-implementation
+  -> final response
+```
+
+For direct OMP edits outside a workflow phase:
+
+```text
+direct code edit
+  -> run required verification
+  -> workflow-context-sync --after-implementation
+  -> final response
+```
+
+For external updates:
+
+```text
+git pull
+  -> workflow-context-sync --after-pull
+```
+
+For manual repair:
+
+```text
+workflow-context-sync --changed-files <files>
+```

package/plugins/devflow-intel/skills/workflow-context-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Workflow Context Sync"
+  short_description: "Sync project context after code changes"
+  default_prompt: "Use $workflow-context-sync to sync project context after a pull, bug fix, implementation, or changed files."

package/plugins/devflow-intel/skills/workflow-context-sync/scripts/context_sync_cursor.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Collect changed files for workflow-context-sync using per-repo cursors."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_STATE = ".planning/context-sync-state.json"
+NAVIGATION_INDEX = ".planning/navigation/INDEX.md"
+
+
+def run_git(repo: Path, args: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        check=check,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+
+def git_output(repo: Path, args: list[str]) -> str:
+    return run_git(repo, args).stdout.strip()
+
+
+def normalize_rel(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.resolve().as_posix()
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"version": 1, "repos": {}}
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict):
+        raise ValueError(f"state file is not an object: {path}")
+    data.setdefault("version", 1)
+    data.setdefault("repos", {})
+    return data
+
+
+def save_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def codebase_paths_from_navigation(project_root: Path) -> list[Path]:
+    index_path = project_root / NAVIGATION_INDEX
+    if not index_path.exists():
+        return []
+    text = index_path.read_text(encoding="utf-8")
+    match = re.search(r"^## Codebase Registry\s*$([\s\S]*?)(?=^## |\Z)", text, re.MULTILINE)
+    section = match.group(1) if match else text
+    paths: list[Path] = []
+    for line in section.splitlines():
+        if not line.startswith("|") or "`" not in line:
+            continue
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) < 2 or cells[0] in {"Name", "---"}:
+            continue
+        code_path_match = re.search(r"`([^`]+)`", cells[1])
+        if code_path_match:
+            paths.append(project_root / code_path_match.group(1))
+    return paths
+
+
+def discover_repos(project_root: Path) -> list[dict[str, str]]:
+    candidates = codebase_paths_from_navigation(project_root)
+    if not candidates:
+        candidates = [project_root / "skit", project_root]
+
+    repos_by_root: dict[str, dict[str, str]] = {}
+    for candidate in candidates:
+        if not candidate.exists():
+            continue
+        result = run_git(candidate, ["rev-parse", "--show-toplevel"], check=False)
+        if result.returncode != 0:
+            continue
+        repo_root = Path(result.stdout.strip()).resolve()
+        repo_id = normalize_rel(repo_root, project_root)
+        repos_by_root[str(repo_root)] = {
+            "id": repo_id,
+            "path": repo_id,
+            "abs_path": str(repo_root),
+        }
+    return sorted(repos_by_root.values(), key=lambda item: item["id"])
+
+
+def commit_exists(repo: Path, commit: str) -> bool:
+    if not commit:
+        return False
+    return run_git(repo, ["rev-parse", "--verify", f"{commit}^{{commit}}"], check=False).returncode == 0
+
+
+def is_ancestor(repo: Path, base: str, head: str) -> bool:
+    return run_git(repo, ["merge-base", "--is-ancestor", base, head], check=False).returncode == 0
+
+
+def merge_base(repo: Path, left: str, right: str) -> str:
+    result = run_git(repo, ["merge-base", left, right], check=False)
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def diff_files(repo: Path, project_root: Path, repo_id: str, base: str, head: str) -> list[str]:
+    if base == head:
+        return []
+    output = git_output(repo, ["diff", "--name-only", f"{base}..{head}"])
+    files = [line.strip() for line in output.splitlines() if line.strip()]
+    prefix = "" if repo_id in {"", "."} else f"{repo_id}/"
+    return [f"{prefix}{path}" for path in files]
+
+
+def select_base(repo: Path, repo_state: dict[str, Any], head: str) -> tuple[str, str, list[str]]:
+    warnings: list[str] = []
+    cursor = str(repo_state.get("last_synced_head", "")).strip()
+    if cursor:
+        if not commit_exists(repo, cursor):
+            warnings.append("stored cursor commit is unavailable; falling back to ORIG_HEAD")
+        elif cursor == head:
+            return head, "cursor", warnings
+        elif is_ancestor(repo, cursor, head):
+            return cursor, "cursor", warnings
+        else:
+            base = merge_base(repo, cursor, head)
+            if base:
+                warnings.append("stored cursor is not an ancestor of HEAD; using merge-base")
+                return base, "cursor_merge_base", warnings
+            warnings.append("stored cursor has no merge-base with HEAD; falling back to ORIG_HEAD")
+
+    if commit_exists(repo, "ORIG_HEAD"):
+        orig_head = git_output(repo, ["rev-parse", "ORIG_HEAD"])
+        if orig_head != head:
+            return orig_head, "ORIG_HEAD", warnings
+    warnings.append("no usable cursor or ORIG_HEAD; treating repository as already synced")
+    return head, "none", warnings
+
+
+def collect(project_root: Path, state_path: Path, output_format: str) -> int:
+    state = load_json(state_path)
+    repos = discover_repos(project_root)
+    changed_files: list[str] = []
+    repo_results: list[dict[str, Any]] = []
+
+    for repo_meta in repos:
+        repo = Path(repo_meta["abs_path"])
+        repo_id = repo_meta["id"]
+        head = git_output(repo, ["rev-parse", "HEAD"])
+        branch = run_git(repo, ["branch", "--show-current"], check=False).stdout.strip()
+        repo_state = state.get("repos", {}).get(repo_id, {})
+        base, source, warnings = select_base(repo, repo_state, head)
+        files = diff_files(repo, project_root, repo_id, base, head)
+        changed_files.extend(files)
+        repo_results.append({
+            "id": repo_id,
+            "path": repo_meta["path"],
+            "branch": branch,
+            "base": base,
+            "base_source": source,
+            "head": head,
+            "changed_files": files,
+            "warnings": warnings,
+        })
+
+    changed_files = sorted(dict.fromkeys(changed_files))
+    payload = {
+        "version": 1,
+        "state_path": normalize_rel(state_path, project_root),
+        "repos": repo_results,
+        "changed_files": changed_files,
+    }
+    if output_format == "files":
+        sys.stdout.write("\n".join(changed_files))
+        if changed_files:
+            sys.stdout.write("\n")
+    else:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n")
+    return 0
+
+
+def mark_synced(project_root: Path, state_path: Path, mode: str) -> int:
+    state = load_json(state_path)
+    repos = discover_repos(project_root)
+    now = datetime.now(timezone.utc).isoformat()
+    state["version"] = 1
+    state["updated_at"] = now
+    state.setdefault("repos", {})
+    for repo_meta in repos:
+        repo = Path(repo_meta["abs_path"])
+        repo_id = repo_meta["id"]
+        state["repos"][repo_id] = {
+            "path": repo_meta["path"],
+            "last_synced_head": git_output(repo, ["rev-parse", "HEAD"]),
+            "last_synced_branch": run_git(repo, ["branch", "--show-current"], check=False).stdout.strip(),
+            "last_synced_at": now,
+            "last_mode": mode,
+        }
+    save_json(state_path, state)
+    sys.stdout.write(json.dumps({
+        "state_path": normalize_rel(state_path, project_root),
+        "updated_at": now,
+        "repos": state["repos"],
+    }, ensure_ascii=False, indent=2, sort_keys=True) + "\n")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project-root", default=".", help="workspace/project root")
+    parser.add_argument("--state", default=DEFAULT_STATE, help="cursor state file")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    collect_parser = subparsers.add_parser("collect", help="collect changed files since cursor")
+    collect_parser.add_argument("--after-pull", action="store_true", help="document after-pull intent")
+    collect_parser.add_argument("--format", choices=["json", "files"], default="json")
+
+    mark_parser = subparsers.add_parser("mark-synced", help="mark all discovered repos synced at HEAD")
+    mark_parser.add_argument("--mode", default="after-pull")
+
+    args = parser.parse_args()
+    project_root = Path(args.project_root).resolve()
+    state_path = (project_root / args.state).resolve()
+    if args.command == "collect":
+        return collect(project_root, state_path, args.format)
+    if args.command == "mark-synced":
+        return mark_synced(project_root, state_path, args.mode)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())