@alsania-io/self-improve

Validated self-improvement gate for Alsania agents.

Turns evidence into durable behavior change through three mechanisms:

1. Start Packet — six items stated before editing durable guidance.
2. 7-state machine — every run ends in exactly one state.
3. Falsifiable proof rule — applied requires a runnable command or a re-read of the changed file. "verified"/"looks good" are invalid.

This gate is agent-attested, not tool-enforced. It works only if the agent runs it honestly. Faking a proof line is a Code v3.0 violation.

Install

npm install @alsania-io/self-improve

Quick start

import { runGate, validateProof, computeConfidence } from '@alsania-io/self-improve';

const state = runGate({
  id: 'l1',
  state: 'candidate',
  packet: {
    futureBehavior: 'use read+write for backups',
    representativeTask: 'back up aegis-boot.md',
    evidence: 'data loss from move_file across devices',
    owner: 'alsanian-enhanced',
    writeBoundary: 'skills/alsanian-enhanced/SKILL.md',
    proof: 're-read of SKILL.md',
  },
  confidence: computeConfidence(4, false),
  repeats: 4,
  hasFocusedTest: false,
  proof: { kind: 're-read', value: 'SKILL.md' },
  manifest: {
    editType: 'modify_skill',
    target: 'alsanian-enhanced',
    intendedEffect: 'prevent backup data loss',
    predictedImpact: 'lift backup reliability',
  },
  createdAt: new Date().toISOString(),
});
// => 'applied'

The 7 states

| State | Meaning | |---|---| | candidate | Reusable, not yet validated. Default outcome. | | validated | Evidence supports it; no owner changed yet. | | applied | Installed in ONE named owner, with a proof line. | | rejected | Disproved, unsafe, too specific, or obsolete. | | superseded | A prior applied/validated lesson was replaced. | | no-delta | No reusable behavior change found. | | open-question | Evidence insufficient; the missing proof is named. |

API

Types (src/types.ts)

LessonState, parseLessonState, StartPacket, ProofLine, EditManifest, Lesson, RejectedEntry, EvolutionMarker, CorrectionMarker.

Classify (src/classify.ts)

• classifyLesson(lesson) → LessonState — the state gate.
• isPacketComplete(packet), missingPacketItems(packet).
• classifyFailure(output) → FailureCategory | null — count-guarded regex classifier.

Score (src/score.ts)

• computeConfidence(repeats, hasFocusedTest) → 0.0–1.0.
• isCritical(repeats) — true at ≥ 3 repeats.
• seriesSlope(values), classifyEpoch(history), safeScore(n), round3(n).

Validate (src/validate.ts)

• validateProof(proof) → { valid, reason? }.
• verifyAgainstEvidence(manifest, evidence) → CriticVerdict.

Top-level (src/index.ts)

• runGate(lesson) — full gate, returns the final state.
• toRejectedEntry(lesson, reason) — negative-feedback buffer entry.

Lineage (epic-harness)

Ported in spirit from /home/sigma/Desktop/insidedev/sigma-lab/epic-harness-main (Rust, MIT):

| epic-harness | here | |---|---| | shared/classify.rs | classifyFailure (count-guarded) | | evolve/metrics.rs | seriesSlope, classifyEpoch, safeScore | | evolve/edits.rs::EditManifest | EditManifest | | evolve/critic.rs::CriticVerdict | verifyAgainstEvidence | | RejectedEntry | RejectedEntry |

Not ported: Rust/SQLite/sqlx plumbing (storage is EME/Qdrant) and the HarnessX 9-dimension taxonomy (overkill for Phase 1).

Develop

make install
make test
make build

License

MIT. Imagined by Sigma. Powered by Echo.