Harness
Defines the constraints, tools, roles, environments, and quality gates that make engineering repeatable and failure visible.
Engineering is the system behind the products
Harness, Loop, and SDD are not product families. They are the three cooperating structures that turn a field problem into a tested increment, traceable evidence, an operable product, and reusable knowledge.
Loop
Moves intent through implementation, verification, observation, and learning—inside every FDE stage.
Living SDD
Links design intent to implementation facts, evidence, deviations, known issues, and reusable decisions.
Constraints outside, execution inside
An engineering harness is the complete environment that constrains, executes, verifies, and repeats work—not merely an AI coding tool or a document template.
Why a harness at all — why every incident has to become a rule:
千丈之堤，以蝼蚁之穴溃；百尺之室，以突隙之烟焚。
A dike a thousand zhang tall collapses through an ant hole; a house a hundred chi high burns down from a spark in a chimney crack. trans.
Han Feizi, *Yu Lao* (《韩非子·喻老》)
Outer constraint harness
Business Harness
- Users and field problems
- Value, scope, and success criteria
- Regulatory and operating constraints
- Available resources and feasibility
Technical Harness
- Domain model and architecture decisions
- Interfaces, protocols, and components
- Performance and safety invariants
- Deployment, observability, and recovery
Product Harness
- Deliverables and acceptance criteria
- Version and release status
- Known issues and deferred work
- Reusable assets and product profiles
Inner execution harness
Human + AI AgentsIntent, judgment, assisted execution
Repository + SDDVersioned code and shared contract
Tools + DiagnosticsBuild, analysis, instrumentation
Tests + ReviewBehavior, compliance, quality, safety
DeploymentControlled release and rollback
Field Telemetry + EvidenceObserved behavior and limitations
Harness boundary: it must make failure visible. Tool output stays traceable to code and environment; automated tests do not replace bench or field verification; deployment and telemetry remain engineering work; Human and AI Agents share the same review, evidence, and safety gates.
One delivery loop, one engineering loop
The outer loop reduces product risk. The inner loop makes every increment implementable, reviewable, observable, and correctable.
Choose and retire the field risk
Echo
Observe field reality→Delta
Prove the riskiest assumption→Product
Stabilize and deliver→New Field Echo
Observe field reality→Delta
Prove the riskiest assumption→Product
Stabilize and deliver→New Field Echo
Build each trustworthy increment
Specify→Implement→Test→Review→Deploy / Observe→Update SDD
Specify → Implement
Declare intent, constraints, interfaces, acceptance conditions, and required evidence. Build the smallest increment that can invalidate an assumption.
Test → Review
Use the verification method appropriate to the claim. Review specification compliance, code quality, safety boundaries, and factual wording.
Deploy / Observe → Update SDD
Collect operating behavior, performance, and failures. Feed decisions, deviations, evidence, and known issues back into the living contract.
Not a waterfall: Echo may build and test capture tools; Product may return to Specify after a field fault. The loops express feedback and evidence flow, not rigid phase gates.
The third loop: delivery and engineering move an increment through the repository. The field loop (§03.5) is what carries a user symptom in — and, since 2026-09-19, a tested patch back out.
The loop that touches the user
FDE's fourth loop practice: the support chain iterating on itself. A 🐞 report becomes cited evidence, a public answer, a board card — and, for scheduled bugs, a tested patch waiting for a human yes.
Report → triage → classify → answer/board → implement → human merge
Report
Redacted diagnostics bundle→Triage
10-minute cron, read-only model→Classify
bug · feature · noise→Answer + Board
Public, searchable, line-cited→Implement
Single-flight, test-gated→Human merge
main is never touched unattended
Redacted diagnostics bundle→Triage
10-minute cron, read-only model→Classify
bug · feature · noise→Answer + Board
Public, searchable, line-cited→Implement
Single-flight, test-gated→Human merge
main is never touched unattended
| Classification | Automatic action | Boundary |
|---|---|---|
| noise — environment / false alarm / already-fixed signature | Answer the user; board column answered — terminal | No code work; the answer already exists on the public answers page |
| bug — a locatable product defect | Answer the user and auto-schedule into the unattended implementation queue | Fixing is a verification problem, not a product choice |
| feature — new capability / parameter | Answer the user; board column backlog | Scheduling is a product decision; the operator decides |
| need_more_info | Never closes — stays in the backlog | An un-answered report must not pretend the loop closed |
Safety rails
Read-only model; patch delivered as a unified-diff JSON contract; protected paths (tooling-guard JS, certs/, win/, packaging/, .iss) refused; at most 8 files per patch; git apply --check first.
Isolation
The patch applies only on a fresh fde/<id> branch from a clean main worktree. main is never touched by an unattended process; merging is a human act.
Test gate
The full unittest suite decides: green commits to the branch (the board records branch@hash plus the test line); red deletes the branch, restores the worktree, and records the reason.
Two incidents that hardened the loop: a cron model runner dying with SIGABRT for two days (a Homebrew upgrade broke the bottled Node's dylib linkage — the loop now names its own signal deaths), and a test fixture that shipped to the live board (fixed by making page shipping one patchable seam; a full test run now leaves the live page byte-identical). An unattended loop must make its own failures visible.
The boundary: the loop used to end at an answered ticket, then at a shipped fix; it now ends at a reviewed branch. Judgment stays human in two verbs — decide (one scheduling note per feature) and merge (accept a tested branch). Evidence decides whether a contract survives; the "does it count" verdict is never delegated. Live surfaces: the FDE board and the answers page; the operator surface is three commands —
fde_board.py list|decide|implement.A cadence stack, not a single loop
Triage · 10 min → Answer · same day → Implement · hours (single-flight) → Release · days → Immunity · permanentA system's learning rate is set by the fastest loop able to capture each class of incident. The field loop adds the outermost period: the classes that never appear inside the repository — sound-card-less VMs, USB re-enumeration, macOS permission dialogs, Gatekeeper.
SDD connects intent to engineering fact
A Software Design Document guides implementation and is corrected by implementation. Planned architecture and observed maturity remain explicit, never blended.
DESIGN DIRECTION
Intent · Constraints · Decisions
Why the system exists, what boundary it owns, which quality attributes matter, and why one architecture was chosen over another.
→ SDD ←
IMPLEMENTATION FACT
Code · Tests · Deployment · Field Evidence
What exists, how it was verified, where it operates, what failed, and which limitations remain open.
Explicit lifecycle states
plannedSpecified, not yet implemented.
implementedExists in code; verification remains bounded.
testedPassed named automated or simulation tests.
bench-verifiedVerified with physical hardware on a bench.
field-verifiedObserved in the intended operating environment.
releasedPublicly released or operational.
deferredExplicitly postponed with scope visible.
known-issueKnown gap; never represented as complete.
No automatic promotion: 1897 automated tests do not prove every radio in the field; a passing server does not close a native-client PTT defect; finished firmware does not verify a PCB or RF bench.
Minimum evidence record
Claim · Source artifact · Version / commit · Environment · Verification method · Result · Limitations · DateWithout these fields, a status label is an assertion without provenance.
Three structures, one learning system
Harness constrains execution, Loop produces evidence and feedback, and SDD preserves the contract they continuously revise.
Harness without Loop
Tools and rules exist, but the system does not learn.
Loop without Harness
Iteration may be fast, but results are not repeatable or auditable.
SDD without Field Loop
The document becomes an outdated prediction.
Loop without SDD
Knowledge remains in individuals, terminals, or chat history.
Harness without SDD
Agents, tests, and deployment lack shared semantics and acceptance criteria.
One system, five different engineering boundaries
The matrix demonstrates how the same Engineering System adapts to each product family. It is not a ranking.
| Product family | Harness focus | Loop breakthrough | SDD role | Engineering evidence |
|---|---|---|---|---|
| MRRC Universal | Hamlib, server authority, Web/PWA | Field network and state-drift feedback | Stabilizes the universal radio boundary | Released and field-operational evidence |
| MRRC Direct USB | USB, model backends, client safety gates | FT-710 vertical validation → Modern platform | Extracts RadioBackend and RadioCapabilities | FT-710: 439 tests; Modern: 1897 tests. Physical-radio acceptance stays separate. FT710Mobile P0 PTT remains a known issue. |
| SunMRRC | Packet capture, DSP, media diagnostics, native client | Unknown protocol → Direct-IQ product | Keeps protocol, media, and safety contracts synchronized | Server, Web, and SunsdrMobile client evidence remain separate |
| MRRC-FT8 | Clock, audio, workflow state, TX guards | Field QSO cycles drive state-machine evolution | Separates public release from SDD V1.8 field evolution | Release evidence and later field evolution are not the same artifact |
| EFHW | Firmware, sensor, servo, RF bench | Bounded measurement–actuation search | Separates design, firmware, PCB, bench, and field states | V3.0 design/firmware complete; PCB and bench verification pending |
Evidence rule: capability and maturity are orthogonal. A feature can exist while field evidence remains incomplete; a released subsystem cannot lend its maturity to another client or hardware profile.
From ad hoc activity to reusable evidence
Maturity describes the engineering system, not product quality or team worth. Documentation volume and test counts alone do not advance a level.
Ad hoc
Knowledge lives in individual actions and temporary notes.
Repeatable
A basic harness and repeatable execution path exist.
Traceable
Specification, code, tests, release, and evidence can be linked.
Evidence-driven
Claims include source, environment, method, result, and limitations.
Reusable
Validated architecture, constraints, and assets transfer across products.
Failure modes that look like speed
Documentation replaces verification
A detailed SDD does not prove hardware behavior.
Test count replaces evidence
Coverage volume does not establish environment, scope, or physical acceptance.
AI generation replaces review
Fast output still requires specification, quality, safety, and provenance gates.
Release replaces field safety
A package can be published while a scenario or client remains unverified.
SDD stops receiving feedback
A contract that ignores implementation and field evidence becomes fiction.
Design target becomes “done”
Planned, implemented, tested, and field-verified are different statements.
Engineering appendices
SDD semantic map
Business Harness
- Executive Direction
- System Context
- Non-functional Requirements
- Use Cases
- Feasibility
Technical Harness
- Subject Area / Domain Model
- Architecture Decisions and Overview
- Service and Component Models
- Operational Model
Product Harness
- Project Definition
- Acceptance Criteria
- Version / Evidence History
- Known Issues
- Reusable Asset Catalog
Projects may use different chapter numbers. Semantic responsibility, lifecycle status, and evidence fields are the stable contract.
Minimum evidence record template
Claim:
Source artifact:
Version / commit:
Environment:
Verification method:
Result:
Limitations:
Date:Engineering review checklist
- Is the field problem and success condition explicit?
- Are authority, state ownership, interfaces, and safety constraints named?
- Does implementation match the SDD, or is the deviation recorded?
- Does each maturity claim identify method, version, environment, and limitation?
- Are automated, simulation, bench, field, and release results kept separate?
- Did deployment produce evidence or a new Echo that must update the SDD?
- Which result is reusable, and is the reuse relationship accurately classified?