@pieerry/harness-kit 3.0.0

package/.claude/plugins/product-manager/scripts/confluence-publish.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+Publish a PRD or PRP to Confluence.
+
+Reads credentials from environment:
+ - JIRA_USERNAME (email)
+ - JIRA_API_TOKEN (API token)
+
+Targets the Confluence at https://YOUR-DOMAIN.atlassian.net.
+
+Usage:
+ confluence-publish.py --artifact PATH.md --kind {prd|prp}
+
+Exit 0 on success, 1 on failure. Stays silent on routine output, prints
+errors to stderr.
+"""
+
+import argparse
+import base64
+import html
+import json
+import os
+import re
+import sys
+import urllib.request
+from pathlib import Path
+
+CONFLUENCE_BASE = "https://YOUR-DOMAIN.atlassian.net/wiki/rest/api/content"
+SPACE_KEY = "TET1"
+
+# Parent page IDs per kind. Override via env if needed.
+PARENT_IDS = {
+ "prd": os.environ.get("CONFLUENCE_PARENT_PRD", "11351457795"),
+ "prp": os.environ.get("CONFLUENCE_PARENT_PRP", "11351457795"),
+}
+
+
+def md_to_storage(md: str) -> str:
+ """Minimal Markdown to Confluence storage XHTML.
+ Good enough for headings, paragraphs, fenced code, lists, tables.
+ For richer rendering, swap for a real converter later.
+ """
+ lines = md.splitlines()
+ out: list[str] = []
+ in_code = False
+ in_list: str | None = None # 'ul' or 'ol'
+ in_table = False
+
+ def close_list():
+ nonlocal in_list
+ if in_list:
+ out.append(f"</{in_list}>")
+ in_list = None
+
+ def close_table():
+ nonlocal in_table
+ if in_table:
+ out.append("</tbody></table>")
+ in_table = False
+
+ for line in lines:
+ if line.startswith("```"):
+ close_list()
+ close_table()
+ if not in_code:
+ lang = line[3:].strip() or "none"
+ out.append(
+ f'<ac:structured-macro ac:name="code">'
+ f'<ac:parameter ac:name="language">{html.escape(lang)}</ac:parameter>'
+ f'<ac:plain-text-body><![CDATA['
+ )
+ in_code = True
+ else:
+ out.append("]]></ac:plain-text-body></ac:structured-macro>")
+ in_code = False
+ continue
+
+ if in_code:
+ out.append(line)
+ continue
+
+ h = re.match(r"^(#{1,6})\s+(.+)$", line)
+ if h:
+ close_list()
+ close_table()
+ level = len(h.group(1))
+ out.append(f"<h{level}>{html.escape(h.group(2))}</h{level}>")
+ continue
+
+ if re.match(r"^[-*]\s+", line):
+ close_table()
+ if in_list != "ul":
+ close_list()
+ out.append("<ul>")
+ in_list = "ul"
+ item = re.sub(r"^[-*]\s+", "", line)
+ out.append(f"<li>{html.escape(item)}</li>")
+ continue
+
+ if re.match(r"^\d+\.\s+", line):
+ close_table()
+ if in_list != "ol":
+ close_list()
+ out.append("<ol>")
+ in_list = "ol"
+ item = re.sub(r"^\d+\.\s+", "", line)
+ out.append(f"<li>{html.escape(item)}</li>")
+ continue
+
+ if line.startswith("|") and "|" in line[1:]:
+ close_list()
+ cells = [c.strip() for c in line.strip("|").split("|")]
+ if not in_table:
+ out.append("<table><tbody>")
+ in_table = True
+ out.append(
+ "<tr>"
+ + "".join(f"<th>{html.escape(c)}</th>" for c in cells)
+ + "</tr>"
+ )
+ elif all(re.fullmatch(r":?-+:?", c) for c in cells):
+ # separator row, skip
+ pass
+ else:
+ out.append(
+ "<tr>"
+ + "".join(f"<td>{html.escape(c)}</td>" for c in cells)
+ + "</tr>"
+ )
+ continue
+
+ # paragraph or blank
+ close_list()
+ close_table()
+ if line.strip():
+ out.append(f"<p>{html.escape(line)}</p>")
+
+ close_list()
+ close_table()
+ return "\n".join(out)
+
+
+def extract_title(md: str) -> str:
+ for line in md.splitlines():
+ m = re.match(r"^#\s+(.+)$", line)
+ if m:
+ return m.group(1).strip()
+ return "Untitled"
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--artifact", required=True, type=Path)
+ parser.add_argument("--kind", required=True, choices=["prd", "prp"])
+ args = parser.parse_args()
+
+ username = os.environ.get("JIRA_USERNAME")
+ token = os.environ.get("JIRA_API_TOKEN")
+ if not username or not token:
+ print("[confluence-publish] JIRA_USERNAME/JIRA_API_TOKEN not set", file=sys.stderr)
+ return 1
+
+ md = args.artifact.read_text(encoding="utf-8")
+ title = extract_title(md)
+ storage = md_to_storage(md)
+
+ payload = {
+ "type": "page",
+ "title": title,
+ "ancestors": [{"id": PARENT_IDS[args.kind]}],
+ "space": {"key": SPACE_KEY},
+ "body": {"storage": {"value": storage, "representation": "storage"}},
+ }
+
+ auth = base64.b64encode(f"{username}:{token}".encode()).decode()
+ req = urllib.request.Request(
+ CONFLUENCE_BASE,
+ data=json.dumps(payload).encode("utf-8"),
+ method="POST",
+ headers={
+ "Authorization": f"Basic {auth}",
+ "Content-Type": "application/json",
+ "Accept": "application/json",
+ },
+ )
+
+ try:
+ with urllib.request.urlopen(req, timeout=20) as resp:
+ data = json.loads(resp.read().decode("utf-8"))
+ page_url = data.get("_links", {}).get("base", "") + data.get(
+ "_links", {}
+ ).get("webui", "")
+ print(f"[confluence-publish] published: {page_url}", file=sys.stderr)
+ return 0
+ except urllib.error.HTTPError as e:
+ body = e.read().decode("utf-8", errors="replace")
+ print(f"[confluence-publish] HTTP {e.code}: {body[:500]}", file=sys.stderr)
+ return 1
+ except Exception as e:
+ print(f"[confluence-publish] error: {e}", file=sys.stderr)
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())

package/.claude/plugins/product-manager/scripts/link-validator.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""
+PRP link validator. Verifies that:
+- Source PRD link points to an existing file
+- Inline code paths (looking like file paths) end in a known extension
+- HTTP URLs are syntactically valid
+- No localhost URLs are pinned as references
+
+Usage:
+  link-validator.py --artifact PRP.md --repo-root /path/to/repo
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+KNOWN_EXTS = {
+    "java", "kt", "ts", "tsx", "js", "jsx", "vue",
+    "py", "sql", "yaml", "yml", "md", "sh", "gradle",
+    "xml", "json", "properties",
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--artifact", required=True, type=Path)
+    parser.add_argument("--repo-root", required=True, type=Path)
+    args = parser.parse_args()
+
+    if not args.artifact.exists():
+        print(f"[link-validator] artifact not found: {args.artifact}", file=sys.stderr)
+        return 1
+
+    text = args.artifact.read_text(encoding="utf-8")
+    failures: list[str] = []
+
+    # 1) Source PRD must exist
+    m = re.search(r"\*\*Source PRD:\*\*\s+`?([^\s`]+)`?", text)
+    if m:
+        prd_rel = m.group(1).strip()
+        candidates = [
+            args.repo_root / prd_rel,
+            args.artifact.parent / prd_rel,
+            args.repo_root / ".claude/plugins/product-manager" / prd_rel,
+        ]
+        if not any(c.exists() for c in candidates):
+            failures.append(f"Source PRD path does not resolve: {prd_rel}")
+    else:
+        failures.append("missing **Source PRD:** field")
+
+    # 2) Inline code-spans that look like paths must have known extensions
+    for span in re.finditer(r"`([^`\s]+/[^`\s]+)`", text):
+        path = span.group(1)
+        # strip :line suffix if present
+        path_clean = re.sub(r":\d+$", "", path)
+        ext = path_clean.rsplit(".", 1)[-1] if "." in path_clean else ""
+        if not ext or ext.lower() not in KNOWN_EXTS:
+            # Allow URLs and confluence-ish paths
+            if path.startswith("http") or "/wiki/" in path:
+                continue
+            failures.append(f"path-like span has unknown/missing extension: `{path}`")
+
+    # 3) Localhost URLs not allowed
+    if re.search(r"https?://(localhost|127\.0\.0\.1)", text):
+        failures.append("localhost URL pinned in PRP; replace with stable reference")
+
+    # 4) GitHub blob/tree on moving branches → warn (treat as failure for handoff)
+    for m in re.finditer(
+        r"github\.com/[\w-]+/[\w.-]+/(blob|tree)/(main|master|develop)/", text
+    ):
+        failures.append(
+            f"GitHub link uses moving branch ({m.group(2)}); use a commit SHA or tag"
+        )
+
+    if failures:
+        print(f"[link-validator] {args.artifact.name} FAILED ({len(failures)} issue(s)):", file=sys.stderr)
+        for f in failures:
+            print(f"  - {f}", file=sys.stderr)
+        return 1
+
+    print(f"[link-validator] {args.artifact.name} passed", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/plugins/product-manager/scripts/sensor-runner.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Deterministic sensor runner.
+
+Parses a markdown sensor file (looking for known sections like
+"Required sections", "Forbidden tokens", "Markdown rules") and applies the
+checks against an artifact file. Returns exit code 0 if all checks pass, 1 if
+any blocking check fails.
+
+Usage:
+  sensor-runner.py --sensor SENSOR.md --artifact ARTIFACT.md
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+def section_body(text: str, heading: str) -> str | None:
+    """Return the body of a `## heading` section, or None if not found."""
+    pattern = rf"^##+\s+{re.escape(heading)}\s*$"
+    lines = text.splitlines()
+    start = None
+    for i, line in enumerate(lines):
+        if re.match(pattern, line, re.IGNORECASE):
+            start = i + 1
+            break
+    if start is None:
+        return None
+    end = len(lines)
+    for i in range(start, len(lines)):
+        if re.match(r"^##+\s+\S", lines[i]):
+            end = i
+            break
+    return "\n".join(lines[start:end])
+
+
+def bullets(body: str) -> list[str]:
+    return [
+        m.group(1).strip()
+        for m in re.finditer(r"^[-*]\s+(.+)$", body or "", re.MULTILINE)
+    ]
+
+
+def check_required_sections(sensor_md: str, artifact_text: str) -> list[str]:
+    body = section_body(sensor_md, "Required sections") or section_body(
+        sensor_md, "Required sections (all must be present)"
+    ) or section_body(sensor_md, "Required sections (all must be present, in order)")
+    if not body:
+        return []
+    sections = bullets(body)
+    failures = []
+    for section in sections:
+        clean = section.split("(", 1)[0].strip()
+        pattern = rf"^##+\s+(\d+\)\s*)?{re.escape(clean)}\b"
+        if not re.search(pattern, artifact_text, re.MULTILINE | re.IGNORECASE):
+            failures.append(f"missing required section: '{clean}'")
+    return failures
+
+
+def check_forbidden_sections(sensor_md: str, artifact_text: str) -> list[str]:
+    body = section_body(sensor_md, "Forbidden sections")
+    if not body:
+        return []
+    failures = []
+    for section in bullets(body):
+        clean = section.split("(", 1)[0].strip()
+        pattern = rf"^##+\s+(\d+\)\s*)?{re.escape(clean)}\b"
+        if re.search(pattern, artifact_text, re.MULTILINE | re.IGNORECASE):
+            failures.append(f"forbidden section present: '{clean}'")
+    return failures
+
+
+def check_forbidden_tokens(sensor_md: str, artifact_text: str) -> list[str]:
+    body = section_body(sensor_md, "Forbidden tokens") or section_body(
+        sensor_md, "Forbidden patterns"
+    )
+    if not body:
+        return []
+    failures = []
+    for token in bullets(body):
+        clean = token.strip("`")
+        if re.search(rf"\b{re.escape(clean)}\b", artifact_text, re.IGNORECASE):
+            failures.append(f"forbidden token present: '{clean}'")
+    return failures
+
+
+def check_markdown_rules(sensor_md: str, artifact_text: str) -> list[str]:
+    body = section_body(sensor_md, "Markdown rules")
+    if not body:
+        return []
+    failures = []
+    if "exactly 1 H1" in body or "require_h1: true" in body or "1 H1 heading" in body:
+        h1_count = len(re.findall(r"^#\s+\S", artifact_text, re.MULTILINE))
+        if h1_count != 1:
+            failures.append(f"expected exactly 1 H1, found {h1_count}")
+    if "no em-dash" in body.lower() or "no em dash" in body.lower():
+        if "—" in artifact_text:
+            failures.append("em-dash (—) found; use commas/periods/parentheses instead")
+    if "no ascii" in body.lower():
+        if re.search(r"^\s*\+[-+]{2,}\+\s*$", artifact_text, re.MULTILINE):
+            failures.append("ASCII box-drawing detected; use Mermaid diagrams")
+    return failures
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--sensor", required=True, type=Path)
+    parser.add_argument("--artifact", required=True, type=Path)
+    args = parser.parse_args()
+
+    if not args.sensor.exists():
+        print(f"[sensor-runner] sensor file not found: {args.sensor}", file=sys.stderr)
+        return 1
+    if not args.artifact.exists():
+        print(f"[sensor-runner] artifact file not found: {args.artifact}", file=sys.stderr)
+        return 1
+
+    sensor_md = args.sensor.read_text(encoding="utf-8")
+    artifact_text = args.artifact.read_text(encoding="utf-8")
+
+    failures: list[str] = []
+    failures += check_required_sections(sensor_md, artifact_text)
+    failures += check_forbidden_sections(sensor_md, artifact_text)
+    failures += check_forbidden_tokens(sensor_md, artifact_text)
+    failures += check_markdown_rules(sensor_md, artifact_text)
+
+    if failures:
+        print(f"[sensor-runner] {args.sensor.name} FAILED ({len(failures)} issue(s)):", file=sys.stderr)
+        for f in failures:
+            print(f"  - {f}", file=sys.stderr)
+        return 1
+
+    print(f"[sensor-runner] {args.sensor.name} passed", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/plugins/product-manager/scripts/token-phase.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+Token-phase accounting for the product-manager plugin.
+
+Reads start and end markers, sums Claude session token usage from the
+transcript JSONL within the time window, and appends a phase entry to
+outputs/tokens/{feature_id}.json.
+
+Usage:
+  token-phase.py --feature-id ID --phase NAME --plugin-dir PATH
+                 [--prd-path PATH] [--prp-path PATH]
+                 [--attempts N] [--details JSON]
+
+Exit 0 on success or graceful skip. Non-zero only on programming bug.
+Never blocks the calling hook.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def find_transcript(session_id: str | None) -> Path | None:
+    """Locate the Claude Code transcript JSONL for the current session."""
+    cwd = Path.cwd().resolve()
+    encoded = str(cwd).replace("/", "-")
+    project_dir = Path.home() / ".claude" / "projects" / encoded
+    if not project_dir.exists():
+        return None
+    if session_id:
+        candidate = project_dir / f"{session_id}.jsonl"
+        if candidate.exists():
+            return candidate
+    jsonls = sorted(
+        project_dir.glob("*.jsonl"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    return jsonls[0] if jsonls else None
+
+
+def read_marker(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as e:
+        print(f"[token-phase] failed to read marker {path.name}: {e}", file=sys.stderr)
+        return None
+
+
+def sum_tokens(transcript: Path, started_at: str, ended_at: str) -> dict:
+    """Sum usage tokens for assistant messages between start and end timestamps."""
+    totals = {"input": 0, "output": 0, "cache_read": 0, "cache_creation": 0}
+    try:
+        with open(transcript, "r", encoding="utf-8") as f:
+            for line in f:
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                ts = entry.get("timestamp") or entry.get("ts")
+                if not ts:
+                    continue
+                if ts < started_at or ts > ended_at:
+                    continue
+                msg = entry.get("message") or {}
+                usage = msg.get("usage") or entry.get("usage")
+                if not usage:
+                    continue
+                totals["input"] += usage.get("input_tokens", 0)
+                totals["output"] += usage.get("output_tokens", 0)
+                totals["cache_read"] += usage.get("cache_read_input_tokens", 0)
+                totals["cache_creation"] += usage.get(
+                    "cache_creation_input_tokens", 0
+                )
+    except Exception as e:
+        print(f"[token-phase] failed to read transcript: {e}", file=sys.stderr)
+    return totals
+
+
+def update_tokens_json(
+    tokens_path: Path, feature_id: str, files: dict, phase_entry: dict
+):
+    if tokens_path.exists():
+        try:
+            data = json.loads(tokens_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            data = None
+    else:
+        data = None
+
+    if data is None:
+        data = {
+            "feature_id": feature_id,
+            "files": {},
+            "phases": [],
+            "totals": {
+                "input": 0,
+                "output": 0,
+                "cache_read": 0,
+                "cache_creation": 0,
+            },
+        }
+
+    data["files"].update({k: v for k, v in files.items() if v})
+
+    duplicate = [
+        p
+        for p in data["phases"]
+        if p.get("phase") == phase_entry["phase"]
+        and p.get("started_at") == phase_entry["started_at"]
+    ]
+    if not duplicate:
+        data["phases"].append(phase_entry)
+
+    totals = {"input": 0, "output": 0, "cache_read": 0, "cache_creation": 0}
+    for p in data["phases"]:
+        for k in totals:
+            totals[k] += p.get("tokens", {}).get(k, 0)
+    data["totals"] = totals
+
+    tokens_path.parent.mkdir(parents=True, exist_ok=True)
+    tokens_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--feature-id", required=True)
+    parser.add_argument("--phase", required=True)
+    parser.add_argument("--plugin-dir", required=True, type=Path)
+    parser.add_argument("--prd-path", default="")
+    parser.add_argument("--prp-path", default="")
+    parser.add_argument("--attempts", type=int, default=1)
+    parser.add_argument("--details", default="{}")
+    args = parser.parse_args()
+
+    markers_dir = args.plugin_dir / "outputs" / ".markers"
+    start_marker = markers_dir / f"{args.feature_id}.{args.phase}.start"
+    end_marker = markers_dir / f"{args.feature_id}.{args.phase}.end"
+
+    start_data = read_marker(start_marker)
+    end_data = read_marker(end_marker)
+    if not start_data or not end_data:
+        print(
+            f"[token-phase] missing markers for phase {args.phase} (feature {args.feature_id})",
+            file=sys.stderr,
+        )
+        return 0
+
+    started_at = start_data.get("timestamp")
+    ended_at = end_data.get("timestamp")
+    if not started_at or not ended_at:
+        print("[token-phase] marker missing timestamp field", file=sys.stderr)
+        return 0
+
+    session_id = start_data.get("session_id") or os.environ.get("CLAUDE_SESSION_ID")
+
+    transcript = find_transcript(session_id)
+    if not transcript:
+        print("[token-phase] transcript not found, skipping", file=sys.stderr)
+        return 0
+
+    tokens = sum_tokens(transcript, started_at, ended_at)
+
+    try:
+        details = json.loads(args.details) if args.details else {}
+    except json.JSONDecodeError:
+        details = {}
+
+    phase_entry = {
+        "phase": args.phase,
+        "started_at": started_at,
+        "ended_at": ended_at,
+        "tokens": tokens,
+        "attempts": args.attempts,
+    }
+    if details:
+        phase_entry["details"] = details
+
+    files = {}
+    if args.prd_path:
+        files["prd"] = args.prd_path
+    if args.prp_path:
+        files["prp"] = args.prp_path
+
+    tokens_path = (
+        args.plugin_dir / "outputs" / "tokens" / f"{args.feature_id}.json"
+    )
+    update_tokens_json(tokens_path, args.feature_id, files, phase_entry)
+
+    for m in (start_marker, end_marker):
+        try:
+            m.unlink()
+        except FileNotFoundError:
+            pass
+
+    print(
+        f"[token-phase] {args.phase}: in={tokens['input']} out={tokens['output']} cache_r={tokens['cache_read']}",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/plugins/product-manager/sensors/prd-acceptance-criteria.md

@@ -0,0 +1,39 @@
+# Sensor: PRD Acceptance Criteria
+
+Type: deterministic
+Mode: hard gate
+
+## Required sections
+
+- Solution Overview
+- Success Metrics
+- Rollout
+
+## Markdown rules
+
+- exactly 1 H1 heading
+- no em-dash
+
+## Checks
+
+User story format. Every bullet in Solution Overview that starts with "As a" must follow:
+
+```
+- As a {persona}, I want {action}, so that {benefit}.
+```
+
+Metric completeness. Success Metrics table: every row must have non-empty Baseline, Target, Horizon. Cells with only "TBD", "N/A", "?", or empty fail.
+
+Guardrails block. A "Guardrails" line must exist in Success Metrics.
+
+Kill criteria. A "Kill criteria:" line must exist in Success Metrics and contain at least one digit.
+
+Rollout phases. Rollout table needs at least 2 rows.
+
+Non-goals listed. Scope and Non-Goals must have a Non-goals subsection with 1-3 bullets.
+
+Open gaps budget. Count of `NOT FOUND` markers must be 5 or fewer.
+
+## On failure
+
+Block publish. Surface each violation with line number. Agent regenerates affected sections only.