Configuration control — post-review hardening, CLI upgrades, duplicate prevention
Summary
Comprehensive post-review hardening of the harness following analysis of sessions 341–378. Upgraded both CLIs with requested features, fixed all remaining hook failures, added guards against stuck loops and rapid re-entry, improved the decompose and review flows, and added pre-publish mermaid validation.
Review Findings (Sessions 341–378)
The surgical robot decomposition ran 31 sessions over ~18 hours, producing 449 requirements, 415 trace links, and 11 diagrams. Total cost: $38.77. Key findings:
- 15 wasted sessions (360–374) from a stuck state machine: Claude set
DECOMPOSITION_STATUSbut the flow engine readFLOW_STATE - 100 floating requirements (22%) created without
--document/--sectionflags - 0/449 idempotency keys used despite template showing
--idempotency-key - 100% hook failure rate — surrealdb-ingest failed every session (
ENV_FILEunbound) - 13 rapid re-entries with sub-30-minute gaps between sessions
- Quality U-curve: strong in sessions 350–354, formulaic 360–365, strong again 371–378
Changes
CLI Upgrades
airgen-cli v0.13.0 → v0.14.0:
reqs reassign— move requirements between documents preserving ID and trace linksreqs search --mode duplicates— find near-duplicate requirements before creationreqs bulk-create— create multiple requirements from JSON arraylint --min-severity medium— filter out 122 low-severity acronym findingsdiag render --clean— strip classDef/style lines from mermaid output
uht-substrate v0.5.2 → v0.6.0:
entities merge— merge duplicate entities, transferring all factsentities reclassify— re-classify in place, preserving UUID and factsfacts store-bulk— bulk fact storage from JSON array
Harness Improvements
Cooldown guard: 30-minute minimum between sessions. Prevents the 13 sub-30-minute re-entries observed in sessions 341–378.
Cost tracking: LAST_SESSION_END and LAST_SESSION_COST stored as Substrate facts after each session for trend analysis.
Pre-publish mermaid fix: OutputParser.fixMermaidFences() closes unclosed fences and strips classDef/style lines at parse time — before the file is written. This catches the issue at the source rather than relying solely on the post-session hook.
surrealdb-ingest fix: ENV_FILE now defaults to /opt/claude-harness/.env instead of failing on set -u when unset.
Flow Improvements
FLOW_STATE in all flows: Every flow (scaffold, decompose, qc, validate, review) now sets FLOW_STATE alongside DECOMPOSITION_STATUS. The stuck-loop bug from sessions 360–374 cannot recur.
Duplicate detection: Decompose flow now instructs Claude to run airgen reqs search --mode duplicates before creating each requirement. Near-duplicates should be updated, not recreated.
Lint filtering: All lint calls use --min-severity medium. The 122 low-severity acronym findings that consumed session time are now filtered out.
Paging limits: All --limit 200 bumped to --limit 500. Prevents the session 366 bug where 88 existing VER entries were missed due to paging.
Diagram rendering: Protocol updated to use airgen diag render --clean, eliminating classDef lines at source.
Review Template
SE_REVIEW journal template expanded with three new sections:
- Per-Subsystem Summary — table of subsystem → requirement count → trace count → diagram status
- Cross-Domain Insights — table of analogs found and gaps they surfaced
- Efficiency — total sessions, cost, wasted/redundant sessions
Added structural check: airgen reqs list | jq '[... | select(.documentSlug == null)] | length' must return 0 before marking complete.
Floating Requirements
99 of 100 REQ-SESURGICALROBOT-* requirements reassigned to correct documents using airgen reqs reassign. 65 → verification-plan, 34 → subsystem-requirements. 1 was already deleted.
Version Manifest
| Component | Before | After |
|---|---|---|
| airgen-cli | v0.13.0 | v0.14.0 |
| uht-substrate | v0.5.2 | v0.6.0 |
| Cooldown guard | None | 30-minute minimum |
| Cost tracking | None | Per-session LAST_SESSION_COST fact |
| Mermaid fix | Hook only (post-build) | Parser + hook (pre-build) |
| Duplicate detection | None | reqs search --mode duplicates before creation |
| Lint default | --format text | --format text --min-severity medium |
| Paging limits | 200 | 500 |
| FLOW_STATE in flows | decompose only | All 5 flows |
| Review template | 5 sections | 8 sections (+subsystem, cross-domain, efficiency) |
| Git commits | 0 | 4 (initial + 3 improvements) |