LATX, docs: Add shared agent guidance and skills

[LaurenIsACoder]

Summary

• add repository-wide AGENTS.md guidance for supported scope, change safety,
  local test expectations, and evidence boundaries
• add explicit repo-scoped Fix and end-to-end performance optimization Skills;
  keep universal contracts in each SKILL.md and load conditional references
  progressively
• provide a default-read-only Fix context manifest helper and a Sphinx-indexed
  current LATX translation/debugging model without stale TU-JIT assumptions

使用教程（中文）

1. AGENTS.md 如何生效

在 LAT 仓库目录中启动新的 Codex 任务时，Codex 会自动读取仓库根目录的
AGENTS.md，不需要手工调用。它提供项目范围、修改安全、测试要求和证据边界等
公共规则。

如果刚刚拉取或修改了 AGENTS.md，请重新启动 Codex 任务，使新的指令链生效。

2. 查看和调用项目 Skill

在 Codex CLI 或 IDE 中可以输入 /skills，或者输入 $ 查看可用 Skill。

本 PR 的两个 Skill 禁止隐式调用，必须在请求中显式写出 Skill 名称：

$lat-fix-validation
$lat-performance-experiment

3. 修复或诊断 Bug

遇到 crash、hang、错误结果、兼容性回归、间歇性故障或测试失败时使用：

$lat-fix-validation 请诊断这个间歇性崩溃，先确认复现环境和实际执行路径，
再分析根因并给出回归验证计划。

Skill 会先区分 diagnosis、implementation 和 existing-candidate validation。只要求
诊断或验证时，不授权编辑 repository、source、test 或 tracked documentation 文件；
temporary instrumentation 也需要编辑授权。没有授权时停在证据结论和下一步计划。

主 SKILL.md 固定所有 Fix 都不能省略的合同：可信 RED、相关身份和实际路径、历史
意图与旧不变量、first divergence、owning layer、probe 不是 GREEN、原始复现终态、
项目测试门禁和诚实结论。具体方法按场景渐进加载：

• runtime、binary、cache、harness、间歇性或现场问题：复现完整性 reference；
• translator/codegen、dump、GDB 或反汇编：translator root-cause reference；
• metadata、layout、register 或 path symmetry：translator invariant reference；
• test seam、验证矩阵、sentinel 或 field gate：regression reference；
• guest/native、loader、callback、共享状态或生命周期：cross-boundary reference；
• CI、Review、产品接受或 handoff：evidence reference。

这些 references 是按需工具箱，不是每个 Bug 都要机械执行的统一命令清单。

4. 进行性能优化

只有性能问题、尚未确定瓶颈或 candidate 时使用：

$lat-performance-experiment 请先定义产品性能问题并建立稳定 baseline，定位主要
瓶颈，形成可证伪的优化假设；得到实现授权后再构造最小 candidate，并完成正确性、
路径证明和多轮成对测量。

已经有具体优化 candidate 时使用：

$lat-performance-experiment 请验证这个 EFLAGS 优化，隔离 baseline 和 candidate，
先验证正确性，再做多轮成对测量，并分别报告机制和端到端结论。

该 Skill 固定的是必要动作和证据门禁：可信 baseline、瓶颈归因、可证伪假设、实现
授权、正确性、实际路径、隔离测量和诚实决策。它不会写死 profiler、PMU 事件、
优化 pass 或实现方式；Agent 可以根据当前证据选择或设计最能区分假设的方法。

5. 中文对话

Skill 正文使用英文，开发者仍可完全使用中文描述任务并要求中文回答。显式
$skill-name 决定调用哪个 Skill，提问语言不会改变调用结果。

6. 可选：记录 Fix 复现身份

复杂 Fix 可以使用辅助脚本记录 Git、host、binary、runtime、开关和复现身份。脚本默认
只读采集并向 stdout 输出；显式指定 --output 时才写入清单文件及其必要父目录：

.agents/skills/lat-fix-validation/scripts/capture_fix_context.py \
  --repo . \
  --binary /path/to/candidate-binary \
  --switch LATX_AOT=0 \
  --workload workload-name \
  --redact-paths \
  --output fix-context.json

即使使用了 --redact-paths，对外分享前仍应人工检查命令、分支名和手工输入内容。

7. 权限边界

这些文件只提供工作流和约束，不会自动授权修改代码、push、创建或修改 PR、发布
release、重写公开历史或修改目标机。此类操作仍需任务中的明确授权。

Validation

• git diff --check
• Skill frontmatter, invocation-policy YAML, Markdown links/fences, and privacy
  scan
• capture_fix_context.py JSON, redaction, invalid-input, executable-mode, and
  read-only smoke checks
• explicit Fix and performance Skill invocation probes, including an
  English-Skill/Chinese-prompt check
• no-candidate performance forward test covering baseline, bottleneck
  attribution, hypothesis, authorization, candidate, correctness, and paired
  measurement without prescribing a profiler or implementation
• progressive Fix forward tests for diagnosis-only translator work,
  cross-boundary intermittent callbacks, and compile-only candidate validation
• current-master source audit for debug-option build conditions, dump boundaries,
  and TB/AOT translation entry points
• Sphinx source-format and toctree validation for the LATX debugging model

Validation boundary

The complete local lat-pr-fast suite was not rerun for this documentation-only
follow-up because an approved local LoongArch environment was unavailable. The
previous head passed CI, but those results do not validate this diff. This Draft
must remain unready for merge until the new head completes its own required CI;
this is an explicit exception to the repository's normal local pre-PR gate.

Notes

• no product code or runtime behavior changes
• Skills require explicit $lat-fix-validation or
  $lat-performance-experiment invocation
• all five commits will carry matching DCO sign-offs after local approval