Aria Doctor

aria-doctor

Version: 1.1.0 (ships with aria-plugin v1.27.0+ — adds --self-test and --help flags) Status: Active Spec: openspec/archive/2026-05-23-aria-secret-guard-plugin-default

Functions

check_context_relay()

检测 aria-context-monitor statusLine relay 安装状态(#104),返回 3 态 + jq 可用性 + advisory。纯诊断,read-only。

Script: scripts/check_context_relay.sh

Usage:

bash ${CLAUDE_PLUGIN_ROOT}/skills/aria-doctor/scripts/check_context_relay.sh [--settings PATH]
bash ${CLAUDE_PLUGIN_ROOT}/skills/aria-doctor/scripts/check_context_relay.sh --help

返回 JSON: { state, jq_available, statusline_script, advisory }

jq_available=false 时:relay 写入侧不工作 (relay 块用 jq),仅 transcript fallback 可用;advisory 含安装提示。诊断脚本本身在无 jq 时仍手工拼 JSON 输出 (graceful)。

Exit code: 0 always (state 编码结果)。Ships with aria-plugin v1.33.0。

check_secret_guard_install()

检测 aria-plugin secret-guard hook 当前安装状态(plugin SOT vs project-local copy),返回 5 primary state + 2 sub-flag + 含意建议的 advisory 文本。

Script: scripts/check_secret_guard_install.sh

Usage:

# Single check (returns JSON)
bash ${CLAUDE_PLUGIN_ROOT}/skills/aria-doctor/scripts/check_secret_guard_install.sh \
  [PROJECT_DIR] [PLUGIN_ROOT]

# Self-test (v1.27.0+): runs all 8 unit tests + env diagnostics, human-readable summary
bash ${CLAUDE_PLUGIN_ROOT}/skills/aria-doctor/scripts/check_secret_guard_install.sh --self-test

# Help (v1.27.0+)
bash ${CLAUDE_PLUGIN_ROOT}/skills/aria-doctor/scripts/check_secret_guard_install.sh --help

Output (single-line compact JSON):

{
  "state": "<primary>",
  "sub_flags": ["<flag>", ...],
  "advisory": "<human-readable text>",
  "details": {
    "plugin_hook_present": true|false,
    "local_hook_present": true|false,
    "settings_json_valid": true|false,
    "plugin_version": "1.24.0" | null,
    "local_version": "1.2.0" | null,
    "plugin_sha256": "<hex>" | null,
    "local_sha256": "<hex>" | null,
    "plugin_hook_path": "<abs path>",
    "local_hook_path": "<abs path>"
  }
}

Exit code:

State Schema

Source-of-truth: aria/skills/aria-doctor/scripts/check_secret_guard_install.sh 任何后续 minor 修改 只可 append sub-flag, 不可重命名 / 删除 primary state (per memory feedback_deterministic_structural_skill_rule6_substitute atomicity guard)。 详见 atomicity-guard.md。

5 Primary states (mutually exclusive)

2 Sub-flags (only attached to dual_install)

两个 sub-flag 可同时存在。若 banner 无法解析(见 NF2 ban-missing edge), stale_local_version 不触发(undefined version → skip),只 divergent_content 通过 SHA 比对触发。

Advisory text per state

Banner regex spec (R2 QA NF2 closure)

Project-local secret-guard.sh copy 可选 包含版本 banner(在文件头 20 行内 任一行匹配):

^# (Aria(-plugin)?|secret-guard)[^\n]*\bv([0-9]+\.[0-9]+\.[0-9]+)\b

示例 — 匹配:

# Aria-plugin secret-guard hook v1.24.0
# secret-guard.sh v1.2.0 (SilkNode upstream)
# Aria secret-guard v1.24.0+ (some narrative tail)

示例 — 不匹配 (banner-missing edge case):

# PreToolUse hook (no version banner — SilkNode HEAD shape)
#  v1.24.0 missing leading "# Aria/secret-guard" prefix
# Aria something v1.24 (only 2-part semver, regex requires X.Y.Z)

Behavior on no match:

• local_version field → null
• stale_local_version sub-flag → NOT set (undefined,不与 plugin 版本比较)
• divergent_content sub-flag → 仍由 SHA256 决定 (与 banner 独立)

Why optional banner: SilkNode HEAD scripts 当前无 banner。强制 banner 会破坏"bytewise identical to SilkNode HEAD"的 cherry-pick 契约 (TASK-001 验证要求)。Banner-missing 是 graceful fallback,非错误。

Atomicity guard (Rule #6 structural substitute)

aria-doctor 是 deterministic structural skill — 输入(filesystem state) → 输出(JSON state object)是 pure function,无 LLM 创意空间。因此 Rule #6 benchmark 用 structural substitute 而非 /skill-creator LLM AB (per memory feedback_deterministic_structural_skill_rule6_substitute)。

Substitute artifacts (Rule #6 closure, 详见 aria-plugin-benchmarks/ab-results/2026-05-23-aria-secret-guard-plugin-default-structural/):

Tests

Direct test-file invocation (developer mode)

bash aria/skills/aria-doctor/tests/check_secret_guard_install.test.sh

User-facing self-test (v1.27.0+)

bash ${CLAUDE_PLUGIN_ROOT}/skills/aria-doctor/scripts/check_secret_guard_install.sh --self-test

Wraps the test file with environment diagnostics (bash + jq + python3 versions) + live env check (current dual_install state via the script itself) + summary verdict (ALL PASS ✓ or FAILURES detected ✗). Exit code: 0 all pass, 1 any fail, 2 test file missing (plugin layout drift).

Recommended for: post-install verification / before reporting hook bugs / CI canary checks.

Latest run: 8/8 PASS (initial implementation,2026-05-23)。

Refs

• Spec: openspec/archive/2026-05-23-aria-secret-guard-plugin-default/proposal.md §State Schema for aria-doctor
• Convention: standards/conventions/secret-hygiene.md §6 Local copy + plugin coexist 模式
• Parent decision: .aria/decisions/2026-05-20-secret-rotation-during-m5-deploy.md §5 (Layer 3 决议)
• Brainstorm: .aria/decisions/2026-05-22-aria-secret-guard-plugin-default-brainstorm.md
• Memory:
  • feedback_deterministic_structural_skill_rule6_substitute (Rule #6 substitute pattern)
  • feedback_claude_code_hook_merge_all_fire (Q1 hook orchestrator 实证)

Version history