hunter-harness 0.1.2 → 0.2.0

package/resources/harness/bundles/java/codex/harness-knowledge-ingest/scripts/harness_knowledge_mcp.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""MCP entry point for Harness knowledge operations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import harness_knowledge as hk  # noqa: E402
+
+
+TOOL_DESCRIPTIONS: list[dict[str, Any]] = [
+    {
+        "name": "harness_knowledge_ingest",
+        "description": "Build or refresh a project-local .harness/knowledge index from .harness/archive.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/archive."},
+                "incremental": {"type": "boolean", "default": True, "description": "Reuse cached archive extraction results when valid."},
+            },
+            "required": ["project"],
+        },
+    },
+    {
+        "name": "harness_knowledge_sync",
+        "description": "Check whether .harness/knowledge is current, optionally refreshing stale indexes.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/archive."},
+                "update": {"type": "boolean", "default": False, "description": "Refresh the index when it is out of date."},
+                "incremental": {"type": "boolean", "default": True, "description": "Use incremental extraction when update is true."},
+            },
+            "required": ["project"],
+        },
+    },
+    {
+        "name": "harness_knowledge_auto",
+        "description": "Run the default automated knowledge maintenance workflow: create config when missing, sync, suggest validators, verify, and audit.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/archive."},
+                "limit": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100},
+                "suggest_statuses": {"type": "array", "items": {"type": "string"}, "default": []},
+                "apply_suggestions": {"type": "boolean", "default": False, "description": "Write validator suggestions into entry JSON files."},
+                "incremental": {"type": "boolean", "default": True, "description": "Reuse cached archive extraction results when refreshing."},
+                "audit_limit": {"type": "integer", "default": 10, "minimum": 1, "maximum": 100},
+            },
+            "required": ["project"],
+        },
+    },
+    {
+        "name": "harness_knowledge_audit",
+        "description": "Generate review lists for candidate, stale, superseded, and conflicted knowledge.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/knowledge."},
+                "limit": {"type": "integer", "default": 10, "minimum": 1, "maximum": 100},
+            },
+            "required": ["project"],
+        },
+    },
+    {
+        "name": "harness_knowledge_verify",
+        "description": "Run configured validators against knowledge entries and refresh verification reports.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/knowledge."},
+            },
+            "required": ["project"],
+        },
+    },
+    {
+        "name": "harness_knowledge_suggest_validators",
+        "description": "Suggest deterministic validators for knowledge entries, optionally applying them.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/knowledge."},
+                "limit": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100},
+                "statuses": {"type": "array", "items": {"type": "string"}, "default": []},
+                "apply": {"type": "boolean", "default": False, "description": "Write suggestions into entry JSON files."},
+            },
+            "required": ["project"],
+        },
+    },
+    {
+        "name": "harness_knowledge_query",
+        "description": "Search .harness/knowledge and generate a context pack for planning or implementation.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/knowledge."},
+                "query": {"type": "string", "description": "Need, question, keyword, or file path to search."},
+                "limit": {"type": "integer", "default": 10, "minimum": 1, "maximum": 100},
+                "files": {"type": "array", "items": {"type": "string"}, "default": []},
+                "statuses": {"type": "array", "items": {"type": "string"}, "default": []},
+                "types": {"type": "array", "items": {"type": "string"}, "default": []},
+            },
+            "required": ["project", "query"],
+        },
+    },
+    {
+        "name": "harness_knowledge_promote",
+        "description": "Promote a candidate knowledge entry to active after manual confirmation.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/knowledge."},
+                "entry_id": {"type": "string", "description": "Knowledge entry id to promote."},
+                "note": {"type": "string", "default": "", "description": "Manual verification note."},
+                "allow_stale": {"type": "boolean", "default": False, "description": "Allow promoting a stale entry after manual verification."},
+            },
+            "required": ["project", "entry_id"],
+        },
+    },
+    {
+        "name": "harness_knowledge_demote",
+        "description": "Demote an active knowledge entry to stale or candidate after manual review.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string", "description": "Project root containing .harness/knowledge."},
+                "entry_id": {"type": "string", "description": "Active knowledge entry id to demote."},
+                "status": {"type": "string", "enum": ["candidate", "stale"], "description": "Target lifecycle status."},
+                "reason": {"type": "string", "description": "Manual demotion reason."},
+            },
+            "required": ["project", "entry_id", "status", "reason"],
+        },
+    },
+]
+
+
+def describe_tools() -> dict[str, Any]:
+    return {
+        "server": "harness-knowledge",
+        "transport": "stdio",
+        "tools": TOOL_DESCRIPTIONS,
+    }
+
+
+def create_server() -> Any:
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except Exception as exc:  # pragma: no cover - exercised when SDK is absent
+        raise RuntimeError(
+            "Python package 'mcp' with FastMCP support is required to run the MCP server. "
+            "Use --describe-tools for static tool metadata."
+        ) from exc
+
+    server = FastMCP(
+        "harness-knowledge",
+        instructions=(
+            "Use these tools to maintain and query project-local Harness knowledge. "
+            "Treat candidate and stale entries as historical context until verified."
+        ),
+    )
+
+    @server.tool(description=TOOL_DESCRIPTIONS[0]["description"])
+    def harness_knowledge_ingest(project: str, incremental: bool = True) -> dict[str, Any]:
+        return hk.summarize_index(hk.build_index(Path(project), incremental=incremental))
+
+    @server.tool(description=TOOL_DESCRIPTIONS[1]["description"])
+    def harness_knowledge_sync(project: str, update: bool = False, incremental: bool = True) -> dict[str, Any]:
+        return hk.sync_status(Path(project), update=update, incremental=incremental)
+
+    @server.tool(description=TOOL_DESCRIPTIONS[2]["description"])
+    def harness_knowledge_auto(
+        project: str,
+        limit: int = 20,
+        suggest_statuses: list[str] | None = None,
+        apply_suggestions: bool = False,
+        incremental: bool = True,
+        audit_limit: int = 10,
+    ) -> dict[str, Any]:
+        return hk.auto_knowledge(
+            Path(project),
+            limit=limit,
+            suggest_statuses=suggest_statuses or [],
+            apply_suggestions=apply_suggestions,
+            incremental=incremental,
+            audit_limit=audit_limit,
+        )
+
+    @server.tool(description=TOOL_DESCRIPTIONS[3]["description"])
+    def harness_knowledge_audit(project: str, limit: int = 10) -> dict[str, Any]:
+        return hk.audit_entries(Path(project), limit=limit)
+
+    @server.tool(description=TOOL_DESCRIPTIONS[4]["description"])
+    def harness_knowledge_verify(project: str) -> dict[str, Any]:
+        return hk.verify_knowledge(Path(project))
+
+    @server.tool(description=TOOL_DESCRIPTIONS[5]["description"])
+    def harness_knowledge_suggest_validators(
+        project: str,
+        limit: int = 20,
+        statuses: list[str] | None = None,
+        apply: bool = False,
+    ) -> dict[str, Any]:
+        return hk.suggest_validators(Path(project), limit=limit, statuses=statuses or [], apply=apply)
+
+    @server.tool(description=TOOL_DESCRIPTIONS[6]["description"])
+    def harness_knowledge_query(
+        project: str,
+        query: str,
+        limit: int = 10,
+        files: list[str] | None = None,
+        statuses: list[str] | None = None,
+        types: list[str] | None = None,
+    ) -> dict[str, Any]:
+        return hk.query_index(
+            Path(project),
+            query,
+            limit=limit,
+            file_filters=files or [],
+            statuses=statuses or [],
+            types=types or [],
+        )
+
+    @server.tool(description=TOOL_DESCRIPTIONS[7]["description"])
+    def harness_knowledge_promote(
+        project: str,
+        entry_id: str,
+        note: str = "",
+        allow_stale: bool = False,
+    ) -> dict[str, Any]:
+        return hk.promote_entry(Path(project), entry_id, note, allow_stale=allow_stale)
+
+    @server.tool(description=TOOL_DESCRIPTIONS[8]["description"])
+    def harness_knowledge_demote(
+        project: str,
+        entry_id: str,
+        status: str,
+        reason: str,
+    ) -> dict[str, Any]:
+        return hk.demote_entry(Path(project), entry_id, status, reason)
+
+    return server
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run the Harness knowledge MCP server.")
+    parser.add_argument("--describe-tools", action="store_true", help="Print static MCP tool metadata as JSON and exit.")
+    parser.add_argument("--transport", choices=["stdio", "sse", "streamable-http"], default="stdio")
+    args = parser.parse_args(argv)
+
+    if args.describe_tools:
+        print(json.dumps(describe_tools(), ensure_ascii=False, indent=2))
+        return 0
+
+    try:
+        server = create_server()
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    server.run(transport=args.transport)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/resources/harness/bundles/java/codex/harness-knowledge-query/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: harness-knowledge-query
+description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
+  历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
+---
+<!-- generated by harness_deploy.py; core=9a7af3c66acaad35; overlay=java; agent=codex; do not edit -->
+# harness-knowledge-query
+
+根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。
+
+此 skill 只负责查询和使用知识。整理、同步和 promote 条目由 `harness-knowledge-ingest` 负责。
+
+## Triggers
+
+- query knowledge
+- knowledge query
+- 查找相关历史需求
+- 根据历史归档理解这个需求
+- 结合之前做过的内容
+- 继续之前类似开发
+- 生成需求上下文包
+- 在规划前查历史
+
+## Automatic Use
+
+当用户提出新功能、改造、排查、设计方案、继续历史任务，且项目存在 `.harness/archive` 或 `.harness/knowledge` 时，AI 应主动运行本 skill，不需要等用户提醒。
+
+如果 `.harness/knowledge/index.json` 不存在或已过期，先运行：
+
+```powershell
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>' --update"
+```
+
+然后再查询。
+
+## Commands
+
+`<ingest-skill-dir>` 指同级 `harness-knowledge-ingest/` 目录；查询逻辑复用其脚本。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行，避开 Bash 在 Windows 中文路径下的编码/参数问题。
+
+### Query by requirement
+
+```powershell
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' query --project '<project-root>' --query '<用户需求原文>'"
+```
+
+### Query with metadata filters
+
+```powershell
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' query --project '<project-root>' --query '<需求或关键词>' --file '<source-file>' --status active"
+```
+
+可重复使用：
+
+- `--file <path>`：只返回关联到指定文件的知识。
+- `--status active|candidate|stale|superseded|conflicted`：按生命周期过滤。
+- `--type requirement|decision|implementation|risk|test-evidence|pitfall|api-contract`：按知识类型过滤。
+- `--limit <n>`：限制返回数量。
+
+## Workflow
+
+1. 确认项目根目录。
+2. 运行 `sync --project <root>`。
+3. 如果 `upToDate=false`，运行 `sync --update`。
+4. 用用户原始需求作为 `--query` 查询。
+5. 如已知道相关文件，追加 `--file` 过滤。
+6. 读取 JSON 输出中的 `contextPack`。
+7. 在 `harness-plan`、设计、代码探索或实现前，把 context pack 当作必读输入。
+
+## Output Contract
+
+查询输出 JSON 包含：
+
+- `matchCount`
+- `contextPack`
+- `filters`
+- `planInput`
+- `matches`
+
+`planInput.kind` 必须为 `harness-knowledge-context-pack`。后续 `harness-plan` 应读取 `planInput.path`。
+
+每次查询还会更新稳定指针：
+
+```text
+.harness/knowledge/context-packs/latest.json
+```
+
+该文件包含最新 query、context pack 路径和 `matchIds`，供后续流程快速读取最近一次知识上下文。
+
+## Interpretation Rules
+
+- `active`：可优先采用，但仍要结合当前代码验证。
+- `candidate`：有参考价值，不是当前事实。
+- `stale`：只能作为历史线索，必须重新检查代码和归档。
+- `superseded` / `conflicted`：必须显式提示风险，不得静默采用。
+
+## Forbidden Actions
+
+- rebuild_index_without_need
+- treat_candidate_as_current_fact
+- treat_stale_as_current_fact
+- skip_context_pack_before_planning
+- copy_large_archive_content_into_prompt
+
+## Verification
+
+```powershell
+powershell.exe -Command "python -m unittest '<ingest-skill-dir>\tests\test_harness_knowledge.py'"
+powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' query --project '<real-project-root>' --query '<真实需求>'"
+```
+
+确认输出中存在 `contextPack`、`planInput.kind=harness-knowledge-context-pack`，且 context pack 文件包含 `Before planning`。
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
+- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
+- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+
+## Output Format
+
+执行完成后展示：
+
+- 用户需求原文与生效的过滤条件（`--file`/`--status`/`--type`/`--limit`）。
+- `matchCount` 与按状态分组的命中数（active/candidate/stale/superseded/conflicted）。
+- `contextPack` 路径与 `latest.json` 指针。
+- 命中 stale/superseded/conflicted 时显式提示风险。
+- 下一步建议（context pack 已就绪 → 进入 `/harness-plan`；索引过期 → 先 `sync --update`）。
+
+## 渐进披露
+
+- 本 skill 暂无 `checklist.md` / `reference.md` 支持文件，规则全部在 SKILL.md。若 Output Contract / Interpretation Rules 后续扩展变重，应拆到 `reference.md`。
+
+## 交互白名单
+
+**无** AskUserQuestion；`stale`/`conflicted` 命中记 `issue`，不阻断 query。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+```powershell
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。

package/resources/harness/bundles/java/codex/harness-package/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: harness-package
+description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。使用场景：打包、package、发版准备
+---
+<!-- generated by harness_deploy.py; core=9a7af3c66acaad35; overlay=java; agent=codex; do not edit -->
+# harness-package — 增量模块打包（Java overlay）
+
+## Purpose
+
+基于 final pushed commit 识别变更模块 → 增量 `mvn package` → 汇总 jar/war 路径与大小。
+
+> 默认时序：`submit → package → archive`。test 已通过且 ledger 有效时可 `-DskipTests`。
+
+## When to Use
+
+- submit 已推送，准备发版打包
+- 触发语："打包""package""发版准备"
+
+## 前置条件
+
+- 推荐已完成 `/harness-submit`；`baseCommit` 以 submit 最终 hash 为准
+- test 报告存在或 ledger 可复用；读 `meta/worktree.json` 决定 worktree 目录
+
+## 统一读取协议
+
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **spec** — 设计真相源：`spec/<change>-design.md`
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+
+## Workflow
+
+1. 读 ledger + build-profile 的 `buildCommands.package`
+2. 识别变更模块（git diff + pom 结构）
+3. `mvn package -DskipTests`（ledger 不可复用时先跑必要测试）
+4. 写打包报告 + append 事件
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
+- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
+- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+
+## 渐进披露
+
+- **Read `reference.md`** — 模块识别与报告格式
+- **Read `checklist.md`** — 逐步勾选
+
+## 交互白名单
+
+**无** AskUserQuestion；冲突/失败记 `issue`/`decision`。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+```powershell
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。