@aipper/aiws-spec 0.0.27 → 0.0.29

package/templates/workspace/.opencode/commands/ws-verify-before-complete.md

@@ -4,24 +4,15 @@ description: 完成前验证：finish / handoff 前检查双审查与 validate/e
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-verify-before-complete -->
 # ws verify before complete
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws verify-bc`.
 
-目标：在 `/ws-finish` 或 `/ws-handoff` 前检查双审查、validate stamp 与 evidence 是否齐全。
-
-步骤（建议）：
-1) 检查以下最小 gate：
-   - `changes/<change-id>/review/spec-review.md`
-   - `changes/<change-id>/review/quality-review.md`
-   - `.agentdocs/tmp/aiws-validate/*.json`
-2) 若存在 `changes/<change-id>/evidence/`，检查 review / validate / collaboration summary 是否已收敛。
-3) 将结果落盘到：
-   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
-   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
-4) 输出：
-   - `证据（Evidence）:`
-   - `结论（Result）: pass|fail`
-   - `缺失项（Missing）:`
-   - `下一步（Next）:`
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws verify-bc
+elif command -v aiws >/dev/null 2>&1; then
+  aiws verify-bc
+else
+  npx @aipper/aiws verify-bc
+fi
+```
 <!-- AIWS_MANAGED_END:opencode:ws-verify-before-complete -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/helpers/approval-whitelist-check.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workspace_root="${1:-.}"
+shift || true
+
+command_text=""
+decision_kind="unknown"
+paths=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --command)
+      command_text="${2:-}"
+      shift 2
+      ;;
+    --kind)
+      decision_kind="${2:-unknown}"
+      shift 2
+      ;;
+    --path)
+      paths+=("${2:-}")
+      shift 2
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+python3 - "$workspace_root" "$command_text" "$decision_kind" "${paths[@]-}" <<'PY'
+import json
+import os
+import shlex
+import sys
+from datetime import datetime, timezone
+from fnmatch import fnmatch
+from pathlib import Path
+
+workspace_root = Path(sys.argv[1]).resolve()
+command_text = sys.argv[2]
+decision_kind = sys.argv[3]
+paths = sys.argv[4:]
+
+config_path = workspace_root / ".opencode" / "oh-my-opencode.json"
+out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".agentdocs" / "tmp" / "opencode-autonomy"))
+out_dir.mkdir(parents=True, exist_ok=True)
+log_file = out_dir / "approval-whitelist.log"
+result_file = out_dir / "approval-whitelist-last.json"
+
+decision = "manual"
+reason = "missing_policy"
+policy = None
+
+def normalize_signature(command: str) -> str:
+    if not command.strip():
+        return ""
+    tokens = shlex.split(command)
+    if not tokens:
+        return ""
+    if tokens[0] == "git" and len(tokens) >= 2:
+        return f"git {tokens[1]}"
+    return tokens[0]
+
+if config_path.exists():
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        payload = {
+            "workspace_root": str(workspace_root),
+            "config_path": str(config_path),
+            "command": command_text,
+            "command_signature": normalize_signature(command_text) if command_text.strip() else "",
+            "kind": decision_kind,
+            "paths": paths,
+            "decision": "manual",
+            "reason": "invalid_config_json",
+        }
+        result_file.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        with log_file.open("a", encoding="utf-8") as fh:
+            fh.write(f"[{timestamp}] decision=manual reason=invalid_config_json kind={decision_kind} signature={(payload['command_signature'] or '(empty)')} paths={paths}\n")
+        print(json.dumps(payload, ensure_ascii=False))
+        sys.exit(0)
+    policy = raw.get("aiws", {}).get("autonomy", {}).get("approval_whitelist", {})
+
+def path_matches(target: str, patterns: list[str]) -> bool:
+    normalized = target.replace("\\", "/")
+    for pattern in patterns:
+        if fnmatch(normalized, pattern):
+            return True
+        if pattern.endswith("/") and fnmatch(normalized, f"{pattern}*"):
+            return True
+    return False
+
+command_signature = normalize_signature(command_text)
+
+payload = {
+    "workspace_root": str(workspace_root),
+    "config_path": str(config_path),
+    "command": command_text,
+    "command_signature": command_signature,
+    "kind": decision_kind,
+    "paths": paths,
+    "decision": decision,
+    "reason": reason,
+}
+
+if policy and policy.get("enabled") is True:
+    deny_commands = [item for item in policy.get("deny_commands", []) if isinstance(item, str) and item.strip()]
+    deny_paths = [item for item in policy.get("deny_paths", []) if isinstance(item, str) and item.strip()]
+    read_only_commands = [item for item in policy.get("read_only_commands", []) if isinstance(item, str) and item.strip()]
+    write_allow_paths = [item for item in policy.get("write_allow_paths", []) if isinstance(item, str) and item.strip()]
+    host_permission_mode = policy.get("host_permission_mode", "")
+
+    if decision_kind == "host-permission":
+        decision = "manual"
+        reason = f"host_permission_mode={host_permission_mode or 'missing'}"
+    elif command_signature in deny_commands:
+        decision = "deny"
+        reason = "deny_command"
+    elif any(path_matches(path, deny_paths) for path in paths):
+        decision = "deny"
+        reason = "deny_path"
+    elif decision_kind == "read" and command_signature in read_only_commands:
+        decision = "allow"
+        reason = "read_only_command"
+    elif decision_kind == "write" and paths and all(path_matches(path, write_allow_paths) for path in paths):
+        decision = "allow"
+        reason = "write_allow_path"
+    else:
+        decision = "manual"
+        reason = "policy_requires_manual_review"
+
+    payload["host_permission_mode"] = host_permission_mode
+    payload["policy_mode"] = policy.get("mode", "")
+
+payload["decision"] = decision
+payload["reason"] = reason
+result_file.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+with log_file.open("a", encoding="utf-8") as fh:
+    fh.write(f"[{timestamp}] decision={decision} reason={reason} kind={decision_kind} signature={command_signature or '(empty)'} paths={paths}\n")
+
+print(json.dumps(payload, ensure_ascii=False))
+PY

package/templates/workspace/.opencode/helpers/approval-whitelist-run.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workspace_root="${1:-.}"
+shift || true
+
+helper_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+check_script="${helper_dir}/approval-whitelist-check.sh"
+
+if [[ ! -x "${check_script}" && ! -f "${check_script}" ]]; then
+  echo "error: missing checker: ${check_script}" >&2
+  exit 2
+fi
+
+decision_json="$(bash "${check_script}" "${workspace_root}" "$@")"
+
+python3 - "${workspace_root}" "${decision_json}" <<'PY'
+import json
+import os
+import shlex
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+workspace_root = Path(sys.argv[1]).resolve()
+payload = json.loads(sys.argv[2])
+
+out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".agentdocs" / "tmp" / "opencode-autonomy"))
+out_dir.mkdir(parents=True, exist_ok=True)
+log_file = out_dir / "approval-whitelist-exec.log"
+result_file = out_dir / "approval-whitelist-exec-last.json"
+
+decision = payload.get("decision", "manual")
+command_text = str(payload.get("command", ""))
+
+def finish(result: dict, exit_code: int) -> None:
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    result_file.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    with log_file.open("a", encoding="utf-8") as fh:
+        fh.write(
+            f"[{timestamp}] decision={result.get('decision')} executed={result.get('executed')} exit_code={result.get('exit_code')} reason={result.get('reason')} command={result.get('command_signature') or '(empty)'}\n"
+        )
+    print(json.dumps(result, ensure_ascii=False))
+    sys.exit(exit_code)
+
+if decision == "deny":
+    finish({**payload, "executed": False, "exit_code": None, "reason": payload.get("reason", "deny_command")}, 4)
+
+if decision != "allow":
+    finish({**payload, "executed": False, "exit_code": None, "reason": payload.get("reason", "manual_review_required")}, 3)
+
+if not command_text.strip():
+    finish({**payload, "decision": "manual", "executed": False, "exit_code": None, "reason": "empty_command"}, 3)
+
+unsafe_fragments = ["&&", "||", ";", "|", ">", "<", "$(", "`"]
+if any(fragment in command_text for fragment in unsafe_fragments):
+    finish({**payload, "decision": "manual", "executed": False, "exit_code": None, "reason": "unsupported_shell_syntax"}, 3)
+
+command_args = shlex.split(command_text)
+if not command_args:
+    finish({**payload, "decision": "manual", "executed": False, "exit_code": None, "reason": "empty_command"}, 3)
+
+proc = subprocess.run(
+    command_args,
+    cwd=str(workspace_root),
+    text=True,
+    capture_output=True,
+    check=False,
+)
+
+result = {
+    **payload,
+    "executed": True,
+    "exit_code": proc.returncode,
+    "stdout_line_count": len(proc.stdout.splitlines()),
+    "stderr_line_count": len(proc.stderr.splitlines()),
+    "reason": "executed",
+}
+
+finish(result, proc.returncode)
+PY

package/templates/workspace/.opencode/helpers/approval-whitelist-watchdog.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workspace_root="${1:-.}"
+shift || true
+
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-${workspace_root}/.agentdocs/tmp/opencode-autonomy}"
+queue_file="${out_dir}/approval-watchdog-queue.jsonl"
+once=false
+poll_ms=2000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --queue)
+      queue_file="${2:-}"
+      shift 2
+      ;;
+    --once)
+      once=true
+      shift
+      ;;
+    --poll-ms)
+      poll_ms="${2:-2000}"
+      shift 2
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+helper_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+runner_script="${helper_dir}/approval-whitelist-run.sh"
+
+python3 - "$workspace_root" "$queue_file" "$runner_script" "$poll_ms" "$once" <<'PY'
+import json
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+workspace_root = Path(sys.argv[1]).resolve()
+queue_file = Path(sys.argv[2]).resolve()
+runner_script = Path(sys.argv[3]).resolve()
+poll_ms = max(int(sys.argv[4]), 100)
+once = sys.argv[5].lower() == "true"
+
+out_dir = queue_file.parent
+out_dir.mkdir(parents=True, exist_ok=True)
+results_file = out_dir / "approval-watchdog-results.jsonl"
+state_file = out_dir / "approval-watchdog-state.json"
+log_file = out_dir / "approval-watchdog.log"
+
+def now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+def load_state() -> dict:
+    if not state_file.exists():
+        return {"processed_ids": [], "last_run_at": None, "processed_count": 0}
+    return json.loads(state_file.read_text(encoding="utf-8"))
+
+def save_state(state: dict) -> None:
+    state_file.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+def append_log(message: str) -> None:
+    with log_file.open("a", encoding="utf-8") as fh:
+        fh.write(f"[{now()}] {message}\n")
+
+def normalize_entry(raw: dict, index: int) -> dict:
+    entry_id = str(raw.get("id") or f"queue-{index}")
+    kind = str(raw.get("kind") or "unknown")
+    command = str(raw.get("command") or "")
+    paths = raw.get("paths") if isinstance(raw.get("paths"), list) else []
+    paths = [str(item) for item in paths if str(item).strip()]
+    return {"id": entry_id, "kind": kind, "command": command, "paths": paths}
+
+def run_entry(entry: dict) -> dict:
+    args = ["bash", str(runner_script), str(workspace_root), "--kind", entry["kind"], "--command", entry["command"]]
+    for path in entry["paths"]:
+        args.extend(["--path", path])
+    proc = subprocess.run(args, cwd=str(workspace_root), text=True, capture_output=True, check=False)
+    stdout = proc.stdout.strip()
+    payload = json.loads(stdout) if stdout else {}
+    result = {
+        "id": entry["id"],
+        "queued_kind": entry["kind"],
+        "queued_command": entry["command"],
+        "queued_paths": entry["paths"],
+        "runner_exit_code": proc.returncode,
+        "result": payload,
+        "processed_at": now(),
+    }
+    with results_file.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(result, ensure_ascii=False) + "\n")
+    append_log(
+        f"id={entry['id']} exit_code={proc.returncode} decision={payload.get('decision', 'unknown')} executed={payload.get('executed', False)}"
+    )
+    return result
+
+def process_pending() -> int:
+    state = load_state()
+    processed_ids = set(str(item) for item in state.get("processed_ids", []))
+    processed_now = 0
+    if not queue_file.exists():
+        state["last_run_at"] = now()
+        save_state(state)
+        append_log("queue_missing")
+        return processed_now
+    lines = queue_file.read_text(encoding="utf-8").splitlines()
+    for index, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        raw = json.loads(stripped)
+        entry = normalize_entry(raw, index)
+        if entry["id"] in processed_ids:
+            continue
+        run_entry(entry)
+        processed_ids.add(entry["id"])
+        processed_now += 1
+    state["processed_ids"] = sorted(processed_ids)
+    state["processed_count"] = len(processed_ids)
+    state["last_run_at"] = now()
+    save_state(state)
+    append_log(f"cycle_complete processed_now={processed_now}")
+    return processed_now
+
+if once:
+    process_pending()
+    print(state_file)
+    sys.exit(0)
+
+append_log(f"watchdog_start poll_ms={poll_ms}")
+try:
+    while True:
+        process_pending()
+        time.sleep(poll_ms / 1000.0)
+except KeyboardInterrupt:
+    append_log("watchdog_stop keyboard_interrupt")
+    print(state_file)
+    sys.exit(0)
+PY

package/templates/workspace/.opencode/helpers/tmux-swarm-rescue.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "error: tmux not found" >&2
+  exit 1
+fi
+
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-.agentdocs/tmp/opencode-autonomy}"
+scan_file="${1:-${out_dir}/tmux-scan.json}"
+log_file="${out_dir}/tmux-rescue.log"
+mkdir -p "${out_dir}"
+
+if [[ ! -f "${scan_file}" ]]; then
+  echo "error: scan file missing: ${scan_file}" >&2
+  exit 1
+fi
+
+python3 - "${scan_file}" "${log_file}" <<'PY'
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+scan_file, log_file = sys.argv[1:3]
+
+def tmux(*args):
+    subprocess.run(["tmux", *args], check=True)
+
+with open(scan_file, "r", encoding="utf-8") as fh:
+    payload = json.load(fh)
+
+actions = []
+for pane in payload.get("panes", []):
+    target = str(pane.get("target", ""))
+    if not target:
+        continue
+    if pane.get("waiting_confirm") is True:
+        tmux("send-keys", "-t", target, "y", "Enter")
+        actions.append((target, "confirm_yes"))
+        continue
+    if pane.get("press_enter") is True:
+        tmux("send-keys", "-t", target, "Enter")
+        actions.append((target, "press_enter"))
+        continue
+    if pane.get("pane_in_mode") is True:
+        tmux("send-keys", "-t", target, "-X", "cancel")
+        actions.append((target, "cancel_copy_mode"))
+
+timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+with open(log_file, "a", encoding="utf-8") as fh:
+    for target, action in actions:
+        fh.write(f"[{timestamp}] {target} {action}\n")
+
+print(log_file)
+PY

package/templates/workspace/.opencode/helpers/tmux-swarm-scan.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "error: tmux not found" >&2
+  exit 1
+fi
+
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-.agentdocs/tmp/opencode-autonomy}"
+out_file="${out_dir}/tmux-scan.json"
+mkdir -p "${out_dir}"
+
+python3 - "$out_file" <<'PY'
+import json
+import subprocess
+import sys
+
+out_file = sys.argv[1]
+
+def run(cmd):
+    return subprocess.run(cmd, check=True, text=True, capture_output=True).stdout
+
+panes_raw = run(["tmux", "list-panes", "-a", "-F", "#{session_name}:#{window_index}.#{pane_index}\t#{pane_current_command}\t#{pane_current_path}\t#{pane_in_mode}"]).splitlines()
+panes = []
+for row in panes_raw:
+    target, command, current_path, in_mode = row.split("\t", 3)
+    capture = run(["tmux", "capture-pane", "-t", target, "-p", "-S", "-80"])
+    lowered = capture.lower()
+    panes.append(
+        {
+            "target": target,
+            "command": command,
+            "current_path": current_path,
+            "pane_in_mode": in_mode == "1",
+            "waiting_confirm": "(y/n)" in lowered,
+            "press_enter": "press enter to continue" in lowered,
+            "error_like": any(token in lowered for token in ["traceback", "error", "failed", "fatal"]),
+            "tail": capture.splitlines()[-20:],
+        }
+    )
+
+with open(out_file, "w", encoding="utf-8") as fh:
+    json.dump({"panes": panes}, fh, ensure_ascii=False, indent=2)
+
+print(out_file)
+PY

package/templates/workspace/.opencode/oh-my-opencode.json.example

@@ -2,16 +2,76 @@
   "agents": {
     "planner-sisyphus": {
       "enabled": true,
-      "replace_plan": false
+      "replace_plan": false,
+      "categories": [
+        "planning",
+        "autonomous"
+      ],
+      "prompt_append": "You are running inside an AIWS workspace. Before coding, read AI_PROJECT.md, REQUIREMENTS.md, and AI_WORKSPACE.md. Stay autonomous until the task is complete. Completion means: truth files read, task/change bound, required verify commands run, review/evidence written, and aiws validate . or change validate completed when applicable. Stop early only for a real blocker: missing user decision, missing credential, external dependency failure, or sandbox/permission failure."
     },
     "librarian": {
-      "enabled": true
+      "enabled": true,
+      "categories": [
+        "docs",
+        "research"
+      ]
     },
     "explore": {
-      "enabled": true
+      "enabled": true,
+      "categories": [
+        "code",
+        "analysis"
+      ]
     },
     "oracle": {
-      "enabled": true
+      "enabled": true,
+      "categories": [
+        "review",
+        "qa"
+      ]
+    }
+  },
+  "backgroundTasks": {
+    "enabled": true,
+    "maxJobs": 3,
+    "defaultTimeoutMs": 1200000
+  },
+  "experimental": {
+    "auto_resume": true
+  },
+  "aiws": {
+    "autonomy": {
+      "approval_whitelist": {
+        "enabled": true,
+        "mode": "assist-only",
+        "host_permission_mode": "manual-only",
+        "read_only_commands": [
+          "rg",
+          "cat",
+          "sed",
+          "ls",
+          "find",
+          "git status",
+          "git diff"
+        ],
+        "write_allow_paths": [
+          ".agentdocs/tmp/",
+          "changes/*/analysis/",
+          "changes/*/review/",
+          "changes/*/evidence/"
+        ],
+        "deny_paths": [
+          "secrets/",
+          ".env*"
+        ],
+        "deny_commands": [
+          "rm",
+          "mv",
+          "git commit",
+          "git push",
+          "npm publish"
+        ]
+      }
     }
   }
 }