@cyning/harness 0.3.0

package/wizard/templates/TASK_TEMPLATE_upstream_pr_v1.md

@@ -0,0 +1,164 @@
+# Task：<动词 + 范围> · #<issue>（阶段 C · OSS fork）
+
+> **状态**：`draft`  
+> **上游 Issue**：`<UPSTREAM>/issues/xxx`  
+> **关联图谱**：`docs/_tech_graph/01_struct.md` · **增量** `graph_delta` 见下表  
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **task_slug** | `<slug>` |
+| **test_strategy** | `required` / `recommended` / `not_applicable` |
+| **orchestration** | Kimi Code Agent · **R0+R1–R5 思考** → 22 → 30 |
+| **git_branch** | `feature/fix-<issue>-<short>` |
+| **worktree_root** | 产品仓 Open Folder |
+| **meta_worktree** | 过程轨 worktree（`cyning/meta`） |
+| **module_id** | 来自 `01_struct` |
+| **graph_delta** | `10_flow_*.md` 或 `none` |
+| **graph_delta_note** | `none` 时必填 |
+| **graph_gate** | `skeleton_before_30` · `close_partial_or_final` |
+
+### 人工闸
+
+| human_gate_id | status | blocks_hats | 说明 |
+|---------------|--------|-------------|------|
+| HG-TASK-DRAFT | pending | 22-R1, 30 | task + skeleton + **§4 思考轮闭合** |
+| HG-AUDIT-R1 | pending | 30 | 22 思考审查通过 + skeleton commit 后人签 |
+
+---
+
+## 1. 需求摘要
+
+（来自 Issue）
+
+---
+
+## 2. 非范围
+
+- harness / task / invoke 进上游 PR
+
+---
+
+## 3. 失败路径
+
+| 触发条件 | 系统行为 |
+|----------|----------|
+| `graph_delta≠none` 且无 skeleton commit | 30 拒开工 |
+| §4 R1–R5 仍有 `（待填）` 且无合法 **思考轮控制** | 22 退回 10 · 30 拒开工 |
+| `early_stop=yes` 但缺 reason / residual_risks | 22 退回 10 |
+| `HG-AUDIT-R1` pending | 30 拒开工 |
+| PR 已开但 meta 无图谱关账 | 不得 `done/` |
+
+---
+
+## 4. 思考轮次（改码前 · 默认 R0 + R1–R5）
+
+> **10 帽义务**：预置 **五槽思考轮**（C1–C3 实证）；见 [`docs/harness/prompts/10-requirements.md`](../../harness/prompts/10-requirements.md) OSS 阶段 C 节。  
+> **回填**：[`docs/harness/FRAGMENT_rethink_backfill_task_v1_zh.md`](../harness/FRAGMENT_rethink_backfill_task_v1_zh.md) — Agent **必须**写回 §4，禁止仅聊天输出。
+
+### 思考轮控制（Agent 填 · 22 审）
+
+| 字段 | 值 |
+|------|-----|
+| **actual_last_round** | `R5` / `R3` / …（最后实质完成轮） |
+| **early_stop** | `no` / `yes` |
+| **early_stop_reason** | （`early_stop=yes` **必填**） |
+| **residual_risks** | `none` 或逐条（**必填**；未增轮风险须写清） |
+
+### R0 · 读 task / Issue / graph_delta
+
+**回填区：**
+
+```text
+（待填）
+```
+
+### R1 · 代码事实
+
+**回填区：**
+
+```text
+（待填）
+```
+
+### R2 · 方案对比
+
+**回填区：**
+
+```text
+（待填）
+```
+
+### R3 · 边界 / 测试
+
+**回填区：**
+
+```text
+（待填）
+```
+
+### R4 · 测试与 PR 策略
+
+**回填区：**
+
+```text
+（待填）
+```
+
+### R5 · 图谱增量 + 关账判断
+
+**回填区：**
+
+```text
+（待填）
+```
+
+### R6+ · 扩展轮（仅当 Agent 增轮时追加）
+
+**扩展理由：**
+
+```text
+（无则删除本节）
+```
+
+**回填区：**
+
+```text
+（待填）
+```
+
+---
+
+## 5. 验收标准
+
+- [ ] §4 思考轮闭合 · **思考轮控制** 已填 · 22 思考审查通过
+- [ ] `HG-AUDIT-R1` → `approved`
+- [ ] 测试 / lint 通过
+- [ ] 上游 PR · `Fixes #<issue>`
+- [ ] invoke 落盘
+- [ ] **图谱**（触模块时必勾）：30 前 skeleton · 关账 partial + `02_version`
+
+---
+
+## 6. 验证命令
+
+```bash
+cd <worktree_root>
+git checkout main && git fetch upstream && git reset --hard upstream/main
+git checkout -b feature/fix-<issue>-<short>
+# 项目测试命令
+git diff upstream/main --name-only
+```
+
+---
+
+## 实现备忘（30 后回填）
+
+| 项 | 状态 |
+|----|------|
+| 图谱 | ⏳ |
+| 测试 | ⏳ |
+| 上游 PR | ⏳ |

package/wizard/templates/task_graph_bootstrap_v1.md

@@ -0,0 +1,53 @@
+# Task：图谱 bootstrap · __REPO_SLUG__ fork（阶段 B）
+
+> **状态**：in_progress  
+> **关联图谱**：`docs/_tech_graph/00_main.md` · `01_struct.md`  
+> **试点 POINTER**：[`docs/harness/POINTER_PILOT_adoption_workspace_v1_zh.md`](../../harness/POINTER_PILOT_adoption_workspace_v1_zh.md)
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **test_strategy** | `not_applicable` |
+| **test_strategy_note** | bootstrap 无业务 30；文档与人签关账 |
+| **orchestration** | Cursor Task 链 |
+| **audit_profile** | `human_only` |
+
+### 人工闸
+
+| human_gate_id | status | blocks_hats | 说明 |
+|---------------|--------|-------------|------|
+| HG-TASK-DRAFT | pending | 22-R1 | task 初稿人扫 |
+| HG-GRAPH-MODULES | pending | **30** | `01_struct` 模块表维护者人签 |
+
+---
+
+## 背景与目标
+
+个人 fork 上建立图谱最低交付：模块表 + 顶层图 + 待补 flow 清单（**不**一次画完全仓 flow）。
+
+---
+
+## 范围
+
+- [ ] `docs/_tech_graph/` 模板落盘
+- [ ] `01_struct` 一级模块表（对照仓内 `AGENTS.md` 或 README）
+- [ ] `00_main` 待补 flow 清单
+- [ ] 维护者签 `HG-GRAPH-MODULES` → `approved`
+
+## 非范围
+
+- 向上游 PR harness / 图谱过程文件
+- 本 task 内 30 改产品代码
+
+---
+
+## 分步图谱
+
+| 子步 | 阶段 |
+|------|------|
+| B1 模块表 + 00_main 清单 | **阶段 B（本 task）** |
+| B2 单条 flow 骨架 | B 可选 |
+| flow 终稿 | **阶段 C** 业务 task 增量 |

package/wizard/uninstall.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# cyning-harness · 清空已接入纪律层（便于删除后重新 install / upgrade）
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "$SCRIPT_DIR/lib/common.sh"
+HARNESS_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CYNING_HARNESS="${CYNING_HARNESS:-$HARNESS_ROOT}"
+
+TARGET=""
+ASSUME_YES=0
+WITH_CI=0
+WITH_INSTALL_ARTIFACTS=0
+DRY_RUN=0
+
+usage() {
+  cat <<'EOF'
+用法（推荐在 cyning-harness 产品包目录执行）:
+
+  cd /path/to/cyning-harness
+  ./wizard/uninstall.sh
+
+非交互:
+
+  ./wizard/uninstall.sh --target /path/to/project --yes
+  ./wizard/uninstall.sh --target /path/to/project --yes --with-ci --with-install-artifacts
+
+选项:
+  --target PATH              业务仓根（交互时可省略）
+  --yes                      预览后不再确认，直接清空
+  --with-ci                  额外删除与产品样例一致的 CI workflow（install preset 写入的）
+  --with-install-artifacts   额外删除 install 时写入的图谱/wiki/standards 模板副本
+  --dry-run                  仅预览，不删除
+  -h, --help                 显示本帮助
+
+默认保留（不删）:
+  docs/tasks/ · docs/harness/reviews/ · docs/harness/invokes/by-task/
+  docs/harness/FRAGMENT* · 业务自定义图谱正文
+
+清空后重新安装:
+  ./wizard/install.sh --target <业务仓> --preset harness-only --ide cursor,claude,agents
+  或 ./wizard/upgrade.sh --target <业务仓>
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --yes) ASSUME_YES=1; shift ;;
+    --with-ci) WITH_CI=1; shift ;;
+    --with-install-artifacts) WITH_INSTALL_ARTIFACTS=1; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "未知参数: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+echo "=== cyning-harness 清空向导 ==="
+echo "产品包: $HARNESS_ROOT"
+echo ""
+
+if [[ -z "$TARGET" ]]; then
+  echo "请输入要清空 Harness 纪律层的业务仓路径"
+  read -r -p "业务仓路径: " TARGET_INPUT
+  [[ -n "$TARGET_INPUT" ]] || { echo "未输入路径，已取消。" >&2; exit 1; }
+  TARGET="$TARGET_INPUT"
+fi
+
+[[ -d "$TARGET" ]] || { echo "错误: 目录不存在: $TARGET" >&2; exit 1; }
+TARGET="$(abs_path "$TARGET")"
+refuse_if_product_root "$TARGET" "$HARNESS_ROOT"
+
+PROFILE_FILE="$TARGET/.cyning-harness/profile.json"
+if [[ ! -f "$PROFILE_FILE" ]]; then
+  echo "未找到 $PROFILE_FILE — 该仓似乎未接入 Harness，无需清空。" >&2
+  exit 0
+fi
+
+PRESET_NAME="$(profile_preset_name "$PROFILE_FILE")"
+echo "目标仓: $TARGET"
+echo "preset: $PRESET_NAME"
+echo ""
+
+PLAN_LINES=()
+
+plan_remove_file() {
+  local path="$1" note="${2:-}"
+  if [[ -f "$path" ]]; then
+    PLAN_LINES+=("rm|$path|$note")
+  fi
+}
+
+plan_remove_marker() {
+  local path="$1" note="${2:-}"
+  if [[ -f "$path" ]] && grep -qF "$MARKER_BEGIN" "$path"; then
+    PLAN_LINES+=("marker|$path|$note")
+  fi
+}
+
+# harness-sync 同步项
+if profile_track_enabled "$PROFILE_FILE" harness_prompts false; then
+  for f in "$CYNING_HARNESS/harness/prompts/"*.md; do
+    [[ -f "$f" ]] || continue
+    plan_remove_file "$TARGET/docs/harness/prompts/$(basename "$f")" "harness prompts"
+  done
+fi
+
+if profile_track_enabled "$PROFILE_FILE" harness_invoke_template false; then
+  plan_remove_file "$TARGET/docs/harness/invokes/TEMPLATE_invoke.md" "invoke 模板"
+fi
+
+if profile_track_enabled "$PROFILE_FILE" ide_cursor true; then
+  plan_remove_file "$TARGET/$(profile_ide_cursor_rel "$PROFILE_FILE")" "Cursor 规则"
+fi
+
+if profile_track_enabled "$PROFILE_FILE" ide_claude false; then
+  plan_remove_marker "$TARGET/CLAUDE.md" "Claude IDE marker"
+fi
+
+if profile_track_enabled "$PROFILE_FILE" ide_agents false; then
+  plan_remove_marker "$TARGET/AGENTS.md" "Agents IDE marker"
+fi
+
+# install 可选轨（须显式 flag）
+if [[ "$WITH_INSTALL_ARTIFACTS" -eq 1 ]]; then
+  if profile_json_bool "$PROFILE_FILE" graph || grep -q '"graph"[[:space:]]*:[[:space:]]*true' "$PROFILE_FILE"; then
+    for f in "$CYNING_HARNESS/graph/templates/"*; do
+      [[ -f "$f" ]] || continue
+      plan_remove_file "$TARGET/docs/_tech_graph/$(basename "$f")" "graph 模板"
+    done
+  fi
+  if profile_json_bool "$PROFILE_FILE" wiki || grep -q '"wiki"[[:space:]]*:[[:space:]]*true' "$PROFILE_FILE"; then
+    for f in "$CYNING_HARNESS/coding_wiki/templates/"*; do
+      [[ -f "$f" ]] || continue
+      plan_remove_file "$TARGET/docs/coding_wiki/$(basename "$f")" "wiki 模板"
+    done
+  fi
+  for f in "$CYNING_HARNESS/standards/"TEMPLATE_CODING_BASELINE_L1*.md; do
+    [[ -f "$f" ]] || continue
+    plan_remove_file "$TARGET/docs/standards/$(basename "$f")" "standards L1"
+  done
+  for f in "$CYNING_HARNESS/standards/"TEMPLATE_CODING_BASELINE_L2*.md; do
+    [[ -f "$f" ]] || continue
+    plan_remove_file "$TARGET/docs/standards/$(basename "$f")" "standards L2"
+  done
+  for f in "$CYNING_HARNESS/standards/"TEMPLATE_SOURCES*.md; do
+    [[ -f "$f" ]] || continue
+    plan_remove_file "$TARGET/docs/standards/$(basename "$f")" "standards sources"
+  done
+  plan_remove_file "$TARGET/docs/tasks/active/task_graph_bootstrap.md" "bootstrap task"
+fi
+
+if [[ "$WITH_CI" -eq 1 ]]; then
+  plan_remove_file "$TARGET/.github/workflows/quality.yml" "CI quality（若存在）"
+  plan_remove_file "$TARGET/.github/workflows/pytest.yml" "CI pytest（若存在）"
+fi
+
+# profile 元数据（最后删）
+PLAN_LINES+=("rm_dir|$TARGET/.cyning-harness|接入配置")
+
+if [[ ${#PLAN_LINES[@]} -eq 0 ]]; then
+  echo "无待清空项。" >&2
+  exit 0
+fi
+
+echo ">>> 将清空以下项（业务 task / reviews / by-task invoke 默认保留）"
+echo ""
+for line in "${PLAN_LINES[@]}"; do
+  IFS='|' read -r kind path note <<<"$line"
+  case "$kind" in
+    rm) echo "  [删除文件 · $note] $path" ;;
+    marker) echo "  [剥离 marker · $note] $path" ;;
+    rm_dir) echo "  [删除目录 · $note] $path" ;;
+  esac
+done
+echo ""
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  echo "dry-run：未执行删除。"
+  exit 0
+fi
+
+DO_UNINSTALL=0
+if [[ "$ASSUME_YES" -eq 1 ]]; then
+  DO_UNINSTALL=1
+elif prompt_yes_no "确认清空以上 Harness 纪律层？" "n"; then
+  DO_UNINSTALL=1
+fi
+
+if [[ "$DO_UNINSTALL" -eq 0 ]]; then
+  echo "已取消。"
+  exit 0
+fi
+
+echo ""
+echo ">>> 执行清空"
+for line in "${PLAN_LINES[@]}"; do
+  IFS='|' read -r kind path note <<<"$line"
+  case "$kind" in
+    rm)
+      rm -f "$path"
+      echo "  已删除: $path"
+      ;;
+    marker)
+      remove_harness_marker_file "$path"
+      ;;
+    rm_dir)
+      rm -rf "$path"
+      echo "  已删除目录: $path"
+      ;;
+  esac
+done
+
+echo ""
+echo "清空完成。"
+echo "重新安装: $SCRIPT_DIR/install.sh --target $TARGET --preset $PRESET_NAME"
+echo "或升级向导: $SCRIPT_DIR/upgrade.sh --target $TARGET"

package/wizard/upgrade.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# cyning-harness · 交互式升级向导（在产品包目录运行，引导输入业务仓路径）
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "$SCRIPT_DIR/lib/common.sh"
+# shellcheck source=lib/manifest.sh
+source "$SCRIPT_DIR/lib/manifest.sh"
+HARNESS_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CYNING_HARNESS="${CYNING_HARNESS:-$HARNESS_ROOT}"
+
+TARGET=""
+IDE_LIST=""
+ASSUME_YES=0
+RUN_GATE=0
+SYNC_FORCE=0
+
+usage() {
+  cat <<'EOF'
+用法（推荐在 cyning-harness 产品包根目录执行）:
+
+  cd /path/to/cyning-harness
+  ./wizard/upgrade.sh
+
+非交互（脚本 / CI）:
+
+  ./wizard/upgrade.sh --target /path/to/project
+  ./wizard/upgrade.sh --target /path/to/project --ide cursor,claude,agents --yes
+  ./wizard/upgrade.sh --target /path/to/project --yes --gate-check
+  ./wizard/upgrade.sh --target /path/to/project --yes --force   # 跳过 S5 git-clean
+
+选项:
+  --target PATH    业务仓根（交互模式下可省略，运行时会提示输入）
+  --ide LIST       更新 IDE 勾选：cursor,claude,agents
+  --yes            预览 plan 后不再确认，直接 apply
+  --force          sync apply 跳过 S5 git-clean 检查
+  --gate-check     同步后运行 gate-check.sh
+  -h, --help       显示本帮助
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --ide) IDE_LIST="$2"; shift 2 ;;
+    --yes) ASSUME_YES=1; shift ;;
+    --force) SYNC_FORCE=1; shift ;;
+    --gate-check) RUN_GATE=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "未知参数: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+VERSION="${HARNESS_VERSION:-$(git -C "$HARNESS_ROOT" describe --tags --always 2>/dev/null || echo unknown)}"
+
+echo "=== cyning-harness 升级向导 ==="
+echo "产品包: $HARNESS_ROOT"
+echo "版本:   $VERSION"
+echo ""
+
+if [[ -z "$TARGET" ]]; then
+  echo "请输入已接入 Harness 的业务仓路径（绝对路径，例: /Users/you/Projects/kimi-code-meta）"
+  read -r -p "业务仓路径: " TARGET_INPUT
+  [[ -n "$TARGET_INPUT" ]] || { echo "未输入路径，已取消。" >&2; exit 1; }
+  TARGET="$TARGET_INPUT"
+fi
+
+[[ -d "$TARGET" ]] || { echo "错误: 目录不存在: $TARGET" >&2; exit 1; }
+TARGET="$(abs_path "$TARGET")"
+refuse_if_product_root "$TARGET" "$HARNESS_ROOT"
+
+PROFILE_FILE="$TARGET/.cyning-harness/profile.json"
+
+if [[ ! -f "$PROFILE_FILE" ]]; then
+  echo ""
+  echo "未找到 $PROFILE_FILE — 该仓似乎尚未接入 Harness。"
+  if prompt_yes_no "是否改为首次安装（install.sh）？" "y"; then
+    PRESET="harness-only"
+    if [[ -z "$IDE_LIST" ]]; then
+      print_preset_menu
+      read -r -p "preset [1]: " PRESET_INPUT
+      PRESET="$(resolve_preset_choice "$PRESET_INPUT" "$SCRIPT_DIR/profiles")"
+      print_ide_menu
+      read -r -p "IDE [1]: " IDE_INPUT
+      IDE_LIST="$(resolve_ide_choice "${IDE_INPUT:-1}")"
+    fi
+    INSTALL_ARGS=(--target "$TARGET" --preset "$PRESET")
+    [[ -n "$IDE_LIST" ]] && INSTALL_ARGS+=(--ide "$IDE_LIST")
+    echo ""
+    echo ">>> install.sh ${INSTALL_ARGS[*]}"
+    "$SCRIPT_DIR/install.sh" "${INSTALL_ARGS[@]}"
+    exit 0
+  fi
+  echo "已取消。请先: $SCRIPT_DIR/install.sh --target $TARGET --preset harness-only" >&2
+  exit 1
+fi
+
+echo "目标仓: $TARGET"
+echo "preset: $(profile_preset_name "$PROFILE_FILE")"
+echo "当前 IDE: $(profile_ide_summary "$PROFILE_FILE")"
+echo ""
+
+# 始终刷新 local.json，避免路径漂移（如 Desktop → Projects）
+printf '%s\n' "{\"cyning_harness_root\":\"$CYNING_HARNESS\"}" > "$TARGET/.cyning-harness/local.json"
+echo "已更新 local.json → cyning_harness_root=$CYNING_HARNESS"
+echo ""
+
+if [[ -z "$IDE_LIST" ]] && [[ "$ASSUME_YES" -eq 0 ]]; then
+  if prompt_yes_no "是否更新 IDE 勾选（cursor / claude / agents）？" "n"; then
+    read -r -p "IDE 列表 [$(profile_ide_summary "$PROFILE_FILE")]: " IDE_INPUT
+    [[ -n "$IDE_INPUT" ]] && IDE_LIST="$IDE_INPUT"
+  fi
+fi
+
+if [[ -n "$IDE_LIST" ]]; then
+  patch_profile_ide "$PROFILE_FILE" "$IDE_LIST"
+  echo "已更新 IDE 勾选: $IDE_LIST"
+  echo ""
+fi
+
+export CYNING_HARNESS TARGET
+[[ "$SYNC_FORCE" -eq 1 ]] && export HARNESS_SYNC_FORCE=1
+
+echo ">>> 预览同步计划（plan）"
+echo ""
+"$SCRIPT_DIR/harness-sync.sh" plan --target "$TARGET"
+echo ""
+
+DO_APPLY=0
+if [[ "$ASSUME_YES" -eq 1 ]]; then
+  DO_APPLY=1
+elif prompt_yes_no "确认执行同步（apply）？" "y"; then
+  DO_APPLY=1
+fi
+
+if [[ "$DO_APPLY" -eq 1 ]]; then
+  echo ""
+  echo ">>> 执行同步（apply）"
+  SYNC_ARGS=(apply --target "$TARGET")
+  [[ "$SYNC_FORCE" -eq 1 ]] && SYNC_ARGS+=(--force)
+  "$SCRIPT_DIR/harness-sync.sh" "${SYNC_ARGS[@]}"
+  write_manifest_upgrade "$TARGET" "$VERSION"
+  echo ""
+  echo "升级完成。"
+else
+  echo "已取消 apply（仅预览）。"
+  exit 0
+fi
+
+if [[ "$RUN_GATE" -eq 1 ]]; then
+  echo ""
+  echo ">>> gate-check"
+  "$SCRIPT_DIR/gate-check.sh" --target "$TARGET"
+elif [[ "$ASSUME_YES" -eq 0 ]] && prompt_yes_no "是否运行 gate-check（30 前人工闸）？" "n"; then
+  echo ""
+  echo ">>> gate-check"
+  "$SCRIPT_DIR/gate-check.sh" --target "$TARGET"
+fi
+
+echo ""
+echo "日后可运行: npx @cyning/harness upgrade --target $TARGET"
+echo "或维护者: $SCRIPT_DIR/upgrade.sh --target $TARGET"
+echo "清空重装: $SCRIPT_DIR/uninstall.sh --target $TARGET"