npm - agent-harness-kit - Versions diffs - 0.8.0 → 0.10.0 - Mend

agent-harness-kit 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (62) hide show

package/src/templates/CLAUDE.md.vi.hbs CHANGED Viewed

@@ -47,6 +47,7 @@ luôn gọn.
 - `/structural-test-author <layer>`   khi thêm rule kiến trúc mới.
 - `/garbage-collection`               mỗi thứ Sáu hoặc trước khi tag release.
 - `/eval-runner`                      trước khi merge bất kỳ thay đổi nào ở skill / agent file.
+- `/deliver-html`                     khi user cần analysis / audit / plan / decision doc / next-actions — HTML cho human, MD giữ cho agent file (principle #11).
 ## Subagents nên ủy thác (KHÔNG inline review)

package/src/templates/docs/adr/0002-html-first-for-humans.md.hbs ADDED Viewed

@@ -0,0 +1,116 @@
+# ADR 0002 — HTML for human deliverables, Markdown for agent files
+- **Status:** accepted
+- **Date:** {{now "yyyy-MM-dd"}}
+- **Deciders:** project owner
+## Context
+The kit produces two distinct kinds of long-form output:
+1. **Files an agent reads-and-edits.** `CLAUDE.md`, `SKILL.md`,
+   `.claude/agents/*.md`, `docs/architecture.md`, ADR notes, structural
+   reports written to stdout. These are line-oriented, diffable, and
+   typically loaded into the LLM context window.
+2. **Documents a HUMAN reads-and-decides.** Audit reports, analyses, plans,
+   "next actions" reviews, status snapshots, decision docs. These are
+   self-contained artefacts that travel via email / Slack / PR attachments
+   and exist to surface a recommendation the human signs off on.
+Anthropic's long-running-agent guide and the `agent-harness-kit` golden
+principles both confirm Markdown is the right format for category 1: the
+LLM tokenizes it cheaply, structural editing tools (`Edit`, `Write`) treat
+it as native, and grep / sed / awk handle it without ceremony. Category 1
+should remain Markdown.
+Category 2 is where pain accumulates. A 500–800-line Markdown audit forces
+the reader to:
+- Scroll past sections that lack visual contrast.
+- Render the file (terminal pager, GitHub preview, VS Code preview) before
+  it is readable at all.
+- Skim and miss conclusions because every heading and bullet looks alike —
+  no severity badges, no border-left callouts, no grid layout.
+The observed failure mode in this kit's own past sessions: the human reads
+the Markdown report, asks the agent a follow-up that was answered in line
+347, and burns another turn. That clarification turn costs more in tokens
+(input replay + new output) than the +30-50% markup overhead of HTML.
+## Decision
+Adopt the rule documented as `docs/golden-principles.md` principle #11:
+- **Human-facing deliverables ship as a single self-contained HTML file**
+  at repo root, produced by the `/deliver-html` skill against the shared
+  CSS at `.claude/skills/deliver-html/assets/report.css`.
+- **Agent-facing files stay Markdown.** No exception.
+Implementation details:
+1. `/deliver-html` triggers on user intent: "analyze", "audit", "review",
+   "phân tích", "báo cáo", "plan", "proposal", "decision doc",
+   "next actions", and any similar prompt that calls for a long-form
+   deliverable.
+2. The agent writes the body in Markdown (cheap tokens, easy reasoning).
+   The side-car `scripts/wrap-html.mjs` converts MD → HTML with three
+   templates (`decision-doc` | `audit-report` | `status-report`) and
+   inlines the shared CSS. No npm dependency: the converter is a
+   self-rolled subset (headings, paragraphs, lists, fenced code, tables,
+   blockquotes, inline formatting, links).
+3. The Stop hook (`scripts/precompletion-checklist.sh`) emits a
+   non-blocking nudge when the user prompt matched a deliverable keyword
+   but the session produced only `.md` files at repo root.
+4. Locale: the `<html lang="…">` attribute is read from
+   `harness.config.json` `.claudeMd.humanLanguage`. CSS is locale-agnostic.
+## Consequences
+Positive
+- One canonical look for every audit, plan, and decision doc. Less drift
+  across reports.
+- Human reads once, decides once. Measured benefit: each saved
+  clarification turn ≈ 2-5k output tokens + cached input replay; offsets
+  HTML markup overhead easily.
+- Self-contained HTML — emailable, Slack-attachable, PR-comment-attachable
+  without a build step.
+- Existing 5 HTML reports at repo root (`NEXT_ACTIONS.html`,
+  `PHAN_TICH.html`, `E2E_REPORT.html`, `E2E_CI_REPORT.html`,
+  `HOOK_AUDIT.html`) validate the pattern in practice — `/deliver-html`
+  formalises it.
+Negative
+- HTML output is ~30-50% larger in token count than the equivalent MD body.
+  Mitigation: the LLM writes MD; only the deterministic side-car emits
+  HTML, so the LLM token budget is not affected.
+- HTML diffs are noisy in GitHub. Mitigation: deliverables are artefacts,
+  not source. Source-of-truth lives in the conversation / commit message;
+  the HTML file is a build output. CI can ignore `*.html` at repo root.
+- Two formats to teach. Mitigation: the rule is "agent reads → MD,
+  human reads → HTML"; reviewers learn it on first encounter.
+## Alternatives considered
+- **Always Markdown.** Rejected: the failure mode this ADR closes is
+  exactly the "scrolling, miss-the-conclusion" loop that Markdown
+  invites for long deliverables. README / CHANGELOG remain MD because
+  npm/GitHub renders them and the install snippet must be copy-paste-able.
+- **Generate PDF instead.** Rejected: solo-dev kit, no print pipeline,
+  PDFs are write-only on common review tools. HTML is editable in 90
+  seconds when a reviewer wants to amend.
+- **Render Markdown server-side (Docusaurus / mdBook / GitHub Pages).**
+  Rejected: requires CI + deploy step for every report. HTML at repo root
+  opens with one click — zero friction.
+- **Inline a renderer in the IDE.** Rejected: not portable when sending the
+  artefact to someone who is not running the kit.
+## Out of scope
+- Existing HTML reports at repo root keep their inline CSS for now.
+  Self-contained shipping artefacts trump DRY at solo scale. A future
+  cleanup may reference the shared CSS file by relative path — tracked in
+  `docs/tech-debt-tracker.md` if/when it becomes load-bearing.
+- Localizing the CSS itself. Style is locale-agnostic by design; only the
+  `lang` attribute and body copy differ between locales.

package/src/templates/docs/golden-principles.md.hbs CHANGED Viewed

@@ -119,6 +119,38 @@ domain. The agent reads the recommendation, invokes
 `architecture-reviewer` (or documents why review is unnecessary), and the
 loop guard (`stop_hook_active`) lets the next stop succeed.
+## 11. HTML for human deliverables, Markdown for agent files
+Files an agent reads-and-edits (`CLAUDE.md`, `.claude/skills/*/SKILL.md`,
+`.claude/agents/*.md`, `docs/architecture.md`, `docs/adr/*.md`, ADR notes,
+inline review output) stay as Markdown. Files a HUMAN reads-and-decides
+(audit reports, analyses, plans, decision docs, next-actions reviews,
+status snapshots) ship as self-contained HTML, written by the
+`/deliver-html` skill against the shared dark-theme CSS.
+Why: a 700-line Markdown deliverable forces the human to scroll, miss the
+conclusion, and ask the agent to clarify — a wasted turn that costs more
+tokens than the HTML overhead it was meant to avoid. HTML deliverables are
+"read once, decide once." Markdown has no visual hierarchy strong enough to
+support decision-grade reading at length.
+Enforced by:
+- `/deliver-html` skill triggers on user intent ("analyze", "audit",
+  "review", "phân tích", "báo cáo", "plan", "proposal", "decision doc",
+  "next actions") and writes `<slug>.html` at repo root.
+- Stop hook nudge: when the prompt matches those keywords and the session
+  produced only `.md` files at repo root, the agent is reminded to invoke
+  `/deliver-html`. Non-blocking.
+- ADR-0002 documents the trade-off (token cost +30-50% on the rendered
+  output, paid back by saving ≥1 clarification turn).
+Counter-rules — when Markdown is still correct:
+- `README.md`, `CHANGELOG.md` — npm/GitHub renders them; human installs/diffs.
+- Stdout from `/review-this-pr`, `/garbage-collection`, structural reports —
+  agent consumes the output.
+- Short summaries (< 30 lines) — answer inline, no file.
 ---
 _Add new principles via `/structural-test-author`, which forces you to

package/src/templates/scripts/precompletion-checklist.sh.hbs CHANGED Viewed

@@ -202,6 +202,49 @@ if [ -f harness.config.json ] && have_jp && command -v git >/dev/null 2>&1; then
   fi
 fi
+# Non-blocking nudge: HTML-for-humans (golden principle #11 / ADR-0002).
+# When the session produced one or more deliverable-shaped .md files at repo
+# root (i.e. not CLAUDE.md / AGENTS.md / README.md / CHANGELOG.md), suggest
+# `/deliver-html`. Pure heuristic — never blocks the stop. Skip with
+# `AHK_DISABLE_HTML_NUDGE=1`.
+if [ "${AHK_DISABLE_HTML_NUDGE:-0}" != "1" ] && command -v git >/dev/null 2>&1; then
+  KIT_MDS="CLAUDE.md|AGENTS.md|README.md|CHANGELOG.md|LICENSE.md|CONTRIBUTING.md|CODE_OF_CONDUCT.md|SECURITY.md"
+  NEW_MD=$(
+    {
+      git ls-files --others --exclude-standard 2>/dev/null
+      git diff --name-only 2>/dev/null
+      git diff --name-only --cached 2>/dev/null
+    } \
+    | sort -u \
+    | grep -E '^[^/]+\.md$' \
+    | grep -Ev "^(${KIT_MDS})$" \
+    || true
+  )
+  if [ -n "$NEW_MD" ]; then
+    NEW_HTML=$(
+      {
+        git ls-files --others --exclude-standard 2>/dev/null
+        git diff --name-only 2>/dev/null
+        git diff --name-only --cached 2>/dev/null
+      } \
+      | sort -u \
+      | grep -E '^[^/]+\.html$' \
+      || true
+    )
+    if [ -z "$NEW_HTML" ]; then
+      {
+        echo
+        echo "[nudge] Repo root has new .md file(s) that look like human deliverables:"
+        echo "$NEW_MD" | sed 's/^/  - /'
+        echo
+        echo "Golden principle #11: HTML for human deliverables, MD for agent files."
+        echo "If these are reports/audits/plans/decision-docs, ship them via /deliver-html"
+        echo "instead. Non-blocking — suppress with AHK_DISABLE_HTML_NUDGE=1."
+      } >&2
+    fi
+  fi
+fi
 if [ ! -s "$TMPDIR_HOOK/failed.list" ]; then
   exit 0
 fi

package/src/templates/scripts/pretooluse-edit-guard.sh.hbs ADDED Viewed

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# PreToolUse hook (matcher: Edit|Write|MultiEdit) — denies direct edits to
+# protected paths. Catches the failure mode where the agent decides to
+# "just fix" a baseline file or .claude/ template instead of going through
+# the proper /garbage-collection or scaffold-refresh paths.
+#
+# Protected paths (and why):
+#   1. .claude/                         — skills, agents, hooks, settings.
+#                                         Use /upgrade flow or edit the source
+#                                         template in src/templates/.
+#   2. node_modules/                    — package state, regenerated by install.
+#   3. .git/                            — repo internals, never hand-edited.
+#   4. .harness/structural-baseline.json — bypasses monotonic guard. Use the
+#                                          /garbage-collection skill.
+#   5. .harness/installed.json          — kit lockfile, derived from render.
+#                                         Hand edits cause spurious "drift"
+#                                         warnings on next upgrade.
+#
+# Escape hatches:
+#   - AHK_ALLOW_BYPASS=1 → log + allow (audit trail in .harness/bypass.log).
+#   - AHK_HOOK_MODE=warn → log only, never deny.
+set -eo pipefail
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then jq -r "$1"
+  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+  fi
+}
+if ! have_jp; then exit 0; fi
+# Resolve target file. Write/Edit ship .tool_input.file_path; MultiEdit ships
+# the same field at the top level. Both carry the absolute or repo-relative
+# path. We normalise via Node to strip any leading ./ and use forward slashes.
+FILE=$(echo "$INPUT" | jp '.tool_input.file_path // .tool_input.path // empty')
+[ -z "$FILE" ] && exit 0
+# Normalise to a path relative to CWD when possible; otherwise keep absolute.
+REL_FILE="$FILE"
+if [ -n "$PWD" ] && [[ "$FILE" == "$PWD"/* ]]; then
+  REL_FILE="${FILE#"$PWD"/}"
+fi
+REL_FILE="${REL_FILE#./}"
+REASON=""
+case "$REL_FILE" in
+  .claude/*|*/.claude/*)
+    REASON=".claude/ is owned by the kit's scaffold. To change a skill/agent/hook, edit src/templates/.claude/ in the kit source and re-run 'agent-harness-kit upgrade', or override at the user level (~/.claude/)."
+    ;;
+  node_modules/*|*/node_modules/*)
+    REASON="node_modules/ is regenerated by the package manager. Edit package.json or the upstream package; never hand-edit installed files."
+    ;;
+  .git/*|*/.git/*)
+    REASON=".git/ contains repo internals. Use git commands ('git config', 'git update-ref', etc.) — never hand-edit."
+    ;;
+  .harness/structural-baseline.json)
+    REASON="Direct edits to .harness/structural-baseline.json bypass the baseline-monotonic guard. Use the /garbage-collection skill or fix the underlying violation."
+    ;;
+  .harness/installed.json)
+    REASON=".harness/installed.json is the kit lockfile, regenerated by 'agent-harness-kit init/upgrade'. Hand edits cause spurious drift warnings."
+    ;;
+esac
+if [ -z "$REASON" ]; then
+  exit 0
+fi
+# Warn-only mode.
+if [ "${AHK_HOOK_MODE:-}" = "warn" ]; then
+  echo "[ahk] pretooluse-edit-guard (warn): would deny edit to $REL_FILE — $REASON" >&2
+  exit 0
+fi
+# Bypass with audit log.
+if [ "${AHK_ALLOW_BYPASS:-}" = "1" ]; then
+  mkdir -p .harness
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
+  ESCAPED=${REL_FILE//\"/\\\"}
+  printf '{"ts":"%s","sha":"%s","bypass":"AHK_ALLOW_BYPASS","file":"%s","rule":"pretooluse-edit-guard"}\n' \
+    "$TS" "$SHA" "$ESCAPED" >> .harness/bypass.log
+  exit 0
+fi
+# Deny via JSON.
+if command -v node >/dev/null 2>&1; then
+  node -e "
+    const reason = process.argv[1];
+    const out = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason
+      }
+    };
+    process.stdout.write(JSON.stringify(out));
+  " "$REASON"
+elif have_jq; then
+  jq -nc --arg r "$REASON" \
+    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $r}}'
+else
+  echo "$REASON" >&2
+  exit 2
+fi
+exit 0

package/src/templates/scripts/session-end.sh.hbs CHANGED Viewed

@@ -45,4 +45,10 @@ fi
 mkdir -p .harness
 TS=$(date +"%Y-%m-%d %H:%M")
 echo "$TS | session_end | $REASON | $BR | $SHA" >> .harness/PROGRESS.md
+# Rollup side-car — writes a JSONL record to .harness/telemetry.jsonl.
+# Best-effort: never blocks the cleanup-only SessionEnd contract.
+if command -v node >/dev/null 2>&1 && [ -f scripts/session-rollup.mjs ]; then
+  printf '%s' "$INPUT" | node scripts/session-rollup.mjs 2>/dev/null || true
+fi
 exit 0

package/src/templates/scripts/session-rollup.mjs ADDED Viewed

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// session-rollup.mjs — deterministic SessionEnd side-car. Writes a single
+// JSONL record summarising the session into .harness/telemetry.jsonl. Pure
+// Node (no jq dependency).
+//
+// Record shape:
+//   { ts, event: "session_rollup", reason, branch, sha, uncommitted,
+//     skills_invoked: [...], session_id }
+//
+// Called from session-end.sh after the human-readable PROGRESS.md line is
+// written, so a single session contributes one PROGRESS.md line + one
+// telemetry rollup record.
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+function readStdinSync() {
+  // SessionEnd hooks pass JSON on stdin. fd 0 is the inherited stdin.
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+function safeJSON(s) {
+  if (!s) return {};
+  try { return JSON.parse(s); } catch { return {}; }
+}
+function git(args, def = "") {
+  const r = spawnSync("git", args, { cwd: ROOT, encoding: "utf8" });
+  if (r.status !== 0) return def;
+  return (r.stdout || "").trim();
+}
+function recentSkillInvocations() {
+  // Tail of telemetry.jsonl: count skill_invoked records since the last
+  // session_rollup. If no prior rollup, count everything in the file (capped
+  // to 50 for sanity).
+  const path = resolve(ROOT, ".harness/telemetry.jsonl");
+  if (!existsSync(path)) return [];
+  const body = readFileSync(path, "utf8");
+  const lines = body.split("\n").filter(Boolean);
+  let startIdx = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const rec = JSON.parse(lines[i]);
+      if (rec.event === "session_rollup") {
+        startIdx = i + 1;
+        break;
+      }
+    } catch { /* skip malformed */ }
+  }
+  const window = lines.slice(startIdx);
+  const skills = [];
+  for (const line of window) {
+    try {
+      const rec = JSON.parse(line);
+      if (rec.event === "skill_invoked" && rec.skill) skills.push(rec.skill);
+    } catch { /* skip */ }
+  }
+  return skills.slice(-50);
+}
+function main() {
+  const input = safeJSON(readStdinSync());
+  const reason = input.end_reason || "unknown";
+  const sessionId = input.session_id || "";
+  const branch = git(["branch", "--show-current"], "(detached)");
+  const sha = git(["rev-parse", "--short", "HEAD"], "(no-git)");
+  const uncommittedRaw = git(["status", "--short"], "");
+  const uncommitted = uncommittedRaw ? uncommittedRaw.split("\n").filter(Boolean).length : 0;
+  const skills = recentSkillInvocations();
+  const record = {
+    ts: new Date().toISOString(),
+    event: "session_rollup",
+    reason,
+    session_id: sessionId,
+    branch,
+    sha,
+    uncommitted,
+    skills_invoked: skills,
+  };
+  const outPath = resolve(ROOT, ".harness/telemetry.jsonl");
+  mkdirSync(resolve(ROOT, ".harness"), { recursive: true });
+  appendFileSync(outPath, JSON.stringify(record) + "\n");
+}
+main();

package/src/templates/scripts/session-start.sh.hbs CHANGED Viewed

@@ -60,6 +60,31 @@ if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; th
   CTX+="[harness] git: branch=$BR, uncommitted=$COUNT file(s)"$'\n'
 fi
+# 1b. One-shot daily pill (harness version + open-feature reminder).
+# `mkdir -p .harness/state` then check the stamp file. Today's pill fires
+# once per UTC day per project; subsequent SessionStarts that day stay
+# silent on this line so the model doesn't see the same banner thirty
+# times per coding day.
+mkdir -p .harness/state 2>/dev/null || true
+STAMP_FILE=".harness/state/session-pill.stamp"
+TODAY=$(date -u +%Y-%m-%d)
+LAST=""
+[ -f "$STAMP_FILE" ] && LAST=$(cat "$STAMP_FILE" 2>/dev/null || echo "")
+if [ "$LAST" != "$TODAY" ]; then
+  HARNESS_VER=""
+  if [ -f harness.config.json ] && have_jp; then
+    HARNESS_VER=$(jp '.version // empty' harness.config.json 2>/dev/null || echo "")
+  fi
+  if [ -z "$HARNESS_VER" ] && [ -f .harness/installed.json ] && have_jp; then
+    HARNESS_VER=$(jp '.version // empty' .harness/installed.json 2>/dev/null || echo "")
+  fi
+  if [ -z "$HARNESS_VER" ]; then
+    HARNESS_VER="unknown"
+  fi
+  CTX+="[harness] pill (one/day): kit=$HARNESS_VER · date=$TODAY"$'\n'
+  printf '%s' "$TODAY" > "$STAMP_FILE" 2>/dev/null || true
+fi
 # 2. Current feature (from feature_list.json) — picks the first entry with
 #    passes=false so the model resumes the in-flight work, not a finished
 #    one. Skipped if file missing or jp unavailable.

package/src/templates/scripts/subagent-stop.sh.hbs ADDED Viewed

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# SubagentStop hook — fires when a subagent finishes its turn (Task tool).
+# Triggers the same structural-test that PostToolUse(Edit) runs, because a
+# subagent can edit files in batches that individually pass but jointly drift
+# off-layer. Running the check at subagent boundary catches that drift early.
+#
+# Contract:
+#   - Never blocks (exit 0 even on failure — the parent Stop hook handles the
+#     final gate). We only emit a stderr summary that Claude reads.
+#   - Telemetry append to .harness/telemetry.jsonl as {event:"subagent_stop"}.
+#   - Skipped when harness.config.json#structuralTest.engine === "none" (the
+#     "structural test not yet wired" escape hatch used by polyglot scaffolds).
+set -eo pipefail
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then jq -r "$1"
+  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+  fi
+}
+SUBAGENT="(unknown)"
+if have_jp; then
+  SUBAGENT=$(echo "$INPUT" | jp '.subagent // .session_id // "unknown"' 2>/dev/null || echo "unknown")
+fi
+# Telemetry first so we record every subagent boundary, even if the
+# structural-test bails below.
+mkdir -p .harness
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
+printf '{"ts":"%s","event":"subagent_stop","subagent":"%s","sha":"%s"}\n' \
+  "$TS" "$SUBAGENT" "$SHA" >> .harness/telemetry.jsonl
+# Skip if structural test disabled.
+if [ -f harness.config.json ] \
+   && grep -qE '"engine"[[:space:]]*:[[:space:]]*"none"' harness.config.json; then
+  exit 0
+fi
+# AHK_HOOK_MODE=warn → log only, don't run.
+if [ "${AHK_HOOK_MODE:-}" = "warn" ]; then
+  exit 0
+fi
+# Run structural test workspace-wide. Subagents typically touch multiple
+# files; per-file scoping would miss the cross-file drift case. Cap output
+# to 30 lines on stderr so the parent agent sees the summary without flood.
+RAN=0
+if [ -f harness/structural-check.mjs ] && command -v node >/dev/null 2>&1; then
+  RAN=1
+  if ! node harness/structural-check.mjs 2>&1 | tail -30 >&2; then
+    echo "[ahk] subagent_stop: structural-test reported violations (see above). Continuing — parent Stop hook will gate." >&2
+  fi
+elif command -v npm >/dev/null 2>&1 && [ -f package.json ] \
+     && grep -q '"harness:check"' package.json 2>/dev/null; then
+  RAN=1
+  if ! npm run --silent harness:check 2>&1 | tail -30 >&2; then
+    echo "[ahk] subagent_stop: structural-test reported violations (see above). Continuing — parent Stop hook will gate." >&2
+  fi
+fi
+if [ "$RAN" = "0" ]; then
+  # No structural-test entry point. Skip silently — already logged in telemetry.
+  exit 0
+fi
+exit 0