agent-harness-kit 0.7.0 → 0.9.0

package/src/templates/.claude/skills/garbage-collection/SKILL.md.vi.hbs

@@ -0,0 +1,58 @@
+---
+name: garbage-collection
+description: Use this skill on Fridays, before tagging a release, or when the user mentions "cleanup", "tech debt", "AI slop", "GC", or "garbage collection". Runs the deterministic linters, structural tests, and doc-drift scans, then proposes the top-3 highest-leverage cleanups (with risk/cost/benefit) — does NOT auto-merge. This is the solo-dev shrunk version of OpenAI's Friday garbage-collection ritual.
+allowed-tools: Read, Glob, Grep, Bash(npm run:*), Bash(pytest:*), Bash(ruff:*), Bash(git:*), Bash(gh:*), Bash(node .claude/skills/garbage-collection/scripts/gc-classify.mjs:*)
+suggested-turns: 15
+---
+
+## Các bước
+
+1. **Lấy baseline.** Chạy toàn bộ test suite và lưu output:
+   - {{#if isPython}}`python -m harness.structural_test`{{else}}`npm run harness:check`{{/if}}
+   - {{#if isPython}}`ruff check . --output-format json`{{else}}`npm run lint -- --format json`{{/if}}
+   - Lưu vào `.harness/gc-<date>.json`.
+2. **Phân loại vi phạm.** Với mỗi finding:
+   - **Vi phạm layer** → sửa.
+   - **Duplicate utility** (cùng function body ở 2+ chỗ) → đề xuất
+     trích xuất sang `src/shared/`.
+   - **Dead import** → xóa.
+   - **Doc drift** (đường dẫn trong `docs/architecture.md` không còn tồn tại) →
+     gọi skill `doc-drift-scan`.
+   - **Helper viết tay** trùng với shared utility đã có → đề xuất thay thế.
+3. **Chấm điểm** từng candidate fix trên ba thang điểm 1–5 qua side-car
+   script (thay thế LLM-scored turn trước đây — deterministic và có thể
+   kiểm chứng):
+
+   ```bash
+   node .claude/skills/garbage-collection/scripts/gc-classify.mjs \
+     --baseline .harness/gc-<date>.json \
+     --history  .harness/gc-history.json
+   ```
+
+   Script áp dụng rubric cơ học: `risk = 1 + ceil(touched/3)`,
+   `cost = 1 + ceil(lines/30)`, `benefit = recurrenceCount(class)`. Đọc
+   `candidates[]` JSON đã sort theo `(benefit desc, cost asc, risk asc)`.
+4. **Chỉ đề xuất top 3** cleanup (mức cap cho solo-dev; OpenAI làm hàng chục,
+   bạn làm 3). Mở thành các PR riêng bằng `gh pr create --label gc --draft`.
+5. **Append một row** vào `.harness/gc-history.json`:
+   `{ "date": "...", "violations_found": N, "fixes_opened": M, "total_tokens": K }`.
+6. **Dừng lại.** Không merge gì cả. Phải có human review ở scale solo.
+
+## Output contract
+
+```
+### GC run: <date>
+### Violations found: <N>
+### Top 3 fixes proposed:
+1. <slug> — risk:<1-5> cost:<1-5> benefit:<1-5> — PR #<n>
+2. ...
+3. ...
+### Fixes deferred (not in top 3): <count>
+```
+
+## Anti-patterns
+
+- Không mở quá 3 PR trong một lần chạy. Cap đó là feature, không phải bug.
+- Không auto-merge — toàn bộ ý nghĩa của GC ở solo scale là human review.
+- Không bỏ qua các findings điểm thấp; record chúng vào
+  `.harness/gc-history.json` để xu hướng nổi lên theo thời gian.

package/src/templates/.claude/skills/garbage-collection/scripts/gc-classify.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// gc-classify.mjs — deterministic scoring step for /garbage-collection.
+// Replaces "LLM-scored risk/cost/benefit" turn with mechanical rubric.
+//
+// Usage:
+//   gc-classify.mjs --baseline <gc-snapshot.json> [--history <hist.json>] [--out <file>]
+//
+// Rubric:
+//   risk    = 1 + ceil(touched_files / 3)            capped at 5
+//   cost    = 1 + ceil(lines_to_change / 30)         capped at 5
+//   benefit = recurrenceCount(class) from gc-history capped at 5
+
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function loadJSON(p, fallback = null) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return fallback; }
+}
+
+function parseArgs(argv) {
+  const out = { baseline: null, history: ".harness/gc-history.json", out: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--baseline") out.baseline = argv[++i];
+    else if (argv[i] === "--history") out.history = argv[++i];
+    else if (argv[i] === "--out") out.out = argv[++i];
+  }
+  if (!out.baseline) {
+    console.error("usage: gc-classify.mjs --baseline <gc-snapshot.json> [--history <hist.json>] [--out <file>]");
+    process.exit(2);
+  }
+  return out;
+}
+
+function recurrenceCount(history, klass) {
+  if (!history?.runs) return 1;
+  let n = 0;
+  for (const run of history.runs) {
+    if (Array.isArray(run.classes_seen) && run.classes_seen.includes(klass)) n++;
+  }
+  return n;
+}
+
+function cap5(n) { return Math.max(1, Math.min(5, n)); }
+
+function classify(baseline, history) {
+  const violations = Array.isArray(baseline?.violations) ? baseline.violations : [];
+  return violations.map((v) => {
+    const touched = Number(v.files_touched) || 1;
+    const lines = Number(v.lines_estimate) || 5;
+    return {
+      class: v.class || "unknown",
+      path: v.path || "(unspecified)",
+      summary: v.summary || `${v.class} at ${v.path || "(unspecified)"}`,
+      risk: cap5(1 + Math.ceil(touched / 3)),
+      cost: cap5(1 + Math.ceil(lines / 30)),
+      benefit: cap5(recurrenceCount(history, v.class)),
+    };
+  });
+}
+
+function main() {
+  const { baseline, history: histPath, out } = parseArgs(process.argv.slice(2));
+  const base = loadJSON(resolve(baseline));
+  if (!base) {
+    console.error(`gc-classify: cannot read baseline at ${baseline}`);
+    process.exit(2);
+  }
+  const hist = existsSync(resolve(histPath)) ? loadJSON(resolve(histPath), { runs: [] }) : { runs: [] };
+  const scored = classify(base, hist);
+  scored.sort((a, b) => b.benefit - a.benefit || a.cost - b.cost || a.risk - b.risk);
+  const payload = { total: scored.length, candidates: scored };
+  const text = JSON.stringify(payload, null, 2);
+  if (out) writeFileSync(resolve(out), text + "\n");
+  else process.stdout.write(text + "\n");
+}
+
+main();

package/src/templates/.claude/skills/i18n-add-locale/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: i18n-add-locale
+description: Use this skill to scaffold a new human-language locale for the kit's skills/agents/CLAUDE.md. Mirrors every existing SKILL.md.hbs into a SKILL.md.<locale>.hbs stub so a translator (or LLM) can edit copy without touching machine-readable frontmatter. Default locale codes — vi, ja, fr, es, de — but accepts any 2-5 char code.
+allowed-tools: Read, Write, Bash(node scripts/locale-scaffold.mjs:*)
+suggested-turns: 4
+---
+
+## When to invoke
+
+- Adding a new human language to the kit (or a fork's downstream).
+- After upstream adds a new English skill — re-running this skill scaffolds
+  the locale stubs for the new file, leaving translated files untouched.
+
+## Steps
+
+1. **Pick a locale.** Two-to-five char ISO code (vi, ja, fr-CA, etc.).
+2. **Dry-run the scan.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code> --dry-run
+   ```
+   Lists every SKILL.md / SKILL.md.hbs that lacks a `.<locale>.hbs` sibling.
+3. **Materialize stubs.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code>
+   ```
+   For each missing sibling, copies the English master and prepends a
+   `<!-- LOCALE_TODO: translate body --> ` banner so the translator can grep
+   for pending work.
+4. **Register the locale.** Edit `src/core/render-templates.mjs` and add the
+   code to `SUPPORTED_HUMAN_LANGS`. The renderer picks the variant via
+   `--locale <code>` or `HARNESS_LOCALE` env.
+5. **Verify rendering** by running `agent-harness-kit init --locale <code>`
+   in a scratch dir and grepping the output for `LOCALE_TODO` (must be
+   zero before publishing).
+
+## Output contract
+
+```
+locale: <code>
+scaffolded: <N>
+already-present: <M>
+register-in: src/core/render-templates.mjs (SUPPORTED_HUMAN_LANGS)
+```
+
+## Anti-patterns
+
+- Don't translate the YAML frontmatter — the renderer + Claude Code parse
+  it as machine-readable. Translate only the body markdown.
+- Don't drop the master `.hbs` file. The locale stub *augments*; the
+  renderer falls back to the master when the locale variant is missing.

package/src/templates/.claude/skills/i18n-add-locale/SKILL.md.vi

@@ -0,0 +1,56 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/i18n-add-locale/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: i18n-add-locale
+description: Use this skill to scaffold a new human-language locale for the kit's skills/agents/CLAUDE.md. Mirrors every existing SKILL.md.hbs into a SKILL.md.<locale>.hbs stub so a translator (or LLM) can edit copy without touching machine-readable frontmatter. Default locale codes — vi, ja, fr, es, de — but accepts any 2-5 char code.
+allowed-tools: Read, Write, Bash(node scripts/locale-scaffold.mjs:*)
+suggested-turns: 4
+---
+
+## When to invoke
+
+- Adding a new human language to the kit (or a fork's downstream).
+- After upstream adds a new English skill — re-running this skill scaffolds
+  the locale stubs for the new file, leaving translated files untouched.
+
+## Steps
+
+1. **Pick a locale.** Two-to-five char ISO code (vi, ja, fr-CA, etc.).
+2. **Dry-run the scan.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code> --dry-run
+   ```
+   Lists every SKILL.md / SKILL.md.hbs that lacks a `.<locale>.hbs` sibling.
+3. **Materialize stubs.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code>
+   ```
+   For each missing sibling, copies the English master and prepends a
+   `<!-- LOCALE_TODO: translate body --> ` banner so the translator can grep
+   for pending work.
+4. **Register the locale.** Edit `src/core/render-templates.mjs` and add the
+   code to `SUPPORTED_HUMAN_LANGS`. The renderer picks the variant via
+   `--locale <code>` or `HARNESS_LOCALE` env.
+5. **Verify rendering** by running `agent-harness-kit init --locale <code>`
+   in a scratch dir and grepping the output for `LOCALE_TODO` (must be
+   zero before publishing).
+
+## Output contract
+
+```
+locale: <code>
+scaffolded: <N>
+already-present: <M>
+register-in: src/core/render-templates.mjs (SUPPORTED_HUMAN_LANGS)
+```
+
+## Anti-patterns
+
+- Don't translate the YAML frontmatter — the renderer + Claude Code parse
+  it as machine-readable. Translate only the body markdown.
+- Don't drop the master `.hbs` file. The locale stub *augments*; the
+  renderer falls back to the master when the locale variant is missing.

package/src/templates/.claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// locale-scaffold.mjs — deterministic step for /i18n-add-locale.
+// Walks .claude/skills/* (and a small whitelist of other files) and scaffolds
+// missing `.<locale>.hbs` siblings from their English masters.
+//
+// Usage:
+//   locale-scaffold.mjs --locale vi [--dry-run] [--root .claude/skills]
+//
+// A "master" file is either:
+//   - <stem>.md.hbs        → scaffold sibling <stem>.md.<locale>.hbs
+//   - <stem>.md            → scaffold sibling <stem>.md.<locale>.hbs
+//                            (rare; only when no .hbs counterpart exists)
+//
+// Idempotent: if the sibling already exists, the script leaves it alone.
+
+import { readFileSync, existsSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { resolve, join, dirname, basename, relative } from "node:path";
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function parseArgs(argv) {
+  const out = { locale: null, dryRun: false, roots: [".claude/skills", ".claude/agents"] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--locale") out.locale = argv[++i];
+    else if (argv[i] === "--dry-run") out.dryRun = true;
+    else if (argv[i] === "--root") out.roots = [argv[++i]];
+  }
+  if (!out.locale || !/^[a-z]{2,5}(-[A-Z]{2})?$/.test(out.locale)) {
+    console.error("usage: locale-scaffold.mjs --locale <code> [--dry-run] [--root <dir>]");
+    console.error("  <code> = 2-5 lowercase letters, optional region (e.g. vi, ja, fr-CA)");
+    process.exit(2);
+  }
+  return out;
+}
+
+function* walk(dir) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) yield* walk(full);
+    else yield full;
+  }
+}
+
+function isMaster(path, locale) {
+  // English masters: *.md or *.md.hbs (but NOT *.md.<locale>.hbs already).
+  const name = basename(path);
+  if (!/\.md(?:\.hbs)?$/.test(name)) return false;
+  // Skip locale-specific files of any code.
+  if (/\.md\.[a-z]{2,5}(?:-[A-Z]{2})?\.hbs$/.test(name)) return false;
+  return true;
+}
+
+function siblingPath(masterPath, locale) {
+  // Preserve the master's Handlebars-ness in the variant. Master .md.hbs
+  // → variant .md.<lang>.hbs (Handlebars-active). Master .md (plain) →
+  // variant .md.<lang> (no Handlebars). This matters because plain-md
+  // masters often contain literal `{{...}}` strings as examples (e.g.
+  // XSS demos in security-reviewer.md); promoting them to .hbs would
+  // make Handlebars choke on the example text.
+  const name = basename(masterPath);
+  if (name.endsWith(".md.hbs")) {
+    return join(dirname(masterPath), name.replace(/\.md\.hbs$/, `.md.${locale}.hbs`));
+  }
+  if (name.endsWith(".md")) {
+    return join(dirname(masterPath), name.replace(/\.md$/, `.md.${locale}`));
+  }
+  return null;
+}
+
+function scaffold(masterPath, siblingPathAbs, locale, dryRun) {
+  if (existsSync(siblingPathAbs)) return { status: "skip", reason: "exists" };
+  if (dryRun) return { status: "would-create" };
+  const body = readFileSync(masterPath, "utf8");
+  const banner =
+`<!-- LOCALE_TODO: translate body to ${locale} -->
+<!-- Source: ${relative(ROOT, masterPath)} -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+`;
+  writeFileSync(siblingPathAbs, banner + body);
+  return { status: "created" };
+}
+
+function main() {
+  const { locale, dryRun, roots } = parseArgs(process.argv.slice(2));
+  const masters = [];
+  for (const r of roots) {
+    const abs = resolve(ROOT, r);
+    if (!existsSync(abs)) continue;
+    for (const f of walk(abs)) {
+      if (isMaster(f, locale)) masters.push(f);
+    }
+  }
+  let created = 0;
+  let skipped = 0;
+  const wouldCreate = [];
+  for (const m of masters) {
+    const sib = siblingPath(m, locale);
+    if (!sib) continue;
+    const res = scaffold(m, sib, locale, dryRun);
+    if (res.status === "created") created++;
+    else if (res.status === "would-create") wouldCreate.push(relative(ROOT, sib));
+    else skipped++;
+  }
+  const payload = {
+    locale,
+    dry_run: dryRun,
+    scaffolded: dryRun ? wouldCreate.length : created,
+    already_present: skipped,
+    scanned_masters: masters.length,
+    would_create: dryRun ? wouldCreate : undefined,
+    register_in: "src/core/render-templates.mjs#SUPPORTED_HUMAN_LANGS",
+  };
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+
+main();

package/src/templates/.claude/skills/inspect-app/SKILL.md.vi

@@ -0,0 +1,61 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/inspect-app/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: inspect-app
+description: Use this skill whenever the user asks to "test the UI", "check what the app looks like", "inspect the page", "verify the dev server is up", or before claiming a UI feature is done. Boots the dev server via scripts/dev-up.sh and drives the failing flow through Playwright MCP if installed (else falls back to curl + lightweight HTML capture). Mirrors the OpenAI Chrome-DevTools-Protocol-into-runtime pattern at solo scale — verify the running app, don't trust the type checker alone.
+allowed-tools: Read, Bash(scripts/dev-up.sh), Bash(curl:*), Bash(playwright:*), Bash(node:*)
+suggested-turns: 12
+---
+
+## When to use
+
+The user said any of: "what does the page look like", "test the UI flow",
+"is the dev server up", "before merging the UI work", or invoked this skill
+explicitly via `/inspect-app`. Also auto-invokes from `/debug-flow` when the
+bug is UI-shaped.
+
+## Steps
+
+1. **Detect dev server.** Read `harness.config.json` for the framework.
+   - If a process is already listening on the expected port (3000 / 8000 /
+     5000 depending on framework), reuse it.
+   - Else: `bash scripts/dev-up.sh &` in the background and wait up to 30s
+     for the readiness probe.
+2. **Capture mode — Playwright MCP (preferred).** If `mcp__playwright__*`
+   tools are available:
+   - `mcp__playwright__browser_navigate` to the target URL
+   - `mcp__playwright__browser_snapshot` for accessibility tree
+   - `mcp__playwright__browser_take_screenshot` for a visual
+   - Optionally drive a single user flow (click → fill → click → wait)
+3. **Capture mode — curl fallback.** If MCP is unavailable:
+   - `curl -i -s -o response.body "http://localhost:$PORT$PATH"` for headers + body
+   - `wc -l response.body` to size-check
+   - `grep -E '<title>|<h1>' response.body | head -5` for sanity
+4. **Diff against expectation.** If the user gave an expected element /
+   text, grep for it. If not, just report what's on the page.
+5. **Cleanup.** Kill the dev server we started (don't kill ones already
+   running before this session).
+
+## Output contract
+
+```
+### App inspection
+**URL:** http://localhost:<port><path>
+**Status:** <HTTP status>
+**Title:** <page title or first H1>
+**Mode:** playwright-mcp | curl-fallback
+**Screenshot:** <path or "n/a">
+**Findings:** <bulleted list of matches/mismatches against expectation>
+```
+
+## Anti-patterns
+
+- Don't claim a UI feature is done without running this skill once.
+- Don't leave a dev server running after the inspection — kill what you
+  started.
+- Don't grep for "Error" alone as a failure signal — many pages legitimately
+  contain that word. Match against specific expected text instead.
+- Don't take screenshots of pages with secrets or test fixtures with PII —
+  the screenshot lands on disk.

package/src/templates/.claude/skills/inspect-module/SKILL.md.hbs

@@ -1,7 +1,7 @@
 ---
 name: inspect-module
 description: Use this skill whenever the user mentions "explore", "inspect", "understand", "what does X do", "where is Y", or before adding a new feature in an unfamiliar area. Produces a structured map of one module — files, exports, dependencies, layer assignment, and recent commits — without reading the entire codebase. Always invoke this skill before editing an unfamiliar module so the agent has accurate context, not guesses.
-allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*)
+allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*), Bash(node .claude/skills/inspect-module/scripts/module-summary.mjs:*)
 suggested-turns: 6
 ---
 
@@ -15,19 +15,22 @@ feature Y, what's in the area?", "explore <path>", "show me the shape of
 
 1. **Resolve the target.** If the user gave a feature name (not a path), grep
    `feature_list.json` for it. If multiple paths match, ask the user which.
-2. **Recent activity.** Run `git log --oneline -20 -- <target>` and read the
-   top 3 commit messages.
-3. **Layer.** Cross-reference the path against `harness.config.json` →
-   `domains[].layers` to determine the layer.
-4. **Public surface.** List exported symbols:
-   - TypeScript: `grep -nE "^export " <target>/**/*.ts`
-   - Python: `grep -nE "^def |^class |^[A-Z_][A-Z0-9_]+ ?=" <target>/**/*.py`
-5. **Dependencies.** List inbound imports (who depends on this module) and
-   outbound imports (what this module depends on). Verify both respect the
-   forward-only layer order; if not, **stop and report the violation** before
-   proceeding with any change plan.
-6. **Risks.** Flag any of: dynamic imports, eval, shell-out with
-   interpolation, missing tests for an exported function.
+2. **One-shot summary (deterministic).** Run the side-car script — bundles
+   exports + inbound + outbound deps + layer + recent commits into one JSON
+   blob, replacing three LLM turns of grep:
+
+   ```bash
+   node .claude/skills/inspect-module/scripts/module-summary.mjs <target>
+   ```
+
+   Read the JSON. If `layer` is `null`, the file is outside any configured
+   layer root — flag that and ask whether the user wants to add it.
+3. **Forward-only check.** Walk `outbound[]` and verify each crosses layers
+   forward only (never backward). The structural test enforces this
+   mechanically too, but flagging here short-circuits a wasted write step.
+4. **Risks.** Flag any of: dynamic imports, eval, shell-out with
+   interpolation, missing tests for an exported function. (LLM judgment —
+   the side-car reports facts, not risks.)
 
 ## Output contract
 

package/src/templates/.claude/skills/inspect-module/SKILL.md.vi.hbs

@@ -0,0 +1,57 @@
+---
+name: inspect-module
+description: Use this skill whenever the user mentions "explore", "inspect", "understand", "what does X do", "where is Y", or before adding a new feature in an unfamiliar area. Produces a structured map of one module — files, exports, dependencies, layer assignment, and recent commits — without reading the entire codebase. Always invoke this skill before editing an unfamiliar module so the agent has accurate context, not guesses.
+allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*), Bash(node .claude/skills/inspect-module/scripts/module-summary.mjs:*)
+suggested-turns: 6
+---
+
+## Khi nào dùng
+
+User hỏi bất cứ câu nào dạng: "X hoạt động như thế nào", "trong src/foo
+có gì", "trước khi thêm feature Y, khu vực này có gì?", "explore <path>",
+"hiện cho tôi shape của <module>".
+
+## Các bước
+
+1. **Resolve target.** Nếu user đưa tên feature (không phải path), grep
+   `feature_list.json` để tìm. Nếu nhiều path khớp, hỏi user chọn cái nào.
+2. **Tóm tắt one-shot (deterministic).** Chạy side-car script — bundles
+   exports + inbound + outbound deps + layer + recent commits vào một JSON
+   blob, thay thế ba LLM turn grep:
+
+   ```bash
+   node .claude/skills/inspect-module/scripts/module-summary.mjs <target>
+   ```
+
+   Đọc JSON. Nếu `layer` là `null`, file nằm ngoài layer root đã config —
+   flag điều đó và hỏi user có muốn thêm vào layer không.
+3. **Forward-only check.** Đi qua `outbound[]` và xác minh mỗi outbound
+   cross layer theo chiều tiến (không bao giờ ngược). Structural test sẽ
+   enforce điều này cơ học rồi, nhưng flag ở đây tránh được một write step
+   bị lãng phí.
+4. **Rủi ro.** Flag bất kỳ trường hợp nào: dynamic imports, eval, shell-out
+   với interpolation, missing tests cho function được export. (LLM judgment
+   — side-car report facts, không report risks.)
+
+## Output contract
+
+Tạo Markdown report với các section sau, theo thứ tự này:
+
+```
+### Module: <path>
+### Layer: <layer-name>
+### Public surface: <list>
+### Inbound deps: <list of paths>
+### Outbound deps: <list of paths or external packages>
+### Recent changes: <top 3 commit messages>
+### Risks: <bulleted list, "none" nếu clean>
+```
+
+Kết thúc bằng: "Tôi sẵn sàng thay đổi `<module>`. Architecture-reviewer
+subagent sẽ được gọi khi hoàn tất."
+
+## Anti-patterns
+
+- Không đọc mọi file trong module — sample exports, rồi chỉ drill in
+  vào nơi mà task của user chỉ tới.
+- Không đề xuất changes trong skill này. Đây là read-only context-gathering.