NULNUL Harness

A project-aware AI coding harness for OpenAI Codex and Anthropic Claude Code.
Tell it what you want. NULNUL loads only the project capabilities that matter, verifies the work with real checks, remembers verified experience, and evolves only when evidence justifies change.

English · 한국어

Quick start · What it does · In action · Evidence · v3.2.0 release

Outcome first · Verify the result · Keep only what earns its place

Why NULNUL?

AI coding agents are powerful, but the project-specific setup around them tends to drift: rules get duplicated, skills accumulate, context goes stale, and “done” can mean “the model thinks it is done.”

NULNUL keeps that layer project-aware and evidence-driven.

If the existing project setup is already the strongest justified path, adding nothing is a correct result.

Quick start

Want to see the output first? NULNUL in Action collects a local booking UI/API demo, a synthetic research-workbook example, and the recorded 3.1.0 adoption of an existing project. Each case labels its evidence and limitations; these are not three independently verified customer projects or a new performance benchmark.

These installation commands target public v3.2.0, verified by fresh Claude and Meta adoption. Use a Codex or Claude Code build supporting plugin commands and follow its trust and permission prompts. A pinned installation does not automatically follow later releases.

OpenAI Codex

codex plugin marketplace add SeoNaRu/nulnul-harness --ref v3.2.0
codex plugin add nulnul-harness@nulnul-harness

Anthropic Claude Code

claude plugin marketplace add 'https://github.com/SeoNaRu/nulnul-harness.git#v3.2.0'
claude plugin install nulnul-harness@nulnul-harness

For first-time adoption, including a repository with an existing harness, ask:

Set up NULNUL for this repository, preserving its existing instructions and agent roles.
Then fix the booking API and verify that the existing behavior still passes.

For a project already using NULNUL, just ask for the work:

Fix the booking API and verify that the existing behavior still passes.

That is the intended normal workflow. You do not need to manually choose a Skill, create a Session, save Memory, pick an Agent topology, or run Evolution.

A task already covered by a complete local contract can stay on the Direct path. Installing the plugin does not force setup or durable Memory for every request.

Already pinned to an older public release? Remove that host’s old reference with codex plugin marketplace remove nulnul-harness or claude plugin marketplace remove nulnul-harness --scope user, then repeat its installation commands above. Start a new session and ask to upgrade the existing NULNUL setup while preserving project instructions and roles. A package update does not rewrite existing project entries automatically.

Upgrading an existing NULNUL project? The 3.0 foundation upgrade guide still applies; 3.2 does not change existing checkpoint shapes. If you maintain custom Setup Plans, each inspected existing role now needs a name: disposition entry rather than a bare name. Allowed dispositions are reuse, kept, upgraded, merged, and removed; kept normalizes to reuse.

Inspect this repository and show the strongest justified path for this task.
Explain what you would reuse, what you would omit, and why. Do not modify files.

What NULNUL does

1. Continues the project, not the chat

NULNUL keeps bounded Session, handoff, Experience, Decision, Lesson, and Open Thread state. A later session restores only relevant verified Memory instead of replaying the whole conversation.

Interrupted work is recovered without inventing completion.

2. Builds a task-fit Capability Pack

Before work starts, NULNUL selects capabilities for the strongest justified task outcome and verification. Only among materially equivalent outcome paths does it prefer lower context, coordination, runtime, maintenance, and permission cost. Capability or agent count is not the primary objective.

Task
  ↓
Project + relevant Memory
  ↓
Capability selection
  ↓
Pre-Session Capability Pack
  ↓
Work

A clear Direct task receives no capability body. A task-fit path receives only the selected body or bodies.

3. Verifies the result

NULNUL does not treat model confidence as proof.

Work
  ↓
Repository check / build / test
  ↓
Authoritative Check receipt
  ↓
Verified Experience

The check that matters is the project's actual check, not an agent-authored “looks good.”

4. Learns from verified Experience

Verified work becomes bounded Experience with provenance. Future sessions can retrieve relevant Experience, while raw transcripts stay out of normal Memory and Context.

5. Evolves only when evidence says it should

NULNUL does not constantly rewrite itself.

For capabilities, lifecycle decisions can be:

KEEP · UPGRADE · REPLACE · MERGE · RETIRE · CREATE

KEEP is a first-class decision. If there is no verified weakness, the current capability stays.

External candidates, Agent topology changes, Harness-control changes, and cross-project priors are all evidence-triggered rather than always-on maintenance work.

NULNUL in one flow

USER TASK
   ↓
SESSION + PROJECT CONTEXT
   ↓
RELEVANT MEMORY
   ↓
AGENT TOPOLOGY OPPORTUNITY
   ↓
CAPABILITY PACK
   ↓
WORK
   ↓
AUTHORITATIVE VERIFICATION
   ↓
EXPERIENCE
   ↓
MEMORY
   ↓
EVIDENCE-TRIGGERED EVOLUTION
   ├─ Capability Natural Selection
   ├─ External Capability Competition
   ├─ Agent Evolution
   ├─ Guarded Harness Evolution
   └─ Cross-Project Generalization

Simple outside. Inspectable inside. Ordinary tasks do not load the maintenance/evolution machinery when it is not needed.

A concrete example

User:

Add validation to the import endpoint and keep the existing error contract.

NULNUL can:

1. inspect the existing project contract and checks;
2. restore only relevant Memory;
3. select the project API-validation capability;
4. prepare that capability before work begins;
5. implement the change;
6. run the repository's authoritative validation command;
7. store the verified Experience;
8. reuse that Experience later when it is actually relevant.

The user still asked for one thing: the product outcome.

How NULNUL is different

NULNUL is not an agent-team generator, a giant prompt bundle, or a hosted orchestrator.

Evolution without churn

NULNUL separates several kinds of change instead of treating “self-improvement” as one unrestricted rewrite.

Capability Natural Selection

A project capability can stay, improve, be replaced, merge with another capability, retire, or be created from a verified uncovered need.

External Capability Competition

External candidates are treated as untrusted and quarantined before evaluation. They do not enter ordinary Pack selection merely because they exist.

In 3.1, the offline preparation helper packages inspected, pinned public Skill files for the existing local-directory quarantine path. It does not fetch, install, or automatically accept candidates. Remote marketplace superiority is not claimed.

Agent Evolution

Agent topology is about who owns which execution responsibility. Direct or single-agent execution is preferred when outcome-competitive. Additional bounded roles must materially improve specialization, context isolation, parallel work, or independent verification; one owner keeps final synthesis.

Guarded Harness Evolution

NULNUL separates a guarded Kernel from evolvable control policy. Evidence may justify bounded control tuning or replacement, but candidates cannot change their own evidence, promotion result, provenance, authority, or rollback rules.

Cross-Project Generalization

Cross-project reuse is opt-in and requires an existing local Personal Home chosen and approved by the user. Projects never copy raw Memory into one another. Only privacy-safe abstract priors with provenance and applicability boundaries are eligible; they remain subordinate to target-project truth and require compatibility and target validation. Public Meta adoption evidence covers its frozen selector and a bounded case, not universal transfer or live proof of every Generalization path.

3.2.0: focused task routing, executable host resume commands, complete installed-copy comparison, verified setup receipt reuse, stricter checkpoint evidence, and bounded Trace observability.

The public archive contains 65 files, 255,448 bytes, from product commit 59d366f7df3a6f0633317d563786caa6893ec109. Downloaded ZIP, release source and installed Claude files match. SHA-256: 95611e2f603c31f05d3be35b62aafa541b2ce86e93e2c27dfb050cf92f872bcb. These bounded checks establish neither universal routing nor comparative model performance or general runtime savings. Earlier nonpasses and frozen 3.1.0 evidence remain unchanged.

The skill entry now puts ordinary covered tasks first and routes setup, continuity, workflow and evolution details on demand. Its description is 244 characters and its entry is about 1,026 words; these are document sizes, not measured runtime gains. Required permission/check ownership and the verified checkpoint read/check boundaries are preserved. This user-directed documentation cleanup is separate from the closed experiment below.

Current local maintenance also reduces the developer entry to 615 words by moving subsystem-specific invariants into the development contract. Checkpoint rechecks invalidate old verification before execution, malformed fields fail closed, status requires matching ordered body evidence, and the non-Git documentation fallback scans once. Reproductions and validation describe these changes; frozen public-adoption results do not certify them.

A subsequent installed-copy and live-use check refreshed the stale local cache, completed a real receipt-schema correction, and recovered an interrupted check in a fresh Codex session. Each session ran its completion check once and passed all 12 checks. Both still listed files before checkpoint validation; an ineffective section reorder was restored, so fast-resume conformance and comparative speed are not claimed.

The three-upgrade follow-up adds executable host-entry commands and full installed-file comparison. Two fresh document/bug resumes validated the checkpoint before discovery and ran completion once; an interrupted check recovered safely. Local-only adoption preserved the original code and roles after an inventory guard repair. The full local suite passed 476 checks. Extra skill loading and an adoption recheck remain explicit limits; no comparative speed or public-release claim is made.

The instruction-routing evaluation ended with NO_PROMOTION after eight model attempts: the first evaluator was invalidated, and the repaired evaluator withheld acceptance for an unknown candidate event. This episode’s product and guidance changes were restored; only the verified local evaluator repair and rejection evidence remain. The frozen 3.1.0 evidence below is unchanged.

New in 3.1

The published 3.1.0 baseline added six task-delivery improvements without changing the 3.0 state formats, fast resume, acceptance authorities, or skills-only boundary:

1. Boundary QA: inspect actual producers and consumers, check integration incrementally, and retain a reproducible negative control.
2. Task recipes: web/API changes, data migration/sync, and evidence-backed research.
3. Execution patterns: six conditional patterns using existing roles and handoffs, without mandatory teams or fixed models.
4. Partial reruns: invalidate affected dependency chains and reuse only matching verified contracts and input/output fingerprints.
5. Skill acceptance cases: actual use, near-miss skips, and follow-ups, with authoritative check references.
6. Offline candidate preparation: prepare inspected pinned skill bytes for existing quarantine and competition, without fetching, installing, or granting adoption.

These references load only when needed. Planner receipts and development scores are advisory, not Foundation evidence, promotion authority, sealed holdouts, or proof of live quality gains. No new state migration is required.

Public adoption exposed three gaps, now repaired: installed-plugin bootstrap, cold-setup listing and document completion, and explicit role dispositions. Setup receipts bind the project, host, and executing package digests; the transaction rejects missing, duplicate, ambiguous, or unknown role dispositions. No shadow skill, extra state writer, protected-path write, or checkpoint migration is required. The fresh fourth public run passes without relaxing the validator. Earlier failures and their prerelease archives remain preserved; these are release regressions, not sealed holdouts or a universal quality-gain benchmark.

python3 plugins/nulnul-harness/skills/nulnul-harness/scripts/workflow_delivery.py demo

Evidence

The results below certify the frozen 3.1.0 release on 2026-09-08, not every subsequent working-tree change. Suite counts refer to the clean publication tree. New delivery helpers have deterministic coverage, not a claimed live quality advantage.

One previously frozen live Direct pair kept the NULNUL path within the project's preferred <=120% input target while preserving zero capability bodies for a clear Direct task. This is historical, scoped evidence, not a new 3.1 live benchmark or a universal performance guarantee.

Evidence discipline

The following distinctions matter:

• Live-proven: core Session/Pack/Check/Experience/Memory continuity and the Skill KEEP path.
• Implemented and deterministically validated: broader lifecycle mechanics such as non-KEEP capability changes, Agent Evolution, Harness Evolution, and Generalization.
• Not claimed: globally optimal capabilities, universal multi-Agent superiority, recursive self-evolution, or universal cross-project best practices.

Safety and privacy

NULNUL keeps the important boundaries explicit:

• Repository-local operation: no NULNUL server or daemon is required.
• Raw evidence stays local-only: raw transcripts/runtime events are not normal durable Memory.
• Project Memory stays isolated: cross-project transfer uses abstract priors, not source-project Memory copies.
• External candidates are quarantined: discovery does not grant authority or execute untrusted install behavior.
• Capability context is not authority: loading a Skill does not grant structural project/Harness write permission.
• Authoritative checks stay deterministic: model-authored success does not replace check receipts.
• Mutations are transactional: lifecycle changes validate, preserve provenance, and roll back on failure.
• Host trust remains host/user-owned: NULNUL does not silently take over host trust.

Read SECURITY.md and PRIVACY.md for the full boundaries.

What NULNUL may add to a project

NULNUL prefers reusing the project that already exists. Durable state is added only when it has a job.

Typical managed surfaces include:

• AGENTS.md or CLAUDE.md managed guidance for the active host;
• docs/nulnul/project.md for stable project facts and checks;
• bounded checkpoint / Session / Experience / Memory state under docs/nulnul/;
• a project-local Skill only when the current capability ecosystem does not already cover the job.

Only the active host's entry may change: Codex owns AGENTS.md, and Claude Code owns CLAUDE.md. Sequential adoption preserves the inactive entry and reuses the same shared contract with one live-state writer. Concurrent mutation of that state by both hosts is not supported.

The foundation migration and ownership rules remain documented in the 3.0 upgrade guide.

Inspectability

NULNUL is designed so the normal path stays small while the internal decisions remain inspectable.

Advanced inspection can answer questions such as:

• Why was this capability selected?
• Which project check ran?
• What verified Experience was stored?
• What Memory was restored in the next Session?
• Why did Evolution choose KEEP instead of changing something?
• Which capability/Agent/Harness version produced an outcome?

The durable records are provenance-linked; raw internal transcripts are not required for ordinary inspection.

Current limitations

NULNUL deliberately does not claim more than its recorded evidence supports.

• The Skill KEEP lifecycle has live evidence; a naturally occurring live Skill UPGRADE has not yet been observed in the public evidence set.
• External Capability Competition is implemented with bounded source/quarantine mechanics; there is no claim that NULNUL finds the best capability on the internet.
• Agent Evolution mechanics are implemented, but multi-Agent execution is not claimed to be universally better than Single-Agent execution.
• Harness Evolution is first-order and guarded; recursive unrestricted self-evolution is not supported.
• Cross-Project Generalization is privacy-gated and implemented, but universal transferability is not claimed.
• Host feature depth can differ between Codex and Claude Code; host-independent records do not imply perfect host parity.

These limitations are product boundaries, not hidden TODO claims.

Architecture details

Project Model
Session / Task
Context Assembly
Capability Selection
Pre-Session Capability Pack
Agent Topology
Verification
Observability
Experience
Memory
Provenance
Natural Selection
External Competition
Agent Evolution
Guarded Harness Evolution
Cross-Project Generalization

Verified Experience
        ↓
Evidence review
        ↓
No weakness? ─────────────→ KEEP
        ↓
Justified change
        ↓
Frozen Challenger
        ↓
Champion vs Challenger
        ↓
Verification + holdout + rollback gate
        ↓
Promote or reject

Release and upgrade

• Current package: NULNUL 3.2.0, with exact-version public Claude and Meta adoption.
• Verified baseline: NULNUL 3.1.0
• Upgrade guide: docs/upgrade-3.0.md, unchanged checkpoint shapes in 3.1 and 3.2.
• Changelog: CHANGELOG.md
• Security: SECURITY.md
• Privacy: PRIVACY.md

License

MIT — see LICENSE.

NULNUL + Trace: outcome evidence

Locally execution-validated integration candidate; not included in the frozen v3.1.0 release evidence. NULNUL projects its existing runtime records into a privacy-bounded, versioned contract for NULNUL Trace. The useful distinction is selected capability -> body loaded -> work -> authoritative check -> task outcome, with source digests, rather than more logs or inferred success.

Trace separates project configuration from observed use, checks receipt/file/command freshness and exposes checked outcomes, missing evidence and limited cost signals. It does not call another model, export transcripts, mutate the harness or claim an improvement percentage without a comparison. Token savings and fresh-resume success remain unmeasured. See the evidence contract.

Seeing Harness work in Trace

1. Use the updated Harness producer with a new Foundation task. Setup alone and older sessions do not create runtime evidence; an unchanged installed plugin will not gain this integration automatically.
2. Run the matching Trace API, web app and collector. Apply the additional table with the existing pnpm db:push command when updating a database.
3. Open the session ticket, expand 하네스가 한 일, and choose 이번 세션 (this session) or 이 프로젝트 (this project). Selection, body loading and receipt-linked results are separate observations.

Local validation (2026-09-09)

The following records describe the integration at that time, separately from current 3.2.0 public release evidence.

• Trace tests: 71/71 passed (domain 48/48, collector 23/23); API and web builds passed.
• Deterministic integration smoke: 12 canonical runtime events, one task and one receipt-linked pass reached the collector, API and browser. Session/project scopes, receipt provenance and a 390px mobile viewport passed.
• API negative controls passed: replay deduplication, wrong project/session, private-field rejection, missing authentication and cross-device session/project isolation.
• Harness workspace: 447/448 passed; the remaining product-boundary failure is the pre-existing docs/research directory. It was not deleted or excluded to manufacture a pass.
• A separate publication-base copy was not green: 448 tests, 5 failures and 6 errors, including frozen-evidence source-identity mismatches. This is not clean release validation.
• Documentation-debt check passed. Release Gate still reports release_ready: false: exact-version public Claude and cross-project Meta adoption evidence does not cover the changed producer bytes.
• The smoke used synthetic data in a temporary DB schema, not an observed user or model trial. The temporary servers/schema were removed; existing sessions were untouched. Additional model calls: 0. No global plugin update, push or release was performed.

Request-first integration update (2026-09-09)

The Trace home screen now lists user requests with results, verification and next actions. 하네스가 한 일 distinguishes connected, absent, legacy and unbound runtime records; nulnul-trace doctor reports the local cause. The local installed Codex plugin was refreshed for this explicitly requested integration work.

An actual task in this coding session used trace-core-purity: selection, body loading and a passing Foundation receipt reached the running collector, API and browser. The earlier interrupted bootstrap remains a partial observation. This is one live development run, not a controlled model comparison or evidence of savings.

The source-state digest now follows Git-tracked and non-ignored untracked files, retaining tracked files even when ignored. Dependency and build trees no longer make bootstrap scan the entire worktree. The digest alone took about 2.1 seconds on the local Trace checkout; this is not an end-to-end performance benchmark. Added two regression checks. After repacking, the full Harness suite is 449/450 passed, with only the previously recorded docs/research product-boundary failure remaining. Frozen public release evidence is unchanged.

Operational visibility in 3.2

Ask what NULNUL is doing without opening Trace. The read-only view separates source identity, an explicitly inspected installation, host-session binding, task state, capability selection with its recorded reason, changes and verification evidence.

python3 plugins/nulnul-harness/skills/nulnul-harness/scripts/harness_status.py --root . --lang en

The host supplies its actual session key. Unknown binding is not inactivity; an explicit historical lookup is not current execution. An installed/enabled plugin entry is not proof that an already-open thread loaded the latest skill body. Recorded check exits and validated historical receipts are shown separately. No notification, extra model call, global installation or second state writer is added.

Repository research stays outside the product without being deleted. Packaging rejects legacy lab paths and symlinks inside the shipped plugin, while retaining normalized archive timestamps and permissions.

Local evidence and publication permission are separate commands:

python3 scripts/release_gate.py
python3 scripts/public_release_gate.py

The second command exits nonzero unless release_ready is exactly true. Main and pull requests targeting main use this strict gate; non-main candidates retain the local evidence gate. Frozen evaluator files and historical adoption hashes are not rewritten to make a changed candidate look certified.

The updated candidate passes all 481 repository checks. An actual Trace project repair now recognizes quoted verification paths; the original workspace passed its completion check after the reviewed two-file patch. The fresh metadata-only setup follow-up reused its existing receipt through two transactions with zero additional completion executions; the initial repeated-check failure remains recorded. Exact-public 3.2.0 Claude and Meta adoption also pass; release evidence is separate from these local observations. No comparative superiority is claimed.