spec hardening

---

title: Spec Hardening category: concepts tags: [harness, spec, layer-1, quality] status: developing created: 2026-04-28 updated: 2026-04-28 sources:

• "harness-implementation-plan" related:
• "agentic-harness"
• "structured-planning"
• "adversarial-verification" layer: "Layer_1" summary: Layer 1 blocks execution until every underspecified component of a request is resolved. Vague or untestable success criteria are flagged as ambiguities and must be cleared before proceeding. provenance: extracted: 0.85 inferred: 0.15 ambiguous: 0.0

---

Spec Hardening

Origin Principle

Block execution until every underspecified component is resolved. Ambiguity is a bug — if you can't write a test for it, it's not specified.

Flow

User request
    ↓
SpecHardener.harden(raw_request) → AI call → HardenedSpec
    ↓
Ambiguity gate: count blocking ambiguities with null resolution
    ↓
If blocking ambiguities > 0:
    → Return to user for resolution
    → Loop until zero blocking ambiguities (max_ambiguity_retries)
    ↓
Store HardenedSpec in .pi/harness/specs/<id>.json
    ↓
Emit: spec_hardened → Layer 2

HardenedSpec Data Contract

The output of spec hardening includes:

• intent_summary — what the user actually wants
• success_criteria — each must be testable (untestable criteria are flagged as ambiguities)
• anti_criteria — what the solution MUST NOT do
• ambiguity_flags — blocking or warning severity; blocking ambiguities halt the pipeline
• definition_of_done — single boolean expression
• scope_boundary — explicit in_scope and out_of_scope lists
• constraints — technical or domain constraints

AI Prompt Strategy

The spec hardening agent is instructed to:

• Be aggressive about flagging ambiguities — multiple reasonable interpretations = ambiguity
• Flag unverifiable success criteria as ambiguous
• Treat every success criterion as needing a test (if you can't write a test, flag it)
• Anti-criteria describe forbidden behaviors explicitly

Extension Interface

Type	Name	Description
Tool	harden-spec	Takes raw text, produces HardenedSpec
Tool	resolve-ambiguity	Takes spec_id + ambiguity_id + resolution
Tool	approve-spec	Human override to force-approve
Command	/harness-spec-status	Current spec status

Config

{
  "spec_hardening": {
    "max_ambiguity_retries": 3,
    "auto_resolve_warning": true
  }
}

auto_resolve_warning: automatically resolve warning-severity ambiguities with best-guess interpretation. Blocking ambiguities always require human resolution.

Files

• lib/harness-spec.ts — SpecHardener class, AI prompt construction
• extensions/harness-spec.ts — Extension: intercepts requests, runs hardening gate