docs(#172): correct action-field inventory claim (4 → 3 verbs) + regression guard

Pinpoint #172: SCHEMAS.md v1.5 Emission Baseline documentation inaccuracy
discovered during cycle #98 probe.

The Phase 1 normalization targets section claimed:
  "unify where `action` field appears (only in 4 inventory verbs)"

But reality is only 3 inventory verbs have `action`:
  - mcp
  - skills
  - agents

list-sessions uses `command` instead (the documented 1-of-13 deviation
already captured elsewhere in v1.5 baseline).

This is a doc-truthfulness issue (same family as cycles #76, #79, #82).
Active misdocumentation leads downstream consumers to assume 4-verb
coverage when building adapters/dispatchers.

Changes:
1. SCHEMAS.md: 'only in 4 inventory verbs' → 'only in 3 inventory verbs: mcp, skills, agents'
2. Added regression test `v1_5_action_field_appears_only_in_3_inventory_verbs_172`
   - Asserts mcp/skills/agents HAVE action field
   - Asserts help/version/doctor/status/sandbox/system-prompt/bootstrap-plan/list-sessions do NOT have action field
   - Forces SCHEMAS.md + binary to stay synchronized

Test added:
- `v1_5_action_field_appears_only_in_3_inventory_verbs_172` (8 negative cases + 3 positive cases)

Tests: 227/227 pass (+1 from #172).

Related: #155 (doc parity family), #168c (emission baseline).
Doc-truthfulness family: #76, #79, #82, #172.
This commit is contained in:
YeonGyu-Kim 2026-04-23 08:32:59 +09:00
parent d9b61cc4dc
commit ce352f4750
2 changed files with 45 additions and 1 deletions

View File

@ -689,7 +689,7 @@ Phase 1 (shape stabilization) will normalize these divergences:
- `list-sessions`: `command``kind` (align with 12/13 convention)
- Potentially: unify where `message` field appears (9/13 have it, inconsistently populated)
- Potentially: unify where `action` field appears (only in 4 inventory verbs)
- Potentially: unify where `action` field appears (only in 3 inventory verbs: `mcp`, `skills`, `agents`)
Phase 1 does **not** add common metadata (`timestamp`, `exit_code`) — that's Phase 2 (v2.0 wrapper).

View File

@ -822,6 +822,50 @@ fn unrecognized_argument_still_classifies_as_cli_parse_247_regression_guard() {
);
}
#[test]
fn v1_5_action_field_appears_only_in_3_inventory_verbs_172() {
// #172: SCHEMAS.md v1.5 Emission Baseline claims `action` field appears
// only in 3 inventory verbs: mcp, skills, agents. This test is a
// regression guard for that truthfulness claim. If a new verb adds
// `action`, or one of the 3 removes it, this test fails and forces
// the SCHEMAS.md documentation to stay in sync with reality.
//
// Discovered during cycle #98 probe: earlier SCHEMAS.md draft said
// "only in 4 inventory verbs" but reality was only 3 (list-sessions
// uses `command` instead of `action`). Doc was corrected; this test
// locks the 3-verb invariant.
let root = unique_temp_dir("172-action-inventory");
fs::create_dir_all(&root).expect("temp dir should exist");
let verbs_with_action: &[&str] = &["mcp", "skills", "agents"];
let verbs_without_action: &[&str] = &[
"help",
"version",
"doctor",
"status",
"sandbox",
"system-prompt",
"bootstrap-plan",
"list-sessions",
];
for verb in verbs_with_action {
let envelope = assert_json_command(&root, &["--output-format", "json", verb]);
assert!(
envelope.get("action").is_some(),
"#172: `{verb}` should have `action` field per v1.5 baseline, but envelope: {envelope}"
);
}
for verb in verbs_without_action {
let envelope = assert_json_command(&root, &["--output-format", "json", verb]);
assert!(
envelope.get("action").is_none(),
"#172: `{verb}` should NOT have `action` field per v1.5 baseline (only 3 inventory verbs: mcp/skills/agents should have it), but envelope: {envelope}"
);
}
}
fn assert_json_command_with_env(current_dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Value {
let output = run_claw(current_dir, args, envs);
assert!(