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_STATUS but the flow engine read FLOW_STATE
  • 100 floating requirements (22%) created without --document/--section flags
  • 0/449 idempotency keys used despite template showing --idempotency-key
  • 100% hook failure rate — surrealdb-ingest failed every session (ENV_FILE unbound)
  • 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 links
  • reqs search --mode duplicates — find near-duplicate requirements before creation
  • reqs bulk-create — create multiple requirements from JSON array
  • lint --min-severity medium — filter out 122 low-severity acronym findings
  • diag render --clean — strip classDef/style lines from mermaid output

uht-substrate v0.5.2 → v0.6.0:

  • entities merge — merge duplicate entities, transferring all facts
  • entities reclassify — re-classify in place, preserving UUID and facts
  • facts 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

ComponentBeforeAfter
airgen-cliv0.13.0v0.14.0
uht-substratev0.5.2v0.6.0
Cooldown guardNone30-minute minimum
Cost trackingNonePer-session LAST_SESSION_COST fact
Mermaid fixHook only (post-build)Parser + hook (pre-build)
Duplicate detectionNonereqs search --mode duplicates before creation
Lint default--format text--format text --min-severity medium
Paging limits200500
FLOW_STATE in flowsdecompose onlyAll 5 flows
Review template5 sections8 sections (+subsystem, cross-domain, efficiency)
Git commits04 (initial + 3 improvements)
← all entries