release(v4.8.3): bump framework and eight skills to 4.8.3 in lockstep; archive PR #46 reviews (two rounds)

Issue #42 stages 1-2: the SKILL.md code-block inventory as test data and the removal of blocks the entry scripts already do. Merge-workspace review: round 1 (@8d26106) claude agy grok PASS, codex NOT PASS (R1-R3); fixed in 17eba09 (docs, inventory data and the guard test only); round 2 4/4 PASS. Full suite at 8d26106 1408 passed / 0 failed. Reports and the round-2 identity sidecars go to .agents/reports/<session>/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCgu9Fa9iT7TbJUSzdq4Ff
2026-10-04 08:36:15 +09:00
1 parent 17eba0904e
commit 44999ff2fb
@@ -0,0 +1,113 @@
+# Final Review Report: Job a783001f (PR #46 / Issue #42 Stages 1 & 2)
+
+## 1. Review Identity & Metadata
+- **Loop ID**: `loop-20261003T222707Z-a0de27`
+- **Job ID**: `a783001f`
+- **Reviewer**: agy (session: `herdr:reviewer-agy-01`)
+- **Base Commit**: `45d1621c93504e6cfa347b31995f70da868f4172` (main, v4.8.2)
+- **Head Commit**: `8d26106195a0a24621f140e76389d206332f84c0` (3 commits)
+- **Tree Hash**: `b579380959e08f721492386da904972092bf8d7f`
+- **Verification Path**: `/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1`
+- **Git Status**: Clean (working tree clean, no uncommitted changes)
+- **Whitespace Check (`git diff base...HEAD --check`)**: Clean (0 errors)
+
+---
+
+## 2. Commit Range Audit (base..head)
+
+The branch contains 3 atomic commits:
+1. `7670b41`: `docs(issue-42): stages 1-2 - SKILL.md code-block inventory as test data; remove blocks the scripts already do`
+2. `e6a46cd`: `fix(issue-42): review R1 - stop's exit 1 also comes after the stop`
+3. `8d26106`: `test(issue-42): review R2 - a passthrough code must be in the exit table`
+
+Modified files:
+- `.agents/skills/multi-agent-mux-create/SKILL.md` (lines: -105, +44)
+- `.agents/skills/multi-agent-mux-resume/SKILL.md` (lines: -64, +28)
+- `.agents/skills/multi-agent-mux-status/SKILL.md` (lines: -16, +27)
+- `.agents/skills/multi-agent-mux-stop/SKILL.md` (lines: -27, +15)
+- `tests/data/skill_code_blocks.json` (+624 lines)
+- `tests/test_issue42_skill_blocks.py` (+193 lines)
+
+**Product Code Modification**: None (0 lines in `.sh` or `.py` product files).
+
+---
+
+## 3. Evaluation of Review Items
+
+### Item 1: Accuracy of Code Block Classification
+- **Removed (a) Blocks (5 blocks)**:
+  1. `multi-agent-mux-resume` Workflow (base lines 59–118): Replaced by `resume_session.sh` entry point call. All original steps are accounted for in [`resume_session.sh`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh):
+     - Session ID resolution: lines 111–130 (`resolve_session_id.sh`).
+     - Fresh-spawn fallback for Class A agents: lines 133–144.
+     - herdr alive check: lines 147–158 (updates YAML row and exits 0; attach is intentionally separate).
+     - Command construction (`CMD_FULL`): lines 172–197 (via adapter `resume-spec`/`spawn-spec`).
+     - Spawning session: line 237 (`herdr new-session`).
+     - Dialog handling: line 241 (`handle_startup_dialogs`).
+     - YAML update: lines 247–250 (`update_yaml_resumed.sh`).
+  2. `multi-agent-mux-stop` Pre-flight (base lines 38–63): Checked directly inside [`stop_session.sh`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1/.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh) at lines 99, 140–143, and 184–188.
+  3. `multi-agent-mux-create` Pre-flight (base lines 35–52): Checked directly inside [`create_session.sh`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1/.agents/skills/multi-agent-mux-create/scripts/create_session.sh) at lines 111–156 (herdr installation, agent binary, auth, workspace).
+  4. `multi-agent-mux-create` Workflow (base lines 168–220): Checked and handled entirely by [`create_session.sh`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1/.agents/skills/multi-agent-mux-create/scripts/create_session.sh) (adapter `spawn-spec`, TUI readiness wait, exit code handling).
+  5. `multi-agent-mux-create` Manual YAML row append (base lines 226–252): Handled automatically by [`create_session.sh`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1/.agents/skills/multi-agent-mux-create/scripts/create_session.sh) at lines 491–610.
+- **Retained (b) Blocks (5 blocks)**:
+  - `create` post-create checks, `monitor` agent-run polling loop, `resume` post-resume checks, `status` pre-flight checks, and `stop` post-stop checks. None of these have a standalone script entry point; they remain documented as manual/verification steps and provide input for Stage 3.
+- **Conclusion**: Classification across all 37 blocks is verified with valid `file:line` evidence.
+
+### Item 2: Option Tables, Exit Codes, and Documentation Corrections
+- **Exit Code Tables**:
+  - `create_session.sh`: Codes 0, 1, 2, 3, 4, 42, 43, `other`. Passthrough `4` from Python `SystemExit(4)` on duplicate running row (`create_session.sh:515`) is explicitly verified.
+  - `resume_session.sh`: Codes 0, 1, 2, `other`.
+  - `stop_session.sh`: Codes 0, 1, 2, 3, 4, `other`. Follow-up R1 (`e6a46cd`) and R2 (`8d26106`) verified that passthrough code `1` from post-stop registry update (`stop_session.sh:310`) is properly declared in `entry_points.passthrough` and explained in the table.
+- **Documentation Discrepancy Corrections**:
+  1. `resume` Case 3: Accurately documents that an already-running session updates the row and exits 0 without auto-attaching or checking permissions (`SKILL.md:240`).
+  2. `stop` `--purge-conversation`: Clarified that `--yes` is required to avoid exit 3 (`SKILL.md:461`).
+  3. `status` `--json`: Aligned schema with `reconcile.sh` drift object and `sessions_detail` list (`SKILL.md:364-414`).
+  4. `create` `cmd_full`: Replaced static table with note that command line is determined by adapter `spawn-spec` (`SKILL.md:218`).
+  5. `create` nonexistent `agent-sessions-yaml-edit`: Reference removed (`SKILL.md:218`).
+
+### Item 3: Agent Executability & Safety
+- Each skill workflow now directs the agent to a clear, robust one-line CLI invocation.
+- Destructive workflows (e.g., `--purge-conversation`) explicitly mandate interactive user confirmation before passing `--yes`.
+- Error recovery guidance (e.g., inspecting status if post-kill or post-spawn updates fail) is thoroughly documented.
+
+### Item 4: Robustness of Test Guard (`test_issue42_skill_blocks.py`)
+- Code block parsing accurately accounts for variable fence lengths, indentation inside lists, and language tags.
+- Exit code analysis (`_scan_exits`) skips comments and heredoc blocks to separate shell `exit N` from Python `SystemExit(N)`.
+- Test suite validates that all 8 skills have inventories, all removed blocks have valid script replacements, all declared exit codes and passthroughs match script reality, and all evidence pointers reference valid file lines.
+- Existing documentation tests in [`tests/test_tier2_component.py`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1/tests/test_tier2_component.py) continue to pass completely (42/42 passed).
+
+### Item 5: Scope & Boundaries
+- `git diff --stat` confirms only documentation (`SKILL.md`), test data (`tests/data/skill_code_blocks.json`), and test code (`tests/test_issue42_skill_blocks.py`) were changed.
+- No product logic changed.
+- No version bump.
+
+### Item 6: Inquiry on `tests/test_issue10_13_purge.py` Baseline
+- Executed `tests/test_issue10_13_purge.py` in the verification environment: 23 passed in 11.10 s.
+- Confirmed that the 12 failures cited in PR description refer to existing Linux-specific CI baselines (Issue #28). On this macOS host, all tests pass cleanly and are unrelated to PR #46.
+
+---
+
+## 4. Test Suite Execution Results
+
+All tests executed in the verification worktree (`/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T222707Z-a0de27/1`) with `--basetemp=/tmp/pytest-pr46-review`:
+
+| Test File | Result | Duration |
+|---|---|---|
+| `tests/test_issue42_skill_blocks.py` | 28 passed, 1 skipped* | 0.07 s |
+| `tests/test_tier2_component.py` | 42 passed | 249.66 s |
+| `tests/test_orc_onboard.py` | 13 passed | 2.59 s |
+| `tests/test_loop_cli.py` | 20 passed | 37.19 s |
+| `tests/test_o1_rebuttal.py` | 11 passed | 1.83 s |
+| `tests/test_version_consistency.py` | 15 passed | 2.69 s |
+| `tests/test_issue10_13_purge.py` | 23 passed | 11.10 s |
+
+*\* Note: `test_claude_skills_link_resolves_to_agents_skills` skipped as expected because `.claude/skills` symlink is untracked and absent in the detached review worktree.*
+
+**Total Tested**: 152 passed, 1 skipped, 0 failed.
+
+---
+
+## 5. Conclusion
+
+All requirements for Issue #42 Stages 1 and 2 are cleanly and accurately satisfied without product regressions or scope creep.
+
+[VERDICT: PASS]
@@ -0,0 +1,14 @@
+{
+  "loop_id": "loop-20261003T230658Z-e7866a",
+  "base_sha": "8d26106195a0a24621f140e76389d206332f84c0",
+  "head_sha": "17eba0904ebbf54c1d2243ad61a6f2ba17263889",
+  "tree_sha": "a0f1ffede44be7c86267a56b25871e1d081feafb",
+  "review_commit": "17eba0904ebbf54c1d2243ad61a6f2ba17263889",
+  "reviewer": "reviewer-agy-01",
+  "job_id": "e722c7b8",
+  "verdict": "PASS",
+  "transport": "herdr",
+  "evidence": "review-tree",
+  "isolation": "worktree",
+  "verified_at": "2026-10-03T23:35:18Z"
+}
@@ -0,0 +1,87 @@
+# Final Review Report: Job e722c7b8 (PR #46 / Issue #42 Round 2 Delta)
+
+## 1. Review Identity & Metadata
+- **Loop ID**: `loop-20261003T230658Z-e7866a`
+- **Job ID**: `e722c7b8`
+- **Reviewer**: agy (session: `herdr:reviewer-agy-01`)
+- **Base Commit**: `8d26106195a0a24621f140e76389d206332f84c0` (Round 1 Head)
+- **Head Commit**: `17eba0904ebbf54c1d2243ad61a6f2ba17263889` (1 commit)
+- **Tree Hash**: `a0f1ffede44be7c86267a56b25871e1d081feafb`
+- **Verification Path**: `/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1`
+- **Git Status**: Clean (working tree clean, no uncommitted changes)
+- **Whitespace Check (`git diff base...HEAD --check`)**: Clean (0 errors)
+
+---
+
+## 2. Commit Audit (base..head: `17eba09`)
+
+Commit `17eba09`: `docs(issue-42): review - attach names the herdr server, --dry-run is not "write nothing", a deleted block stays deleted`
+
+Files modified:
+- `.agents/skills/multi-agent-mux-create/SKILL.md` (lines: -2, +2)
+- `.agents/skills/multi-agent-mux-resume/SKILL.md` (lines: -6, +10)
+- `.agents/skills/multi-agent-mux-stop/SKILL.md` (lines: -1, +1)
+- `tests/data/skill_code_blocks.json` (lines: -8, +27)
+- `tests/test_issue42_skill_blocks.py` (lines: -2, +53)
+
+**Product Code Modifications**: None (0 changes to `.sh` or `.py` runtime scripts).
+
+---
+
+## 3. Review Item Verification
+
+### Item 1: Codex R1~R3 Resolution & Server Routing
+- **Codex R1 (Server Routing on Attach & Verification)**:
+  - Addressed across [`multi-agent-mux-resume/SKILL.md`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1/.agents/skills/multi-agent-mux-resume/SKILL.md):
+    - Case 3 (line 80): updated to `herdr --session <server> agent attach <name>`.
+    - Workflow explanation (line 89): clearly notes that native `herdr` does not route on ambient environment variables, requiring explicit `--session <server>` for manual attach.
+    - When NOT to use (line 130): `herdr --session <server> agent attach <name>`.
+    - Verification block (lines 108–121): reads `SERVER` from the row's `herdr_session` (falling back to `'default'` via `.get('herdr_session') or 'default'`) and invokes `herdr --session "$SERVER" agent get/read`.
+  - Confirmed via `herdr --help` that native `herdr` defines global syntax `herdr --session <name> [options]`.
+- **Codex R2 (`--dry-run` Semantics)**:
+  - In both [`multi-agent-mux-create/SKILL.md:58`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1/.agents/skills/multi-agent-mux-create/SKILL.md#L58) and [`multi-agent-mux-resume/SKILL.md:98`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1/.agents/skills/multi-agent-mux-resume/SKILL.md#L98), table entries now accurately document that `--dry-run` skips spawn and registry updates, but runs pre-spawn checks and strips macOS `com.apple.quarantine` attributes.
+- **Codex R3 (Deleted Body Anti-Reintroduction Guard)**:
+  - Implemented [`test_no_deleted_body_came_back()`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1/tests/test_issue42_skill_blocks.py#L271-L275) scanning all current blocks in all 8 `SKILL.md` files against `DATA["removed"]` and `DATA["superseded"]`.
+  - Independent of `DATA["blocks"]`: re-registering a deleted block under class `c` or `b` will still be detected and fail the test.
+  - Self-verification in [`test_a_returned_body_is_caught_reindented_and_with_the_inventory_updated()`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1/tests/test_issue42_skill_blocks.py#L277-L288) ensures both exact `base_sha` and re-indented `base_fingerprint` matches trigger failures.
+
+### Item 2: Robustness of Fingerprinting
+- Fingerprint definition: `hashlib.sha256(" ".join(body.split()).encode()).hexdigest()[:12]`.
+- Normalizes all internal whitespace and indentation, robustly detecting re-indented copies (e.g. within list items) without falsely flagging unrelated example blocks.
+
+### Item 3: Inventory Classification Integrity
+- Git diff of `tests/data/skill_code_blocks.json` shows only boundary shifts for the updated `resume` verification block (`start: 103, end: 128, sha: 8a468dfa43bd`). Its classification remains strictly `class: "b"`, `kind: "verification"`.
+- Added `base_fingerprint` fields to `removed` blocks.
+- Added `superseded` entry for the folded `create/SKILL.md` call block (`base_start: 263, class: "c", kind: "invocation"`).
+- No block's class or kind was changed.
+
+### Item 4: Scope & Documentation Refinements
+- **Claude O4**: Accurately documented `MAM_KILL_ON_READY_TIMEOUT=1` for create exit 42 and `--purge-conversation` exception for stop exit 0.
+- **Boundaries**: Strictly limited to documentation and test guard verification. Zero product code changes. Zero version bumps.
+
+---
+
+## 4. Test Suite Execution Results
+
+Executed in verification worktree (`/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261003T230658Z-e7866a/1`) with `--basetemp=/tmp/pytest-pr46-review2`:
+
+| Test Suite | Result | Duration |
+|---|---|---|
+| `tests/test_issue42_skill_blocks.py` | 31 passed, 1 skipped* | 0.06 s |
+| `tests/test_tier2_component.py` | 42 passed | 254.31 s |
+| `tests/test_orc_onboard.py` | 13 passed | 2.58 s |
+| `tests/test_loop_cli.py` | 20 passed | 37.66 s |
+| `tests/test_o1_rebuttal.py` | 11 passed | 1.87 s |
+| `tests/test_version_consistency.py` | 15 passed | 2.86 s |
+
+*\* Note: `test_claude_skills_link_resolves_to_agents_skills` skipped as expected in worktree context.*
+
+**Total Tested**: 132 passed, 1 skipped, 0 failed.
+
+---
+
+## 5. Conclusion
+
+All review feedback items (Codex R1~R3, Codex C1 / Claude O1, Claude O4) are resolved accurately and cleanly verified.
+
+[VERDICT: PASS]